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

# SMS Channel

> Two-way SMS messaging via Twilio with TCPA compliance and automated opt-out handling.

# SMS Channel

In addition to WhatsApp, Kaanha AI supports two-way SMS messaging via Twilio. SMS conversations appear in the same chat inbox alongside WhatsApp messages.

## Activating SMS

SMS is activated through your organization settings:

1. Go to **Settings → Connection**
2. Under the SMS section, select your country
3. Click **Activate SMS**

Your organization receives a dedicated Twilio phone number for inbound and outbound SMS messaging.

***

## Sending SMS

In the **Chat** inbox, use the **channel switcher** in the chat header to select **SMS** before sending.

Alternatively, the API accepts a `channel` parameter:

```http theme={null}
POST /api/conversations/[id]/messages
{
  "content": "Hi there! Your appointment is confirmed.",
  "channel": "sms"
}
```

SMS messages respect the contact's `smsOptedIn` flag — opted-out contacts will not receive SMS.

### MMS (Picture Messaging)

You can attach an image to an SMS send the same way you would a WhatsApp message — it goes out as MMS. This is only available for US/Canada numbers, since that's where Twilio supports MMS; outside that region, an attachment is silently dropped and the message sends as plain text instead.

***

## Receiving SMS

Inbound SMS messages are received via Twilio webhook:

```
POST https://app.kaanha.ai/api/webhooks/twilio/sms
```

Inbound SMS:

* Auto-creates a contact if not found (using the phone number)
* Creates or continues a conversation with `channel: "sms"`
* Appears in the Chat inbox alongside WhatsApp messages
* Routes through the chatbot system (AI agents, flow bots)

***

## TCPA Compliance

Kaanha AI handles TCPA-mandated opt-out keywords automatically:

| Keyword                                                   | Action                                                 |
| --------------------------------------------------------- | ------------------------------------------------------ |
| `STOP`, `STOPALL`, `UNSUBSCRIBE`, `CANCEL`, `QUIT`, `END` | Opt out — sets `smsOptedIn: false`, sends confirmation |
| `START`, `SUBSCRIBE`, `UNSTOP`, `YES`                     | Opt back in — sets `smsOptedIn: true`                  |
| `HELP`, `INFO`                                            | Auto-reply with support info                           |

Opt-out records include `smsOptOutDate` and are permanent until the contact opts back in.

> **Full Acceptable Use Policy:** see [/aup](https://app.kaanha.ai/aup) for the complete list of prohibited content categories, sender ID rules, and consent requirements.
>
> **Privacy details:** how SMS metadata is processed and retained is documented in [/privacy](https://app.kaanha.ai/privacy) (SMS section).

***

## SMS vs WhatsApp Opt-In

SMS opt-in (`smsOptedIn`) is **independent** of WhatsApp opt-in (`optedIn`):

* A contact can be opted in to WhatsApp but not SMS
* Opting out of SMS does not affect WhatsApp messaging

***

## Viewing SMS Conversations

In the **Chat** inbox:

* Conversations via SMS show a purple **SMS** badge in the conversation list
* The channel switcher shows **SMS** as the active channel
* Message bubbles are identical to WhatsApp messages

***

## Deactivating SMS

To release your SMS number and close the Twilio subaccount:

1. Go to **Settings → Connection**
2. Under the SMS section, click **Deactivate**
3. Confirm

This releases the phone number. **All SMS history is retained** in Kaanha AI — only the connection is removed.

***

## Related Channels

* **[Voice Agents](./voice-agents.md)** — telephony AI agents (Premium / Enterprise tier, currently rolling out). Same Twilio account is reused for voice if SMS is already active.
* **[WhatsApp Connection](./whatsapp-connection.md)** — primary messaging channel (Meta Cloud API)

## Disclosures

* AI-driven auto-replies on inbound SMS are governed by the [AI Disclosure / System Card](https://app.kaanha.ai/ai-disclosure). When an AI agent handles an SMS conversation, the model used and its limitations are documented there.
* Acceptable Use Policy: [/aup](https://app.kaanha.ai/aup)
* Privacy Policy (SMS section): [/privacy](https://app.kaanha.ai/privacy)