Skip to main content

ToothFairyAI — Twilio SMS Integration Guide

This guide shows how to connect your ToothFairyAI agents to Twilio SMS services for automated text messaging.
Your agents will be able to receive SMS messages via webhook and respond automatically through Twilio's messaging API.

How it works (at a glance)​

SMS received → Twilio → Webhook → ToothFairyAI Agent → Response → Twilio → SMS sent:

  1. Twilio Setup: Create account, purchase phone number, configure messaging service
  2. Webhook Configuration: Set ToothFairyAI webhook URL in Twilio messaging service
  3. Channel Creation: Create SMS channel in ToothFairyAI with Twilio credentials
  4. Agent Configuration: Assign SMS channel to your agent and set phone number
  5. Agent receives SMS messages and responds automatically via Twilio
note

SMS messages are charged by Twilio according to their pricing. Check Twilio's pricing page for current rates.

Prerequisites​

  • A ToothFairyAI workspace (Chat agents only support channels)
  • A Twilio account with SMS capabilities
  • A purchased Twilio phone number
  • Agent configured in Chat mode (Operator, Assistant, or Programmer)
Phone Number Requirements

You must purchase a phone number from Twilio to send and receive SMS messages. Free trial accounts may have limitations on messaging capabilities.

Step 1: Twilio Account Setup​

1.1) Create Twilio Account​

  1. Go to twilio.com and create an account
  2. Complete the verification process
  3. Navigate to the Twilio Console Dashboard

1.2) Purchase a Phone Number​

  1. In the Twilio Console, go to Phone Numbers > Manage > Buy a number
  2. Select your country and desired capabilities:
    • ✅ SMS (required)
    • ✅ Voice (optional)
  3. Choose a phone number and click Buy
  4. Note down your purchased phone number (e.g., +1234567890)

1.3) Get Account Credentials​

  1. In the Twilio Console, go to Account > API keys & tokens
  2. Note down your Account SID (starts with AC...)
  3. Note down your Auth Token (keep this secure)
Security

Your Auth Token is sensitive information. Store it securely and never share it publicly.

Step 2: Create Messaging Service​

2.1) Create New Messaging Service​

  1. In Twilio Console, go to Messaging > Services
  2. Click Create Messaging Service
  3. Enter a friendly name (e.g., "ToothFairyAI Integration")
  4. Select Defer to sender's webhook as the use case
  5. Click Create Messaging Service

2.2) Add Phone Number to Service​

  1. In your messaging service, go to Sender Pool
  2. Click Add Senders
  3. Select Phone Number and choose your purchased number
  4. Click Add Phone Numbers

2.3) Configure Webhook URL​

  1. In your messaging service, go to Integration
  2. In the Incoming Messages section:
    • Webhook URL: https://api.toothfairylab.link/webhooks/twilio/{WORKSPACE_ID}
    • HTTP Method: POST
    • Replace {WORKSPACE_ID} with your actual workspace ID
Finding Your Workspace ID

Your workspace ID can be found in ToothFairyAI under Settings > General. It's a UUID format like 6586b7e6-683e-4ee6-a6cf-24c19729b5ff.

2.4) Save and Activate​

  1. Click Save Configuration
  2. Go to Properties tab and click Start Messaging Service

Step 3: Create SMS Channel in ToothFairyAI​

3.1) Navigate to Channels​

  1. Log into your ToothFairyAI workspace
  2. Go to Settings > Channels
  3. Click Create

3.2) Configure Channel Settings​

Fill in the following details:

  • Provider Name: Twilio SMS (or your preferred name)
  • Description: SMS integration via Twilio (optional)
  • Channel Type: Select SMS from dropdown
  • Provider: Select Twilio for SMS from dropdown
  • Token: Enter your Twilio Auth Token (from Step 1.3)
  • Account ID: Enter your Twilio Account SID (from Step 1.3)

3.3) Save Channel​

  1. Click Save to create the channel provider
  2. Note that ToothFairyAI will generate a unique webhook URL for this channel
