Skip to main content

​
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 (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
  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 → 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

OptionDefaultDescription
EnabledOnToggle SMS on or off without deleting your configuration
Max Message Length1600Maximum characters per response (50-1600). Longer responses are truncated
Contact MatchingOffAutomatically match incoming phone numbers to existing contacts
Auto-Create ContactsOffCreate 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 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
  • Check your assistant’s model — faster models like Grok produce quicker responses

​
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

Need help?

Contact support for SMS setup assistance