> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bubblav.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS (Twilio)

> Connect a Twilio phone number or Messaging Service to add AI chatbot capabilities to your customer support over SMS

Transform your SMS customer support with an intelligent AI chatbot that answers questions from your knowledge base automatically, 24/7.

<Note>
  The SMS channel is available on **all plans, including Free**. Human takeover in the unified inbox requires a **Pro** plan.
</Note>

## Why Connect SMS?

<CardGroup cols={2}>
  <Card title="Instant AI Responses" icon="zap">
    Customers get immediate answers based on your website's knowledge base
  </Card>

  <Card title="24/7 Availability" icon="clock">
    AI responds day and night, even when your team is offline
  </Card>

  <Card title="Human Takeover" icon="users">
    Support agents can jump into any conversation from the dashboard (Pro)
  </Card>

  <Card title="Reach Every Phone" icon="smartphone">
    SMS works on any phone. No app or internet connection is needed
  </Card>

  <Card title="Multi-Language" icon="globe">
    AI supports 100+ languages for international customers
  </Card>

  <Card title="Knowledge-Powered" icon="brain">
    Answers based on your website's content and documentation
  </Card>
</CardGroup>

## What Can the SMS Bot Do?

### Answer Customer Questions Instantly

Your customers can text questions about your products, services, or content:

**Example Questions:**

```text theme={null}
What are your business hours?
How do I track my order?
Tell me about your return policy
What payment methods do you accept?
```

### Provide 24/7 Support

* Responds instantly to common questions
* No waiting for business hours
* Reduces support ticket volume
* Consistent, accurate answers

### Human Agent Handoff & Unified Inbox

SMS conversations appear in your **Live Support** unified inbox alongside website widget and other platform conversations. Each conversation shows an SMS badge so you always know the source platform.

**How agent replies work:**

1. Go to **Live Support** in your dashboard
2. Find the SMS conversation (look for the SMS badge)
3. Click to open and type your reply
4. Your message is sent directly to the customer's phone
5. The AI remains paused while you're active in the conversation

The AI resumes automatically when you leave the conversation.

<Note>
  Agent replies are limited to **1600 characters**. Longer replies are rejected with a clear error message. Keep SMS replies short.
</Note>

## How AI Replies Work on SMS

SMS is a short, plain-text channel. AI replies follow these rules:

* **Short and plain**: The AI writes short, plain-text replies. There is no formatting, no buttons, and no images in AI replies.
* **4-segment cap**: Each AI reply is at most 4 SMS segments (see [Costs](#costs) below). Longer answers are cut to fit.
* **Daily cap**: Each sender gets at most **20 AI replies in any rolling 24-hour window**. Once a sender reaches the cap, the AI stays quiet for that sender until older replies fall out of the 24-hour window. Human agents can still reply from the inbox.
* **Media-only messages**: If a customer sends only photos or videos with no text, the AI does not run. When no agent is active, the sender has not opted out, and the sender is within the daily cap, BubblaV sends one fixed reply: "Sorry, I can only read text messages." When an agent is active, the message goes to the inbox and the agent answers.

## Prerequisites

* A **Twilio account** ([sign up free](https://www.twilio.com/try-twilio))
* A **phone number with SMS capability**, or a **Messaging Service** with at least one number
* For US traffic: **A2P 10DLC campaign registration** for local numbers, or **toll-free number verification**
* Active BubblaV account with a website
* Website with knowledge base content (crawled pages)

<Note>
  **Trial accounts**: Twilio trial accounts can only send messages to phone numbers you have verified in your Twilio account, and trial messages start with a trial notice. Trial accounts must also send Twilio template bodies, so AI replies (which use custom text) fail until you upgrade your Twilio account. Upgrade to message all customers and to send AI replies.
</Note>

## Setup Steps

<Steps>
  <Step title="Get your Twilio credentials">
    In the [Twilio Console](https://console.twilio.com/), copy your **Account SID** and **Auth Token** from the account dashboard.
  </Step>

  <Step title="Navigate to Integrations">
    Go to **Dashboard** → **Your Website** → **Integrations** and find the **SMS (Twilio)** card.
  </Step>

  <Step title="Click Connect">
    Click **Connect** to open the SMS connect dialog.
  </Step>

  <Step title="Paste your credentials">
    Paste the **Account SID** and **Auth Token**. BubblaV validates them and loads the phone numbers and Messaging Services on your Twilio account.
  </Step>

  <Step title="Choose a number or Messaging Service">
    Select one phone number, or one Messaging Service. If the number or service already has a webhook set by another app, BubblaV asks you to confirm the overwrite before it continues.
  </Step>

  <Step title="Verify Connection">
    The SMS integration should now show **Connected**. Open the configuration page to view the connected number or service.
  </Step>

  <Step title="Test the Bot">
    Send an SMS to your Twilio number to verify the AI responds correctly.
  </Step>
</Steps>

### Testing on a Trial Account

A trial account's "Try out SMS" sender is not listed by Twilio's API, so the connect dialog cannot show it. You can still test incoming messages:

1. In the connect dialog, choose **A phone number**. The list is empty on a trial — type the trial sender number (the "From" number on Twilio's **Try out SMS** page) in the **Trial sender number** field.
2. Connect. The configure page shows a **webhook URL**.
3. In the Twilio console, open **Messaging → Try out SMS → Receive an SMS**, set **Auto-Reply settings** to **Custom**, and paste the webhook URL.
4. Text your Twilio number from a verified phone. The message lands in your inbox and the AI turn runs. The reply itself fails with a Twilio error until you upgrade, because trial accounts can only send Twilio template bodies.

<Note>
  **Switching between a number and a Messaging Service** (or the other way) starts new conversation threads. Old conversations keep their history but no longer match the new channel.
</Note>

## Managing Your Integration

### View Connection Details

From the SMS configuration page, you can see:

* Connected phone number or Messaging Service
* Twilio account name
* Connection status

### Disconnect

To remove the SMS integration:

1. Go to **Dashboard** → **Your Website** → **Integrations**
2. Find the **SMS (Twilio)** card and disconnect it

**Note:** Disconnecting stops the AI from responding. BubblaV restores the webhook URL that was set on the number or service **before** you connected. Your Twilio configuration returns to its previous state.

## STOP, START, and HELP

SMS customers control their own consent:

* **STOP** (or STOPALL, STOP ALL, UNSUBSCRIBE, CANCEL, END, QUIT, REVOKE, OPTOUT): the customer is unsubscribed. The AI and human agents cannot send messages to an opted-out customer. The conversation shows an "Opted out of SMS" badge. STOP-class keywords always count, whether or not the customer is already opted out.
* **START** (or YES, UNSTOP): the customer is subscribed again. **START**, **YES**, and **INFO** count as keywords only while the customer is opted out. For a customer who is not opted out, a message like "YES" or "INFO" is a normal question and the AI answers it.
* **HELP**: the customer gets standard help text. HELP always counts as a keyword, whether or not the customer is opted out.

BubblaV records the opt-out in the conversation, on every Live Support ticket for that phone number, and on the customer's visitor profile. The opt-out therefore holds in both conversation and ticket views, and it stays in place if you change the connected number or Messaging Service. If BubblaV cannot read the opt-out state, it does not send.

Twilio handles these keywords automatically for **+1 (US/Canada) numbers**. For other numbers and Messaging Services, enable **Advanced Opt-Out** on the Messaging Service in the Twilio Console. We recommend Advanced Opt-Out for all Messaging Services, because it handles opt-out consistently across countries.

## Costs

You pay Twilio for every SMS you send. Twilio bills per **segment**:

* A segment is up to **160 characters** in **GSM-7** encoding (plain Latin text, single SMS).
* If the message contains characters outside GSM-7 (for example **Vietnamese text or emoji**), the message is sent as **UCS-2**. Then each segment holds only **70 characters**, and every character costs about **2.3× more**.
* Long messages are split into multiple segments and billed as such.

**Tips to save money:**

* Enable **Smart Encoding** on your Messaging Service in the Twilio Console. It replaces characters like curly quotes with GSM-7 equivalents when possible. BubblaV warns you at connect time when Smart Encoding is off.
* Keep AI replies short. The 4-segment cap also caps the cost per AI reply.

## Troubleshooting

| Problem | Cause | Fix |
| - | - | - |
| Error **20003 — Authenticate** | Account SID or Auth Token is wrong or was rotated | Copy fresh credentials from the Twilio Console and reconnect |
| Error **21610** | The customer opted out (STOP) | The customer must text **START** first. Agents cannot override opt-out |
| Error **21608** | Trial account, customer number not verified | Verify the customer's number in the Twilio Console, or upgrade your Twilio account |
| Error **30034** | US 10DLC number not registered | Register an A2P 10DLC campaign in the Twilio Console |
| Messages stop arriving | Another app overwrote the webhook URL | Reconnect BubblaV, or remove the other app's webhook on the number or service |

## FAQ

<AccordionGroup>
  <Accordion title="Do I need a developer to set it up?">
    No. Copy your Account SID and Auth Token from the Twilio Console, choose a number or Messaging Service, and BubblaV sets up the webhook automatically — no code required.
  </Accordion>

  <Accordion title="Can I use a Messaging Service instead of a single number?">
    Yes. Choose the Messaging Service at connect time. Note that switching between a number and a Messaging Service later starts new conversation threads.
  </Accordion>

  <Accordion title="Why did the AI stop replying to a customer?">
    Check the daily cap (20 AI replies per sender in a rolling 24-hour window), the opt-out badge on the conversation, or whether the customer sent only media. All of these pause AI replies. Human agents can still reply (unless the customer opted out). On a Twilio trial account, AI replies also fail because trial accounts can only send Twilio template bodies.
  </Accordion>

  <Accordion title="Can customers opt back in after texting STOP?">
    Yes. The customer texts **START** to your number. For +1 numbers, Twilio processes the keyword. For Messaging Services, enable Advanced Opt-Out in the Twilio Console.
  </Accordion>

  <Accordion title="Does the channel work on the Free plan?">
    Yes. The SMS channel works on all plans, including Free. Human takeover in the unified inbox requires a Pro plan.
  </Accordion>
</AccordionGroup>

## Next Steps

* Set up your [Live Support](/user-guide/live-support) to monitor conversations
* Improve your [Knowledge Base](/user-guide/knowledge) content for better answers
* Explore other [Integrations](/user-guide/integrations/overview) to connect more platforms


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.