Webhook URL Generation

After creating the channel, ToothFairyAI automatically generates the webhook URL that you configured in Step 2.3. This URL handles incoming SMS messages from Twilio.

Step 4: Configure Agent for SMS​

4.1) Select Your Agent​

  1. Go to Settings > Agents
  2. Select the agent you want to connect to SMS
  3. Make sure it's configured as a Chat agent (Operator, Assistant, or Programmer mode)

4.2) Configure Agent Channels​

  1. Scroll down to Agent Channels section
  2. Assign custom channels: Select your created Twilio SMS channel
  3. Phone number: Enter the Twilio phone number you purchased (e.g., +1234567890)
Phone Number Format for SMS

When entering the phone number, remove the + symbol. For example, if your phone number is +61468019327, enter it as 61468019327 in the phone number field.

  1. Delivery delay: Set delay between 0-120 seconds (optional, simulates human response time)
  2. New chat on received msg.: Enable if you want each SMS to start a new conversation

4.3) Save Agent Configuration​

Click Save to apply the SMS channel settings to your agent.

Step 5: Testing the Integration​

5.1) Send Test SMS​

  1. From any phone, send an SMS to your Twilio phone number
  2. Include a question or message for your agent
  3. Wait for the agent's response (plus any configured delivery delay)

5.2) Monitor in ToothFairyAI​

  1. Go to Chat with Agents in ToothFairyAI
  2. You should see the SMS conversation appear
  3. The conversation will show the SMS channel indicator

5.3) Check Twilio Logs​

  1. In Twilio Console, go to Monitor > Logs > Messaging
  2. Verify that messages are being sent and received successfully
  3. Check for any error messages or delivery failures

Advanced Configuration​

Message Templates​

You can customize how your agent responds by configuring:

  • Agent role and instructions: Set the agent's purpose and behavior
  • Default answer: Response when the agent can't find information
  • Goals: How the agent should fulfill its role

Multi-Channel Setup​

Your agent can handle multiple communication channels simultaneously:

  • SMS (this guide)
  • WhatsApp (via Twilio or Meta)
  • Email (via SendGrid or Amazon SES)

Each channel can have different phone numbers and settings.

Conversation Management​

  • New chat on received msg.: Creates a new conversation for each SMS
  • Long term memory: Agent remembers information across conversations
  • Summarized memory: Agent uses conversation summaries for context

Common Issues and Solutions​

IssueLikely CauseSolution
SMS not received by agentWebhook URL incorrectVerify webhook URL includes correct workspace ID
Agent not respondingChannel not assigned to agentCheck Agent Channels configuration
403 Webhook errorsInvalid credentialsVerify Auth Token and Account SID
Messages delayedTwilio queue issuesCheck Twilio message logs and queue status
Phone number not workingNumber not added to messaging serviceAdd phone number to Twilio messaging service sender pool

Success Checklist​

  • ✅ Twilio account created and phone number purchased
  • ✅ Messaging service created with phone number in sender pool
  • ✅ Webhook URL configured: https://api.toothfairylab.link/webhooks/twilio/{WORKSPACE_ID}
  • ✅ SMS channel created in ToothFairyAI with correct Twilio credentials
  • ✅ Agent configured with SMS channel and phone number
  • ✅ Test SMS sent and received response from agent
  • ✅ Conversation visible in ToothFairyAI Chat interface
Pro Tips
  • Test with multiple phone numbers to ensure reliability
  • Monitor Twilio usage and costs through their console
  • Configure appropriate delivery delays for natural conversation flow
  • Use agent instructions to handle SMS-specific scenarios (character limits, etc.)

Webhook URL Format​

For reference, the ToothFairyAI webhook URL format is:

https://api.toothfairylab.link/webhooks/twilio/{WORKSPACE_ID}

Where {WORKSPACE_ID} is your unique workspace identifier found in Settings > General.

This webhook handles:

  • Incoming SMS message processing
  • Message routing to the correct agent
  • Response formatting and delivery back to Twilio