Twilio WhatsApp Channel Setup

Connect your AI agent to WhatsApp using Twilio's messaging service, enabling business-grade WhatsApp conversations with your users.

Overview

A Twilio WhatsApp channel allows your agent to:

• Send and receive WhatsApp messages

• Support rich media (images, videos, documents)

• Reach users globally through WhatsApp

• Use either Twilio's sandbox (for testing) or a production WhatsApp Business number

Prerequisites

Before you begin, you'll need:

1. A Twilio account - Sign up at twilio.com

2. A Twilio phone number with WhatsApp capabilities (or access to the sandbox)

3. A published agent in your Stage5 project that you want to connect to WhatsApp

Understanding Twilio WhatsApp: Sandbox vs Production

Twilio offers two ways to use WhatsApp:

Sandbox Mode (Testing)

• Free to use for testing

• Allows you to test without a production WhatsApp Business number

• Limited to approved phone numbers you add to the sandbox

• Perfect for development and testing

• No approval process required

Production Mode

• Requires a verified WhatsApp Business number from Twilio

• Can send messages to any WhatsApp user

• Subject to WhatsApp Business API policies

• Requires application to WhatsApp Business API (Twilio handles this)

• Suitable for production use

We recommend starting with sandbox mode for testing, then moving to production when ready.

Step 1: Create a Twilio Account

1. Go to twilio.com

2. Sign up for a free account

3. Verify your email address and phone number

4. Complete the account setup process

Step 2: Get Your Twilio Credentials

1. Log into your Twilio Console

2. Go to the Dashboard - you'll see your Account SID and Auth Token

3. Save these credentials - you'll need them in Step 4:

   • Account SID: Starts with AC followed by 32 characters (e.g., AC1234567890abcdef1234567890abcdef)

   • Auth Token: A 32-character string (keep this secret!)

⚠️ Important: Your Auth Token is sensitive. Never share it or commit it to code repositories.

Step 3: Set Up WhatsApp (Sandbox or Production)

Option A: Using Sandbox (Recommended for Testing)

1. In your Twilio Console, navigate to "Messaging" → "Try it out" → "Send a WhatsApp message"

2. Follow the instructions to add your phone number to the sandbox

3. Send the join code from your phone to the sandbox number (usually [phone])

4. Once joined, you can test sending and receiving messages

5. The sandbox number will be your sender phone number (format: [phone])

Option B: Using Production (For Live Use)

1. In your Twilio Console, navigate to "Messaging" → "Senders" → "Messaging Services"

2. Create a new Messaging Service or use an existing one

3. Request a WhatsApp-enabled phone number or configure an existing number

4. Complete Twilio's WhatsApp Business verification process

5. Once approved, your verified phone number will be your sender

⚠️ Note: Production WhatsApp numbers require approval from Twilio and WhatsApp. This process can take time.

Step 4: Configure the Channel in Stage5

In your Stage5 project, in order to create or edit a channel manifest file, just instruct the assistant. For example: "Connect the Customer Support Agent to a Twilio WhatsApp channel. Make sure to have placeholders for all of the Secrets that are needed and I'll add them later." Behind the scenes the Stage5 Assistant will create it all, leaving you just to set the secrets.

What Gets Created

When you instruct the assistant, it will create a channel manifest file. The exact configuration depends on whether you're using sandbox or production mode.

Example for Sandbox Mode

{
  "kind": "channel",
  "version": "1",
  "channel": {
    "type": "twilio-whatsapp",
    "name": "Customer Support WhatsApp",
    "description": "AI assistant for customer support via WhatsApp",
    "agentManifestPath": "agents/support-agent.json",
    "twilioWhatsappOptions": {
      "accountSidSecretKey": "twilio-account-sid",
      "authTokenSecretKey": "twilio-auth-token",
      "useSandbox": true
    },
    "selfRegistrationForExistingUsersEnabled": true,
    "selfRegistrationForNewUsersEnabled": false
  }
}

Example for Production Mode

{
  "kind": "channel",
  "version": "1",
  "channel": {
    "type": "twilio-whatsapp",
    "name": "Customer Support WhatsApp",
    "description": "AI assistant for customer support via WhatsApp",
    "agentManifestPath": "agents/support-agent.json",
    "twilioWhatsappOptions": {
      "accountSidSecretKey": "twilio-account-sid",
      "authTokenSecretKey": "twilio-auth-token",
      "sender": "[phone]",
      "useSandbox": false
    },
    "selfRegistrationForExistingUsersEnabled": true,
    "selfRegistrationForNewUsersEnabled": false
  }
}

