Skip to main content

​
Twilio Integration

Twilio is the primary telephony provider for Crew, enabling voice calls, SMS messaging, and phone number provisioning. This guide covers setup, configuration, and best practices.

​
Overview

Crew uses Twilio for:
  • Voice calls — Inbound and outbound calling
  • SMS — Two-way text messaging
  • Phone numbers — Provisioning and management
  • Call recording — Optional call storage
  • Transcription — Speech-to-text

​
Prerequisites

Before connecting Twilio:
  1. Create a Twilio account
  2. Verify your account (required for outbound calls)
  3. Purchase at least one phone number
  4. Note your Account SID and Auth Token

​
Setup

​
Step 1: Get Twilio Credentials

1

Log into Twilio Console

Go to console.twilio.com
2

Find Account SID

Your Account SID is displayed on the dashboard
3

Get Auth Token

Click to reveal your Auth Token
4

Copy Credentials

Copy both values for the next step

​
Step 2: Connect to Crew

1

Open Crew Dashboard

Navigate to Settings → Integrations
2

Select Twilio

Click Connect next to Twilio
3

Enter Credentials

Paste your Account SID and Auth Token
4

Verify Connection

Crew will verify the credentials are valid

​
Step 3: Configure Webhooks

Crew automatically configures webhooks for your Twilio numbers. You can also configure manually: Voice Webhook URL: 
https://api.usecrew.ai/v1/twilio/voice/{crew_id}
SMS Webhook URL: 
https://api.usecrew.ai/v1/twilio/sms/{crew_id}
Status Callback URL: 
https://api.usecrew.ai/v1/twilio/status/{crew_id}

​
Phone Number Management

​
Viewing Numbers

See all Twilio numbers connected to Crew: 
curl https://api.usecrew.ai/v1/phone-numbers \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Assigning Numbers to Agents

{
  "phone_number": "+14155551234",
  "agent_id": "agent_sarah",
  "capabilities": ["voice", "sms"]
}

​
Purchasing New Numbers

Purchase numbers directly through Crew: 
curl -X POST https://api.usecrew.ai/v1/phone-numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "area_code": "415",
    "capabilities": ["voice", "sms"]
  }'

​
Voice Configuration

​
Inbound Calls

Configure how inbound calls are handled: 
{
  "inbound": {
    "agent_id": "agent_sarah",
    "fallback_agent_id": "agent_marcus",
    "recording": false,
    "transcription": true
  }
}

​
Outbound Calls

Configure outbound calling behavior: 
{
  "outbound": {
    "caller_id": "+14155551234",
    "machine_detection": true,
    "timeout": 30
  }
}

​
Call Recording

Recording regulations vary by jurisdiction. Ensure compliance with local laws.
{
  "recording": {
    "enabled": true,
    "channels": "dual",
    "format": "mp3",
    "storage_region": "us"
  }
}

​
SMS Configuration

​
Inbound SMS

Configure SMS handling: 
{
  "sms": {
    "agent_id": "agent_sms",
    "auto_reply": true,
    "session_timeout": 3600
  }
}

​
Outbound SMS

Send SMS via API: 
curl -X POST https://api.usecrew.ai/v1/sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "to": "+14155559999",
    "from": "+14155551234",
    "message": "Your appointment is confirmed for tomorrow at 2pm."
  }'

​
Twilio Subaccounts

For multi-tenant deployments, use Twilio subaccounts: 
{
  "twilio": {
    "type": "subaccount",
    "parent_account_sid": "AC...",
    "subaccount_sid": "AC...",
    "auth_token": "..."
  }
}

​
Error Handling

​
Common Errors

ErrorCauseSolution
21211Invalid phone numberVerify number format
21614To number not verifiedVerify trial account numbers
21610Blocked numberCheck Twilio blocklist
21606Geographic restrictionCheck account permissions

​
Webhook Failures

If Crew doesn’t receive calls:
  1. Verify webhook URLs are correctly configured
  2. Check Twilio webhook debugger for errors
  3. Ensure Crew API is accessible from Twilio
  4. Check for SSL/TLS issues

​
Security

​
Credential Storage

Crew stores Twilio credentials encrypted at rest using AES-256 encryption.

​
Request Validation

Crew validates all incoming Twilio requests using Twilio’s signature validation: 
// Crew automatically validates these signatures
X-Twilio-Signature: [signature]

​
IP Allowlisting

For additional security, allowlist Twilio’s IP ranges in your firewall.

​
Pricing

Twilio usage is billed directly by Twilio. Crew does not add markups.
ResourceTwilio Pricing
Local numbers~$1/month
Voice (inbound)~$0.0085/min
Voice (outbound)~$0.014/min
SMS (inbound)~$0.0075/message
SMS (outbound)~$0.0079/message
Prices vary by country and number type.

​
Best Practices

If serving multiple clients, use Twilio subaccounts for billing and access separation.
For outbound calls, enable answering machine detection to avoid wasted agent time.
Set up Twilio usage alerts to avoid unexpected charges.
Use Twilio’s trial mode for development and testing.

​
Troubleshooting

​
Calls not connecting

  1. Verify phone number is assigned to an agent
  2. Check webhook configuration in Twilio
  3. Review Crew logs for errors
  4. Test with a simple TwiML response

​
SMS not received

  1. Verify SMS capability on phone number
  2. Check message status in Twilio logs
  3. Verify carrier hasn’t blocked messages
  4. Check for spam filtering

​
Next Steps