Skip to main content

Twilio

Twilio is a cloud communications platform that provides programmable APIs for SMS, voice calls, video, WhatsApp messaging, and more. With Twilio, you can build powerful communication workflows including sending notifications, making automated calls, managing phone numbers, verifying users with OTP, and integrating WhatsApp business messaging into your applications.

Authentication Types​

Twilio supports 1 authentication method with two approaches:

  • API Key - Use Twilio API Keys (recommended for production) or Auth Token (for testing)
    • API Key approach (recommended):
      • Pros: More secure, can be revoked independently, supports granular permissions, production-ready
      • Cons: Requires creating an API key first
      • Best for: Production environments, team access, service accounts
    • Auth Token approach:
      • Pros: Quick setup, immediately available with account
      • Cons: Less secure (main auth token), cannot be revoked separately, full account access
      • Best for: Development, testing, personal projects

General Settings​

Before using the connector, you need to configure your Twilio Account SID:

  • Account SID - Your unique Twilio account identifier (starts with AC...). You can find this in your Twilio Console dashboard.

To use Twilio with API Keys (recommended for production):

  1. Log in to your Twilio Console at https://console.twilio.com

  2. Go to Account → API keys & tokens

  1. Click Create API key

  1. Enter a Friendly name for your API key (e.g., "Webrix Integration")

  2. Select Key type:

    • Main - Full account access (use with caution)
    • Standard - Full access except managing account and keys (recommended)
    • Restricted - Custom permissions per resource

  3. Click Create API Key

  4. IMPORTANT: Copy the API Key SID and API Key Secret immediately - the secret will only be shown once

  1. In Webrix, go to Integrations → New → Built-in

  2. Select Twilio and click Use

  3. Under General Settings, paste your Account SID (starts with AC...)

    • Find this on your Twilio Console dashboard

  4. Under Authentication Type, select API Key

  5. Paste your API Key Secret in the token field (the SID is not needed here - only the secret)

  6. Click Save Changes

tip

API Keys can be created with different permission levels. For most integrations, use a Standard API Key which has full access except managing the account itself. This provides good security while allowing all communication operations.

Setting up Auth Token Authentication​

To use Twilio with your Auth Token (simpler but less secure):

  1. Log in to your Twilio Console at https://console.twilio.com

  2. On the dashboard, find your Account Info section

  1. Copy your Account SID (starts with AC...)

  2. Click the eye icon to reveal your Auth Token, then copy it

  1. In Webrix, go to Integrations → New → Built-in

  2. Select Twilio and click Use

  3. Under General Settings, paste your Account SID

  4. Under Authentication Type, select API Key

  5. Paste your Auth Token in the token field

  6. Click Save Changes

warning

Your Auth Token provides full access to your Twilio account. Treat it like a password. For production use, create a separate API Key instead.

Phone Number Requirements​

When using Twilio tools, phone numbers must be in E.164 format:

  • Format: +[country code][number]
  • Examples:
    • US: +14155551234
    • UK: +447700900123
    • Germany: +4930123456

For WhatsApp:

  • Add whatsapp: prefix: whatsapp:+14155551234
  • Your "From" number must be a WhatsApp-enabled Twilio number

Common Use Cases​

Sending SMS Messages​

Use the Send SMS tool to send text messages:

{
  "to": "+14155551234",
  "from": "+14155556789",
  "body": "Your verification code is 123456"
}

Making Voice Calls​

Use the Create Call tool with TwiML:

{
  "to": "+14155551234",
  "from": "+14155556789",
  "twiml": "<Response><Say>Hello! This is an automated call.</Say></Response>"
}

WhatsApp Messaging​

Use the Send WhatsApp Message tool:

{
  "to": "whatsapp:+14155551234",
  "from": "whatsapp:+14155556789",
  "body": "Hello from WhatsApp!"
}

Phone Number Validation​

Use the Lookup Phone Number tool:

{
  "phoneNumber": "+14155551234",
  "type": "carrier"
}

Troubleshooting​

Invalid Phone Number Format​

Messages or calls fail with "Invalid phone number" error.

Cause: Phone number is not in E.164 format.