Required Secrets

You'll need to store these values as secrets in your project's Secret Vault:

• Account SID Secret Key - The name of the secret storing your Twilio Account SID (from Step 2). The assistant will use a placeholder name like twilio-account-sid, which you can change if needed.

• Auth Token Secret Key - The name of the secret storing your Twilio Auth Token (from Step 2). The assistant will use a placeholder name like twilio-auth-token, which you can change if needed.

Optional Settings

• Sender - Your WhatsApp-enabled phone number in E.164 format (e.g., [phone]). Required for production, optional for sandbox.

• Use Sandbox - Set to true if using Twilio's sandbox. Defaults to false.

Configure the required secrets. For more information see the "Storing Secrets" section.

Step 5: Publish Your Channel

1. Publish your channel to the desired environment (Production, Staging, etc.)

2. Stage5 will automatically configure the webhook with Twilio

3. For sandbox mode: You'll need to manually configure the sandbox webhook (see Step 6)

4. Your channel is now ready!

Step 6: Configure Webhook (Sandbox Only)

If you're using sandbox mode, you need to manually set the webhook:

1. After publishing, Stage5 will provide you with a webhook URL

2. Go to your Twilio Console → "Messaging" → "Try it out" → "Send a WhatsApp message"

3. Find the "Sandbox Configuration" section

4. Paste the webhook URL from Stage5 into the "When a message comes in" field

5. Set the method to "HTTP POST"

6. Click "Save"

For production mode, Stage5 automatically configures the webhook, so you don't need to do this step.

Step 7: Test Your Channel

1. Send a WhatsApp message to your Twilio number (for sandbox, this is usually [phone])

2. Your agent should respond within a few seconds

3. If you don't receive a response, check:

   • Your Account SID and Auth Token are correctly stored in the Secret Vault (see "Storing Secrets" section)

   • The webhook URL is correctly configured (for sandbox)

   • Your phone number is added to the sandbox (if using sandbox mode)

Configuration Options Reference

Channel Name

• Type: String

• Required: Yes

• Description: A descriptive name for your WhatsApp channel (e.g., "Customer Support WhatsApp")

Channel Description

• Type: String

• Required: Yes

• Description: Brief explanation of what this channel is for

Agent Manifest Path

• Type: String

• Required: Yes

• Description: Path to your agent manifest file (e.g., "agents/support-agent.json")

Account SID Secret Key

• Type: String (secret key name)

• Required: Yes

• Description: The name of the secret in your Secret Vault that stores your Twilio Account SID (starts with AC)

Auth Token Secret Key

• Type: String (secret key name)

• Required: Yes

• Description: The name of the secret in your Secret Vault that stores your Twilio Auth Token

Sender

• Type: String (phone number in E.164 format)

• Required: For production mode, optional for sandbox

• Format: Must be in E.164 format (e.g., [phone], [phone])

• Description: Your WhatsApp-enabled phone number. For sandbox, this is usually [phone]. For production, use your verified Twilio WhatsApp Business number.

Use Sandbox

• Type: Boolean

• Required: No

• Default: false

• Description: Set to true to use Twilio's WhatsApp sandbox for testing. When true, the channel can only send messages to phone numbers added to the sandbox. Set to false for production use with a verified WhatsApp Business number.

Self-Registration Options

See the main Channels documentation for details on:

• selfRegistrationForExistingUsersEnabled

• selfRegistrationForNewUsersEnabled

• selfRegistrationForExistingUsersDisabledMessage

• selfRegistrationForNewUsersDisabledMessage

• userDisabledMessage

• userDeletedMessage

Supported Message Types

Your WhatsApp channel can send and receive:

• Text messages - Plain text conversations

• Images - Photos and graphics (JPEG, PNG)

• Videos - Video files (MP4, 3GP)

• Audio - Voice messages and audio files (AMR, OGG, MP3, AAC)

• Documents - Files and documents (PDF, DOCX, etc.)

• Location - Geographic locations

• Contacts - Shared contact information

Phone Number Format

Twilio WhatsApp uses phone numbers in E.164 format, which means:

• Start with a + sign

• Include the country code

• No spaces, dashes, or parentheses

• Examples:

  • US: [phone]

  • UK: [phone]

  • Israel: [phone]

