> ## 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 (Vonage)

> Connect a Vonage number 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 — using your own Vonage account.

<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 (Vonage)?

<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?
```

### 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 **10 SMS segments**. 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. 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.
* **Text-only inbound**: SMS inbound is text-only. If a customer sends photos or videos, they arrive on a different channel (for example MMS) and BubblaV does not process them as SMS.

## Prerequisites

* A **Vonage account** ([sign up free](https://dashboard.nexmo.com/sign-up))
* In the Vonage dashboard under **API Settings → Messaging API type**, select **Messages API**. Older accounts may still be on "SMS API (Legacy)" — with that setting, inbound SMS never reaches BubblaV
* Your **API key** and an **API secret** from the [Vonage API Settings page](https://dashboard.vonage.com/settings). Vonage shows a secret only once, when it is created. If you did not save yours, use **Create new secret** (your existing secret keeps working). A new secret can take a minute to start working
* The **signature secret** from the same page (**Signed Webhooks** section). Vonage signs every webhook with it and there is no API to fetch it, so you paste it at connect time
* An **SMS-capable virtual number** in your Vonage account (**Phone Numbers → Buy Numbers**). Trial accounts cannot buy numbers — upgrade the Vonage account first
* For US traffic: **10DLC campaign registration** in your Vonage account
* Active BubblaV account with a website
* Website with knowledge base content (crawled pages)

<Note>
  **Trial accounts**: Vonage trial accounts can only send messages to phone numbers you have verified in your Vonage account, and are limited to a low number of outbound messages per day. Upgrade to message all customers.
</Note>

<Note>
  **Only the linked number routes to BubblaV.** BubblaV links the one number you pick to its own Vonage application. Your other numbers and Vonage applications are never touched.
</Note>

## Setup Steps

<Steps>
  <Step title="Check your Vonage Messaging API type">
    In the [Vonage dashboard](https://dashboard.vonage.com/settings), open **API Settings** and confirm **Messaging API type** is set to **Messages API**. If it says "SMS API (Legacy)", switch it to Messages API first.
  </Step>

  <Step title="Get your Vonage credentials">
    On the same [API Settings page](https://dashboard.vonage.com/settings), copy your **API key**, your **API secret** (or create a new one), and your **signature secret**.
  </Step>

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

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

  <Step title="Paste your credentials">
    Paste the **API key**, **API secret**, and **signature secret**. BubblaV validates them and loads the SMS-capable numbers from your Vonage account.
  </Step>

  <Step title="Choose a sending number">
    Select one SMS-capable number as the sender. BubblaV creates a dedicated Vonage application named **BubblaV**, registers its webhooks, and links the chosen number to it. If the number is currently linked to another application, BubblaV relinks it and restores the previous link when you disconnect.
  </Step>

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

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

<Note>
  **Switching the sending number later** starts new conversation threads. Old conversations keep their history but no longer match the new channel.
</Note>

## Using Twilio, Telnyx, and Vonage Together

You can connect **all SMS providers at the same time** — for example a Twilio number for one market and a Vonage number for another. Each line keeps its own conversations. A **STOP** from a customer is shared: opting out on one SMS line opts them out on the other SMS lines too (per phone number).

## Managing Your Integration

### View Connection Details

From the SMS configuration page, you can see:

* Connected sending number and Vonage application
* Connection status

### Pause and Resume

Pausing the integration stops AI replies and removes the webhooks from the BubblaV application in your Vonage account. Resuming re-applies them. The number stays linked to the application.

### Disconnect

To remove the SMS integration:

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

**Note:** Disconnecting stops the AI from responding. BubblaV restores the link your number had **before** you connected (its previous application, or its per-number inbound URL) and deletes the dedicated **BubblaV** application. Your other Vonage applications are never touched.

## 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.
* **START** (or YES, UNSTOP): the customer is subscribed again.
* **HELP**: the customer gets a short help reply from BubblaV: "Your business name: reply STOP to opt out."

Vonage does **not** handle STOP, START, or HELP for SMS — BubblaV is the only opt-out enforcement. BubblaV records the opt-out in every SMS conversation of that phone number, on every Live Support ticket for that phone number, and on the customer's visitor profile. The opt-out is shared with connected Twilio and Telnyx lines for the same phone number. If BubblaV cannot read the opt-out state, it does not send.

## Costs

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

* A segment is up to **160 characters** in **GSM-7** encoding (plain Latin text, single SMS), up to **1530 characters** (10 segments) per message.
* 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:**

* Keep AI replies short. The 4-segment cap also caps the cost per AI reply.

## Troubleshooting

| Problem | Cause | Fix |
| - | - | - |
| Error **401** | API key or API secret is wrong or was rotated, or the secret was just created | Wait a minute after creating a secret. Otherwise create a fresh secret on the [Vonage API Settings page](https://dashboard.vonage.com/settings) and reconnect |
| Error **402** | Your Vonage account is out of credit | Top up your Vonage account balance |
| Error **422** | Invalid parameters (for example an invalid destination number) | Check the customer's phone number |
| Error **429** | Vonage is throttling your message rate | Wait and retry; contact Vonage if it persists |
| No inbound messages arrive | Vonage **Messaging API type** is "SMS API (Legacy)", or the number is not linked to the BubblaV application | Set Messaging API type to **Messages API** in Vonage API Settings, then reconnect BubblaV |
| Replies fail on a trial account | Trial accounts can only text verified numbers | Verify the recipient number in Vonage or upgrade |
| US sends fail | US long codes need 10DLC campaign registration | Register a 10DLC campaign in your Vonage account |

<Note>
  Vonage retries webhooks that are not acknowledged. BubblaV acknowledges immediately and deduplicates, so a retried message never produces a second AI reply.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="Do I need a developer to set it up?">
    No. Copy your API key, API secret, and signature secret from the Vonage dashboard, choose a sending number, and BubblaV creates the Vonage application and links the number automatically — no code required.
  </Accordion>

  <Accordion title="Can I connect Twilio, Telnyx, and Vonage at the same time?">
    Yes. Each SMS provider is a separate integration with its own number and conversations. A STOP on one line also opts the customer out on the other SMS lines.
  </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) or the opt-out badge on the conversation. Both pause AI replies. Human agents can still reply (unless the customer opted out).
  </Accordion>

  <Accordion title="Can customers opt back in after texting STOP?">
    Yes. The customer texts **START** to your number. Vonage does not keep its own block list for SMS, so only BubblaV enforces the opt-out.
  </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.