> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SMS Integration
> Enable AI-powered text messaging for your assistants with Twilio
## What is SMS Integration?
SMS Integration lets your IllumiChat assistants respond to text messages automatically. When someone texts your Twilio phone number, your assistant reads the message, generates a helpful response, and sends it back — all via SMS.
Perfect for:
* **Customer support**: Let customers text in for instant AI-powered help
* **Appointment reminders**: Respond to scheduling questions automatically
* **Lead engagement**: Capture and respond to inbound leads 24/7
* **Internal helpdesks**: Give employees quick answers via text
SMS Integration uses **Bring Your Own Key (BYOK)** — you connect your own Twilio account. Message and phone number costs are billed directly by Twilio.
## Getting Started
### Prerequisites
Before setting up SMS, you'll need:
1. An IllumiChat workspace with **Admin** access
2. A [Twilio account](https://www.twilio.com/try-twilio) (free trial works for testing)
3. A Twilio phone number with SMS capability
4. Your Twilio **Account SID** and **Auth Token**
### 1. Find Your Twilio Credentials
1. Log in to [console.twilio.com](https://console.twilio.com)
2. Your **Account SID** and **Auth Token** are on the dashboard homepage
3. Note your Twilio phone number (e.g., +15551234567)
Your Account SID starts with `AC` followed by 32 characters. Keep your Auth Token secret — treat it like a password.
### 2. Configure SMS in IllumiChat
1. Go to your assistant's **Settings**
2. Select **Channels** from the sidebar
3. Click the **SMS** card to open the SMS detail page
4. Enter your Twilio credentials:
* **Account SID**: Your Twilio Account SID (starts with `AC`)
* **Auth Token**: Your Twilio Auth Token
* **Phone Number**: Your Twilio number in E.164 format (e.g., `+15551234567`)
5. Click **Test Credentials** to verify the connection
6. Configure optional settings (see below)
7. Click **Save**
### 3. Set Up Twilio Webhooks
After saving your SMS configuration, IllumiChat provides webhook URLs that you need to add to Twilio:
1. On the SMS detail page, find the **Webhook Setup** section
2. Go to [Twilio Console](https://console.twilio.com) → **Phone Numbers** → **Manage** → **Active Numbers**
3. Click your phone number
4. In the **Messaging** section:
* Set **"A MESSAGE COMES IN"** to your **Inbound Webhook URL**
* Select **HTTP POST**
5. Click **Save Configuration**
Your IllumiChat instance must be accessible via HTTPS for Twilio webhooks to work. Webhooks will not work with localhost during local development.
### 4. Test It Out
Send a text message to your Twilio phone number. Within a few seconds, you should receive an AI-generated response from your assistant.
## Configuration Options
| Option | Default | Description |
| ------------------------ | ------- | ------------------------------------------------------------------------- |
| **Enabled** | On | Toggle SMS on or off without deleting your configuration |
| **Max Message Length** | 1600 | Maximum characters per response (50-1600). Longer responses are truncated |
| **Contact Matching** | Off | Automatically match incoming phone numbers to existing contacts |
| **Auto-Create Contacts** | Off | Create a new contact when an unknown number texts in |
SMS messages over 160 characters are split into multiple segments. Keeping responses concise helps reduce Twilio costs. The 1600 character limit allows up to \~10 SMS segments per response.
## How It Works
When someone sends a text to your Twilio number:
1. **Twilio receives the message** and forwards it to IllumiChat via webhook
2. **IllumiChat validates** the request using Twilio's signature verification
3. **A conversation session** is created (or resumed) for that phone number
4. **Your assistant generates a response** using its system prompt with SMS-specific guidelines
5. **The response is sent back** via Twilio as a text message
6. **The full conversation** is saved to your chat history for review
Your assistant automatically adapts to SMS by keeping responses concise and using plain text only — no markdown, code blocks, or complex formatting.
## SMS Analytics
Track how your SMS integration is performing from the **SMS Analytics** dashboard.
### Usage Metrics
* **Total Messages**: Inbound and outbound message counts
* **Segments Sent**: Total SMS segments (affects Twilio billing)
* **Delivery Rate**: Percentage of messages successfully delivered
* **Estimated Cost**: Approximate Twilio messaging cost
### Session Metrics
* **Total Sessions**: Unique phone numbers that have texted in
* **Active Sessions**: Currently active conversations
* **Contacts Matched**: Sessions linked to existing contacts
### Daily Breakdown
View message volume by day to identify trends and peak usage periods.
Access analytics from your assistant's **Channels → SMS** detail page. The analytics dashboard appears below the configuration form. Filter by time period: **7 days**, **30 days**, or **90 days**.
## SMS Sessions
Each unique phone number that texts your assistant creates a **session**. Sessions track:
* The phone number and conversation history
* Message count and timestamps
* Linked contact (if contact matching is enabled)
* Associated chat (viewable in your normal chat history)
Browse active sessions from the SMS detail page under **Channels → SMS** in your assistant settings.
## Contact Matching
When enabled, IllumiChat checks incoming phone numbers against your workspace contacts:
* **Contact Matching**: Links SMS sessions to existing contacts that share the same phone number
* **Auto-Create Contacts**: Automatically creates a new contact when an unrecognized number texts in
This helps you track which customers are reaching out via SMS and keeps conversations organized alongside your other contact interactions.
## Best Practices
Add SMS-specific instructions to your assistant's system prompt. For example: "When responding to customers, include a brief greeting and sign off with our company name."
While you can set up to 1600 characters, shorter responses (under 320 characters / 2 segments) are more natural for SMS and cost less.
Before sharing your SMS number publicly, text it yourself to make sure the responses are accurate and appropriately formatted.
Check your delivery rate and failed messages. A low delivery rate may indicate phone number issues or carrier filtering.
Enable contact matching to build a history of interactions. This makes it easier to follow up and provide context-aware support.
## Troubleshooting
### Not receiving responses
* Verify your Twilio credentials are correct using **Test Credentials**
* Check that SMS is **enabled** in your configuration
* Confirm webhook URLs are correctly set in the Twilio console
* Ensure your Twilio account has sufficient balance
* Check that the phone number has SMS capability
### Messages failing to deliver
* Check the **SMS Analytics** for error details
* Verify the recipient's phone number is valid
* Ensure your Twilio number is not flagged or suspended
* Check Twilio's [status page](https://status.twilio.com) for outages
### Delayed responses
* AI response generation typically takes 2-5 seconds
* Twilio delivery adds 1-3 seconds
* Long system prompts or complex queries may take longer
### Webhook errors
* Ensure your app URL uses HTTPS
* Verify the webhook URL matches exactly (no trailing slashes)
* Check that Twilio signature validation is passing — the webhook secret must match
Contact support for SMS setup assistance