Sandbox Limitations

When using sandbox mode, be aware of these limitations:

• Approved numbers only: You can only send messages to phone numbers you've added to the sandbox

• 24-hour window: For numbers not in your sandbox, there's a 24-hour window to respond to user-initiated messages

• Testing purpose: Sandbox is intended for testing and development, not production use

• Manual webhook configuration: You need to manually set the webhook URL in Twilio Console for sandbox

Moving from Sandbox to Production

When you're ready to move to production:

1. Get a WhatsApp Business number:

   • Request a WhatsApp-enabled phone number through Twilio

   • Complete Twilio's WhatsApp Business verification process

   • This may take time as it requires approval

2. Update your channel configuration:

   • Set useSandbox to false

   • Add your sender phone number in E.164 format

   • Keep your Account SID and Auth Token the same (no need to change secrets)

3. Republish your channel:

   • Stage5 will automatically configure the production webhook

   • Test with your production number

   • You can now send messages to any WhatsApp user (subject to WhatsApp's business policies)

Troubleshooting

Bot Not Responding

• Check credentials: Verify your Account SID and Auth Token are correctly stored in the Secret Vault (see "Storing Secrets" section)

• Sandbox webhook: If using sandbox, ensure the webhook URL is configured in Twilio Console

• Phone number format: Verify your sender phone number is in E.164 format (e.g., [phone])

• Sandbox membership: If using sandbox, ensure your testing phone number is added to the sandbox

Invalid Credentials Error

• Account SID format: Must start with AC and be 34 characters total

• Auth Token: Should be 32 characters

• Check console: Verify credentials in your Twilio Console Dashboard

• Verify secrets: Ensure your secrets are correctly stored in the Secret Vault (see "Storing Secrets" section)

• Regenerate if needed: You can regenerate your Auth Token in Twilio Console if needed (under Account → Auth Tokens)

Webhook Not Receiving Messages

• Webhook URL: Verify the webhook URL is correctly set in Twilio Console

• HTTPS required: Ensure your webhook uses HTTPS (Stage5 handles this automatically)

• Check logs: Review Twilio webhook logs in the Console to see if requests are being sent

• Sandbox configuration: For sandbox, manually verify the webhook is set correctly

Messages Not Sending (Production)

• Business verification: Ensure your WhatsApp Business number is fully verified

• Rate limits: Check if you've hit Twilio's rate limits

• Message templates: For first-time contacts, you may need to use approved message templates (24-hour window applies after)

• Policies: Ensure compliance with WhatsApp Business policies

Phone Number Format Errors

• E.164 format: Phone numbers must be in E.164 format: +[country code][number]

• No spaces/dashes: Remove all spaces, dashes, or parentheses

• Country code: Always include the country code

• Examples:

  • ✅ Correct: [phone], [phone]

  • ❌ Wrong: [phone], 050-123-4567, [phone]

Best Practices

1. Start with sandbox: Always test in sandbox mode first before moving to production

2. Phone number validation: Ensure all phone numbers are in E.164 format

3. Monitor usage: Keep track of message volume and costs in Twilio Console

4. Error handling: Implement proper error handling for WhatsApp's business policies

5. Message templates: For production, be aware of WhatsApp's template message requirements for first-time contacts

6. Rate limiting: Be mindful of Twilio's rate limits and plan accordingly

7. Security: Never share or commit your Twilio credentials

Cost Considerations

• Sandbox: Free for testing

• Production: Twilio charges per message (both inbound and outbound)

• Review pricing: Check Twilio's pricing page for current rates

• Monitor usage: Keep an eye on your Twilio Console Dashboard for usage and costs

Security Considerations

• Protect credentials: Never share or commit your Account SID and Auth Token

• Use Secret Vault: Always store credentials in Stage5's Secret Vault, never in code

• Token rotation: Consider rotating your Auth Token periodically

• IP restrictions: For additional security, consider using Twilio's IP allowlisting features

• Monitor access: Regularly review access logs in your Twilio Console

Getting Help

If you encounter issues:

1. Check the Troubleshooting section above

2. Verify your configuration matches the examples

3. Review Twilio Console logs and webhook delivery reports

4. Ensure your phone number format is correct (E.164)

5. For sandbox issues, verify your number is added to the sandbox

6. For production issues, verify your WhatsApp Business number is verified and active

7. Contact Twilio support if issues persist