Solution:

  1. Ensure phone numbers start with + and country code
  2. Remove any spaces, dashes, or parentheses
  3. Examples:
    • ❌ Bad: (415) 555-1234, 415-555-1234, 4155551234
    • ✅ Good: +14155551234

Insufficient Account Balance​

Operations fail with "Insufficient funds" or balance errors.

Cause: Your Twilio account balance is too low or depleted.

Solution:

  1. Check your balance using the Get Account Balance tool
  2. Add funds to your Twilio account:
    • Go to Twilio Console
    • Navigate to Billing → Make a Payment
    • Add funds or set up auto-recharge
  3. For trial accounts, verify your phone numbers are in the allowed list

Geographic Permissions Error​

Sending messages or making calls fails with geographic restrictions error.

Cause: Your Twilio account doesn't have permissions for the destination country.

Solution:

  1. Go to Twilio Console → Settings → Geo Permissions
  2. Enable permissions for the countries you need to reach
  3. For SMS, go to Messaging Geo Permissions
  4. For Voice, go to Voice Geo Permissions
  5. Select the countries and save changes
tip

Some countries may require additional verification or documentation before you can enable them.

Rate Limiting Errors​

API requests fail with 429 (Too Many Requests) errors.

Cause: You've exceeded Twilio's rate limits for your account tier.

Solution:

  1. Twilio rate limits vary by service:
    • SMS/MMS: Typically 1-100 messages per second depending on number type
    • Voice: Typically 10-100 concurrent calls
    • Verify OTP: 60 requests per minute, 180 per hour
  2. Implement retry logic with exponential backoff
  3. Consider upgrading your account for higher limits
  4. For bulk messaging, use Messaging Services with queuing
  5. See Twilio Rate Limits Documentation

WhatsApp Template Requirements​

WhatsApp messages fail with "Template required" or similar error.

Cause: Trying to send a WhatsApp message outside the 24-hour customer service window without an approved template.

Solution:

  1. Within 24-hour window: You can send free-form messages to customers who contacted you first
  2. Outside 24-hour window: You must use approved WhatsApp Message Templates
    • Go to Twilio Console → Messaging → Content Templates
    • Create and submit templates for approval
    • Use approved template syntax in your messages
  3. See WhatsApp Business Policy

Authentication Failures​

API requests fail with 401 Unauthorized or authentication errors.

Cause: Invalid Account SID, API Key, or Auth Token.

Solution:

  1. Verify your Account SID is correct (starts with AC...)
  2. For API Key authentication:
    • Ensure you're using the API Key Secret (not the SID)
    • Check that the API Key hasn't been deleted or revoked
    • Verify the API Key has appropriate permissions
  3. For Auth Token authentication:
    • Get a fresh copy of your Auth Token from Twilio Console
    • Click the refresh icon if you recently changed it
  4. Check that you haven't exceeded authentication attempts (temporary lockout)

TwiML Errors in Voice Calls​

Voice calls fail or behave unexpectedly with TwiML errors.

Cause: Invalid or malformed TwiML XML syntax.

Solution:

  1. Validate your TwiML XML syntax
  2. Common TwiML elements:
    • <Say> - Text-to-speech
    • <Play> - Play audio file
    • <Dial> - Dial a number
    • <Record> - Record audio
    • <Gather> - Collect user input
  3. TwiML must be wrapped in <Response> tags
  4. Example valid TwiML: 
    <Response>
      <Say>Please press 1 for support</Say>
      <Gather numDigits="1" action="/handle-input">
        <Say>Press any key to continue</Say>
      </Gather>
    </Response>
  5. Test TwiML using Twilio's TwiML Bin

Message Not Delivered​

Messages show as "sent" but recipient never receives them.

Cause: Various delivery issues including carrier blocks, invalid numbers, or content filtering.

Solution:

  1. Use Get Message tool to check detailed status and error codes
  2. Common issues:
    • 30001-30007: Queue overflow - slow down sending rate
    • 30008: Unknown destination - invalid phone number
    • 30009: Missing segment - message fragmentation issue
    • 30034: Message blocked by carrier spam filters
  3. Check message status in Twilio Console → Monitor → Logs → Messages
  4. For recurring issues:
    • Register your use case with carriers
    • Use a toll-free number or short code
    • Avoid spam trigger words
    • Include opt-out instructions

Additional Resources​