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

> Connect a Telnyx messaging profile and 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 Telnyx 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 (Telnyx)?

<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.
* **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 **Telnyx account** ([sign up free](https://telnyx.com/sign-up))
* A **messaging profile** with **at least one phone number** assigned to it. Numbers without a messaging profile cannot send or receive messages
* An **API key** from the Telnyx portal (**API Keys** page)
* The **public key** from the Telnyx portal (**Public Key** page). Telnyx signs every webhook with it and there is no API to fetch it, so you paste it at connect time
* For US traffic: **10DLC brand and campaign registration** (TCR) in your Telnyx account
* Active BubblaV account with a website
* Website with knowledge base content (crawled pages)

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

<Note>
  **All numbers in the chosen messaging profile route to BubblaV.** The webhook is set on the profile, not on a single number. If you only want one number to reach BubblaV, put that number alone in its own profile.
</Note>

## Setup Steps

<Steps>
  <Step title="Get your Telnyx credentials">
    In the [Telnyx portal](https://portal.telnyx.com/), copy an **API key** from the **API Keys** page, and copy the **public key** from the **Public Key** page.
  </Step>

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

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

  <Step title="Paste your credentials">
    Paste the **API key** and the **public key**. BubblaV validates them and loads the messaging profiles and their numbers from your Telnyx account.
  </Step>

  <Step title="Choose a messaging profile and sending number">
    Select one messaging profile and one of its numbers as the sender. If the profile already has a webhook set by another app, BubblaV asks you to confirm the overwrite before it continues. Numbers not assigned to any profile are listed as not usable.
  </Step>

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

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

<Note>
  **Switching the messaging profile 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 Telnyx or 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 messaging profile and sending number
* Connection status

### Pause and Resume

Pausing the integration stops AI replies and restores the webhook URL that was set on the messaging profile **before** you connected. Resuming re-applies the BubblaV webhook. If another app took over the webhook in the meantime, resume reports a conflict instead of overwriting it.

### Disconnect

To remove the SMS integration:

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

**Note:** Disconnecting stops the AI from responding. BubblaV restores the webhook URL that was set on the messaging profile **before** you connected. Your Telnyx 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.
* **START** (or YES, UNSTOP): the customer is subscribed again.
* **HELP**: the customer gets a short help reply. If your messaging profile has its own HELP auto-response in Telnyx, Telnyx sends it and BubblaV sends nothing. Otherwise BubblaV sends "Your business name: reply STOP to opt out."

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. Custom opt-out keywords and AI opt-out detection that you set up in Telnyx count too: Telnyx marks the message, and BubblaV saves the opt-out. Telnyx also blocks sends to opted-out numbers itself (error `40300`). The opt-out is shared with a connected Twilio line for the same phone number. If BubblaV cannot read the opt-out state, it does not send.

## Costs

You pay Telnyx for every SMS you send. Telnyx 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 **10009 / 20008** | API key is wrong or was rotated | Copy a fresh API key from the Telnyx portal and reconnect |
| Error **47000** | US 10DLC campaign required | Register a brand and campaign (TCR) in your Telnyx account |
| Error **40300** | The customer opted out (STOP) | The customer must text **START** first. Agents cannot override opt-out |
| Error **40012 / 40001** | Destination number is invalid or not routable | Check the customer's phone number |
| Messages stop arriving | Another app overwrote the profile webhook | Reconnect BubblaV, or remove the other app's webhook on the messaging profile |
| Webhook signature rejected | The pasted public key does not match your account | Copy the public key again from the Telnyx portal **Public Key** page and reconnect |

<Note>
  Telnyx retries webhooks that are not acknowledged within 2 seconds, up to 3 times. 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 and public key from the Telnyx portal, choose a messaging profile and sending number, and BubblaV sets up the webhook automatically — no code required.
  </Accordion>

  <Accordion title="Can I connect Twilio and Telnyx 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 line.
  </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).
  </Accordion>

  <Accordion title="Can customers opt back in after texting STOP?">
    Yes. The customer texts **START** to your number. Telnyx also clears its own block list when the keyword is processed.
  </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.