You can connect your own chatbot to Community so it replies to Members who text you. Community sends each inbound message to your backend through a webhook, your backend decides whether the bot should answer, and the reply goes back to the Member through the Send Direct Message API.

What is Bring Your Own Bot

Bring Your Own Bot is a way to put a chatbot you build and control in front of the messages Members send you. Community doesn't host or run the bot. It moves messages in and out, and your system does everything in between.

A conversation works like this:

1. A Member texts you.
2. Community sends the message to your backend through the inbound message webhook.
3. Your backend stores the message and decides whether the bot should respond.
4. If it should, your backend sends the message and any context to your chatbot, which generates a reply.
5. Your backend sends the reply to the Member through the Send Direct Message API.

You need two things of your own:

Why should I use Bring Your Own Bot?

Members already text you with questions. A bot lets you answer common ones at any hour without someone watching the Inbox, and because you build it, you decide what it knows, how it sounds and when it stays quiet.

Because the bot runs on your own systems, you also keep the conversation history in your own database. You can use it for context in later replies, for your own reporting, or to hand a conversation to a person.

How do I use it?

Getting access

1. Confirm your plan includes Community Webhooks, Community API access and the Send Direct Message API. If you're not sure, email yourfriends@community.com or ask your account manager.
2. Ask your account manager to provision your account for the API. Your developer will need the credentials described in the Authentication Setup reference.

Setting up the inbound message webhook

1. In Community, go to Settings > Integrations > Webhooks.
2. Click Configure. If you don't see it, your account doesn't have webhook access yet. See Getting access.
3. Enter a name and your endpoint URL. The endpoint must use HTTPS and accept POST requests.
4. Under event types, select message.inbound. Select message.outbound too if you want your bot to know what you've recently sent (see How do I use it well?).
5. Save the webhook. Each webhook gets its own signature secret. Store it on your backend so you can verify that requests came from Community.

Your endpoint must return a 2xx response within 15 seconds. If it doesn't, Community retries. Do the slow work (calling your chatbot) after you've responded, not before.

The full payload and retry rules are in the Webhooks reference.

Building the backend

1. Receive the message. Read the Member and the message text from the webhook payload.
2. Ignore duplicates. Webhooks are delivered at least once, so the same message can arrive twice. Store each event ID for at least an hour and skip any you've already handled.
3. Store the message. Save it to your own database. You'll use this history for context, rate limits and session rules.
4. Decide whether to respond. Check the message against your entrance criteria (see Setting rules for when the bot responds). If it doesn't qualify, stop here.
5. Send it to your chatbot. Pass the message and any relevant context, such as recent conversation history. Your chatbot's instructions, knowledge base and response behavior are set up in your chatbot platform, not in Community.

Sending replies

1. Format the chatbot's reply as plain text.
2. Send it with the Send Direct Message API, using the Member's phone number and the reply text.
3. If the reply is longer than 400 characters, split it into several messages and send them in order.

The API has an option to send during quiet hours. Talk to your account manager before using it. Quiet hours exist to keep you compliant with messaging rules.

Setting rules for when the bot responds

Not every inbound message should get a bot reply. Before you go live, decide:

Community doesn't enforce these for you. Your backend has to.

Keeping your bot compliant and secure

Compliance. Your bot is sending messages on your behalf, so the same rules apply to it as to anything else you send.

• Keep replies informational and tied directly to what the Member asked.
• Don't send prohibited marketing content or misleading language, or anything else that could violate the TCPA or other messaging rules.
• Steer off-topic conversations back, or end them, rather than following them anywhere.

Security.

• Keep API keys, credentials and webhook secrets on your backend. Never put them in client-side code, logs or unsecured systems.
• Use environment variables, access controls and monitoring on the backend service.

How do I use it well?

Write for a text conversation. Replies should be short, conversational and easy to read on a phone. Instruct your chatbot to answer in a sentence or two rather than a paragraph, and to split anything longer into separate messages.

Let the bot know what you've sent. If you subscribe to the message.outbound webhook as well, your bot can see Campaigns and other messages that just went to a Member. That helps it avoid replies that repeat or contradict what you sent. Some outbound messages aren't included, such as automatic HELP, START and STOP responses.

Decide when the bot stays quiet, not only when it talks. A bot that answers everything will eventually answer something it shouldn't. Narrow entrance criteria and a clear rule for ending a session do more for the experience than a smarter model.

Common questions

Why did my bot's reply arrive hours later?

The most likely cause is quiet hours. Replies sent through the Send Direct Message API during quiet hours are held and delivered when quiet hours end. See Sending replies.

Why didn't my bot's reply get delivered?

Why is my bot replying twice to the same message?

Webhooks are delivered at least once, so your endpoint can receive the same message more than once, especially if it was slow to respond. Store each event ID and skip ones you've already handled. Also make sure your endpoint returns a 2xx response within 15 seconds. See Setting up the inbound message webhook.

Can I use ChatGPT for my bot?

Not the ChatGPT app. Use the OpenAI Platform API (platform.openai.com) or a similar service that your backend can call. See What is Bring Your Own Bot.

Where do I get an API key?

Your account has to be provisioned for the API by Community. Ask your account manager, or email yourfriends@community.com. See Getting access.