Twilio Communications Integration
Connect your Twilio account to give AI agents the ability to send SMS and WhatsApp messages, search message history, validate phone numbers, review voice call logs, verify identities, and monitor messaging spend - all with safety-first controls.
Overview
The Twilio Communications Integration provides AI agents with 7 tools for messaging, phone intelligence, voice call review, identity verification, and account management. Agents can send SMS and WhatsApp messages on your behalf, search message history and delivery status, validate phone numbers and detect carrier types, review call logs and recordings, send verification codes, and track usage spend.
Unlike purely read-only integrations, Twilio includes gated write tools for outbound messaging. Autonomous sends are disabled by default, and an admin must explicitly enable them before agents can send any messages. This safety-first approach ensures you maintain full control over outbound communications.
The integration connects via Twilio API Key credentials (not the master Auth Token), which are revocable, auditable, and recommended by Twilio for production applications. All 7 tools are bundled into a "Twilio Communications" tool group ready to assign to any agent.
Outbound voice calls are intentionally excluded from this integration. Agents can review call logs and recordings but cannot initiate new calls. This is a deliberate safety decision due to the high-risk nature of autonomous outbound calls.
Use Cases
- Customer Appointment Reminders - Agent sends an SMS reminder about an upcoming appointment with confirmation reply instructions
- Delivery Notifications - Agent sends order status updates and shipping notifications via SMS or WhatsApp
- Phone Validation Before Outreach - Agent checks whether a number is mobile or landline before attempting to text a customer
- Identity Verification - Agent sends a verification code via SMS, voice, WhatsApp, or email during sensitive operations
- Voice Call Log Review - Agent retrieves recent call history with a contact, including durations and timestamps
- Monthly Messaging Spend Analysis - Agent pulls usage summaries showing message counts and costs by category
- WhatsApp Template Messaging - Agent sends pre-approved WhatsApp templates for business-initiated conversations
How It Works
Admin connects Twilio 7 tools created Agents use tools
via API Key credentials in tool group during execution
| | |
v v v
+-----------------+ +---------------------+ +---------------------+
| Enter Account | | send_sms | | Send messages, |
| SID, API Key | --> | send_whatsapp | --> | search history, |
| SID, API Key | | search_messages | | validate numbers, |
| Secret | | lookup_phone | | review calls, |
| | | manage_calls | | verify identity, |
| | | verify_phone | | check usage |
| | | account_overview | | |
+-----------------+ +---------------------+ +---------------------+
Getting Started
Prerequisites
Before connecting Twilio:
- Pro Plus+ Subscription - The Twilio integration requires the
custom.twiliofeature code on your subscription - Twilio Account - You need an active Twilio account with at least one phone number provisioned
- Twilio API Key - Create an API Key in your Twilio Console under Account > API Keys. Note the API Key SID (starts with
SK) and Secret (shown only once at creation time) - Twilio Account SID - Found in Twilio Console under Account Info (starts with
AC) - Control Bridge Admin Access - You must be a Control Bridge administrator to configure the integration
Do not use your Twilio Auth Token for this integration. The integration requires an API Key, which is revocable and auditable. Your Auth Token is a master credential that should not be stored in external systems.
Step 1: Connect Twilio
- Navigate to Build > Connections > Twilio
- Click Connect Twilio
- Enter your Account SID (starts with
AC) - Enter your API Key SID (starts with
SK) - Enter your API Key Secret
- The system validates your credentials against the Twilio API and retrieves your account details
- Upon successful validation, your available phone numbers are loaded
- Select a Default Phone Number for outbound SMS (or leave it to auto-select the first SMS-capable number)
- Optionally enter a WhatsApp Number if you have a WhatsApp-enabled number
- Optionally enter a Verify Service SID (starts with
VA) if you want phone verification capabilities - Click Save Connection
Upon successful connection, 7 tools are created and bundled into a "Twilio Communications" tool group.
You can find your Account SID in the Twilio Console dashboard. To create an API Key, go to Account > API Keys > Create API Key. Save the API Key Secret immediately - Twilio only shows it once.
Step 2: Verify the Connection
After connecting:
- The connection page shows your account name, status, default phone number, and configuration
- Click Test Connection to verify the integration is working
- The system confirms the API key is valid and shows your account status and phone number count
Step 3: Configure Safety Controls
Before agents can send messages, you must decide on the autonomous sends setting:
- Locate the Safety Controls section on the connection page
- The Allow Autonomous Sends toggle is OFF by default
- When disabled, agents cannot send SMS, WhatsApp, or verification codes - they will ask for human escalation instead
- To enable autonomous sending, toggle the switch ON and confirm the dialog
When autonomous sends are enabled, agents can send SMS and WhatsApp messages without human confirmation. Messages incur per-message charges on your Twilio account. Only enable this after you are confident in your agents' instructions and Safety Gateway configuration.
Step 4: Assign the Tool Group to Agents
Twilio tools are bundled into a "Twilio Communications" tool group automatically created at connection time:
- Navigate to Build > AI Agents > Agents
- Edit the agent that should have Twilio capabilities
- Go to the Tools tab
- In the Tool Groups section, enable the Twilio Communications group
- Save the agent
All 7 Twilio tools are assigned together as a single unit via the tool group.
Available Tools
When Twilio is connected, 7 tools are created and grouped under the "Twilio Communications" tool group. Two are write tools (requiring autonomous sends to be enabled), and five are read-only.
1. Send SMS (twilio_send_sms) - Write
Send SMS or MMS messages via Twilio.
| Parameter | Type | Required | Description |
|---|---|---|---|
| to | string | Yes | Destination phone number in E.164 format (e.g., +15551234567) |
| body | string | Yes | Message text (max 1,600 characters) |
| media_url | string | No | URL of media to attach (MMS). Must be publicly accessible. |
Requires: AllowAutonomousSends enabled. If disabled, the agent receives an error and asks for human escalation.
Example queries agents can answer:
- "Send a reminder to +1-555-0123 about their appointment tomorrow at 2pm"
- "Text this customer that their order has shipped"
2. Send WhatsApp (twilio_send_whatsapp) - Write
Send WhatsApp messages via Twilio, including template-based business messages.
| Parameter | Type | Required | Description |
|---|---|---|---|
| to | string | Yes | Destination phone number in E.164 format |
| body | string | Conditional | Message text for freeform messages. Cannot be used with template_sid. |
| template_sid | string | Conditional | Content Template SID (starts with HX) for pre-approved templates. Cannot be used with body. |
| template_variables | object | No | Key-value pairs to fill template variables |
| media_url | string | No | URL of media to attach |
Requires: AllowAutonomousSends enabled and a WhatsApp number configured on the connection.
WhatsApp business-initiated messages (outside the 24-hour session window) require pre-approved templates. Use template_sid for these messages. For replies within an active session, use body for freeform messages.
3. Search Messages (twilio_search_messages) - Read
Search message history, get message details, and retrieve media.
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | search, get_details, or get_media |
| to | string | No | Filter by recipient phone number (for search) |
| from | string | No | Filter by sender phone number (for search) |
| date_sent_after | string | No | ISO 8601 date lower bound (for search) |
| date_sent_before | string | No | ISO 8601 date upper bound (for search) |
| message_sid | string | Conditional | Message SID (required for get_details and get_media) |
| limit | integer | No | Maximum results (default 20, max 100) |
Action summary:
| Action | Description |
|---|---|
search | Search messages with optional filters for recipient, sender, and date range |
get_details | Get full details for a specific message including delivery status and pricing |
get_media | List media attachments for a specific MMS message |
4. Phone Lookup (twilio_lookup_phone) - Read
Validate phone numbers, check carrier type, detect SIM swaps, and verify caller identity.
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_number | string | Yes | Phone number in E.164 format |
| fields | array | No | Data packages to include. Default: ['line_type_intelligence'] |
Available fields:
| Field | Description | Relative Cost |
|---|---|---|
line_type_intelligence | Carrier name and line type (mobile/landline/VoIP) | Lowest |
caller_name | Registered caller name and type (consumer/business) | Medium |
sim_swap | Whether a SIM swap occurred recently | Medium |
identity_match | Verify caller identity information | Higher |
reassigned_number | Whether the number has been reassigned | Higher |
Each lookup field has a per-query cost on your Twilio account. The tool defaults to line_type_intelligence (the cheapest option) and only requests additional fields when the agent specifically needs them.
5. Manage Calls (twilio_manage_calls) - Read
List recent voice calls, get call details, and retrieve recordings.
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | list_recent, get_details, or get_recordings |
| call_sid | string | Conditional | Call SID (required for get_details and get_recordings) |
| to | string | No | Filter by recipient (for list_recent) |
| from | string | No | Filter by caller (for list_recent) |
| start_time_after | string | No | ISO 8601 date lower bound (for list_recent) |
| start_time_before | string | No | ISO 8601 date upper bound (for list_recent) |
| limit | integer | No | Maximum results (default 20, max 100) |
Action summary:
| Action | Description |
|---|---|
list_recent | List recent calls with optional filters for phone number and date range |
get_details | Get full details for a specific call including duration and pricing |
get_recordings | List recordings for a specific call |
This tool is read-only. Agents can review call history and recordings but cannot initiate outbound voice calls.
6. Verify Phone (twilio_verify_phone) - Read/Write
Send and check phone verification codes via SMS, voice, WhatsApp, or email.
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | send_code or check_code |
| to | string | Yes | Phone number (E.164) or email address to verify |
| channel | string | No | Delivery channel: sms (default), call, whatsapp, or email |
| code | string | Conditional | Verification code to check (required for check_code) |
Action summary:
| Action | Description | Requires Autonomous Sends |
|---|---|---|
send_code | Send a verification code to the recipient | Yes |
check_code | Validate a code the user provides | No |
Requires: A Verify Service SID configured on the connection. The send_code action also requires AllowAutonomousSends enabled (since it sends an outbound message). The check_code action does not require autonomous sends as it only validates a code with no external message.
7. Account Overview (twilio_account_overview) - Read
View account information, phone numbers, and usage summaries.
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | account_info, list_phone_numbers, or usage_summary |
| category | string | No | Usage category filter (for usage_summary): sms, sms-outbound, sms-inbound, calls, calls-outbound, calls-inbound, phonenumbers, recordings, totalprice |
| start_date | string | No | Usage period start (YYYY-MM-DD). Default: first day of current month. |
| end_date | string | No | Usage period end (YYYY-MM-DD). Default: today. |
Action summary:
| Action | Description |
|---|---|
account_info | Get account name, status, and type |
list_phone_numbers | List all phone numbers with their capabilities (voice/SMS/MMS) |
usage_summary | Get usage statistics and costs by category for a date range |
Safety Controls
Autonomous Sends Gate
The autonomous sends toggle is the primary safety control for outbound messaging. When disabled (the default), all write operations gracefully fail and instruct the agent to escalate to a human.
| Setting | Behavior |
|---|---|
| Disabled (default) | SMS, WhatsApp, and verification code sends are blocked. Agents receive a message asking them to escalate. Read-only tools (search, lookup, calls, account) work normally. |
| Enabled | Agents can send SMS, WhatsApp, and verification codes autonomously. All messages incur charges on your Twilio account. |
The toggle can only be changed via the dedicated safety controls section on the connection page, which requires a confirmation dialog. This is a separate, auditable action from general connection updates.
Tool Authorization Tiers
All Twilio tools are gated by authorization tiers to control who can trigger tool usage:
| Agent Type | Authorization Tier | Who Can Trigger |
|---|---|---|
| CAIOO | VIP | VIP contacts, admins, and business owners only |
| Personal Assistant | Internal | Internal users only (employees within your organization) |
External senders cannot trigger Twilio tool execution through either CAIOO or Personal Assistant agents.
Safety Gateway Integration
All 7 Twilio tools are registered with the Safety Gateway for PII scanning. Outbound message content (SMS body, WhatsApp body) and recipient phone numbers are analyzed before execution. The Safety Gateway can hold, flag, or block messages based on your configured safety settings.
Data Preview
The connection page includes data preview tabs that let you verify your Twilio account data:
- Phone Numbers - Table of your Twilio account phone numbers with their capabilities (voice, SMS, MMS)
- Recent Messages - Paginated table of recent messages showing recipient, sender, body preview, delivery status, and timestamp
These previews load on demand and use the same API credentials as the agent tools.
Execution Logs
The connection page includes a recent executions section showing Twilio tool usage across all agents:
- Agent name and execution timestamp
- Tool calls made during each execution (tool name, action, duration)
- Links to full execution details for deeper investigation
- Configurable lookback period (default 7 days, maximum 30 days)
Navigate to Monitor > Agent Executions for comprehensive execution history across all tool types.
Security
- AES-256-CBC encryption - API Key credentials are encrypted at rest using your tenant's encryption key
- Credentials never exposed - Encrypted credentials are never returned in GET API responses or logged
- API Key auth (not Auth Token) - API keys are revocable and auditable, following Twilio's production best practices
- Tenant isolation - Credentials and tools are strictly scoped to your tenant via TenantId
- No token caching needed - API keys are long-lived and used directly in HTTP Basic Auth; no token refresh or distributed locking complexity
- Audit logging - Every tool execution is logged with the agent, action, parameters, and results
- Safety Gateway - All tools are registered for PII scanning of outbound content
Troubleshooting
Credential Validation Fails
Problem: API key credentials are rejected when connecting
Solutions:
- Verify your Account SID starts with
ACand your API Key SID starts withSK - Confirm you are using an API Key, not your Auth Token
- Check that the API Key has not been revoked in the Twilio Console
- Ensure there are no extra spaces in the credential fields
- Try creating a new API Key in Twilio Console > Account > API Keys
Agent Returns "No Phone Number Configured"
Problem: SMS or WhatsApp tool fails because no sender number is set
Solutions:
- Navigate to Build > Connections > Twilio and check the Default Phone Number field
- For SMS, ensure a Default Phone Number is configured
- For WhatsApp, ensure a WhatsApp Number is configured (separate from the SMS number)
- If your Twilio account has no phone numbers, purchase one in the Twilio Console
Agent Returns "Autonomous Sends Not Enabled"
Problem: Agent cannot send messages and asks for human escalation
Solutions:
- This is the expected behavior when autonomous sends are disabled (the default)
- Navigate to Build > Connections > Twilio and locate the Safety Controls section
- Toggle Allow Autonomous Sends to ON and confirm the dialog
- Retry the agent execution
If you want agents to have read-only Twilio access (message search, phone lookup, call history) without the ability to send messages, leave autonomous sends disabled. The read-only tools work independently of this setting.
Connection Shows "Error" Status
Problem: The connection status changed to "error" after working previously
Solutions:
- Your API Key may have been revoked in the Twilio Console
- Click Test Connection to verify - if it fails, the key was likely revoked or rotated
- Click Update Settings to enter new API Key credentials
- After updating, the connection status returns to active
Agent Cannot Find Twilio Tools
Problem: Twilio tools do not appear when editing an agent
Solutions:
- Verify the Twilio connection is active at Build > Connections > Twilio
- Check that the "Twilio Communications" tool group exists at Build > AI Agents > Tool Groups
- Assign the tool group (not individual tools) to the agent
- Refresh the page and try again
Verification Code Fails to Send
Problem: The verify phone tool returns an error about missing configuration
Solutions:
- Navigate to Build > Connections > Twilio and check whether a Verify Service SID is configured
- If not, create a Verify Service in the Twilio Console (Verify > Services > Create)
- Copy the Service SID (starts with
VA) and enter it in the connection settings - Ensure autonomous sends are enabled (required for sending verification codes)
Rate Limit Errors
Problem: Agent receives rate limit errors from Twilio
Solutions:
- The agent will automatically retry with backoff (up to 3 retries) - the request may succeed after a brief delay
- If errors persist, reduce the frequency of Twilio operations by spacing out agent executions
- Check your Twilio account's rate limits in the Twilio Console
- Avoid running multiple agents that use Twilio tools simultaneously
Best Practices
Agent Instructions
Help your agents use Twilio tools effectively:
When working with Twilio communication tools:
1. Always validate phone numbers with twilio_lookup_phone before sending
messages to unfamiliar numbers (check if mobile vs landline).
2. For message history, use twilio_search_messages with date filters to
narrow results rather than retrieving all messages.
3. For verification workflows, use twilio_verify_phone send_code to send
the code, then check_code to validate - remind the user to provide
the code they received.
4. Use twilio_account_overview with usage_summary to check messaging
costs before large-scale outreach.
5. Phone numbers must be in E.164 format (e.g., +15551234567).
Configuration
- Assign the Twilio tool group only to agents that genuinely need messaging or phone capabilities
- Leave autonomous sends disabled until you have tested your agent instructions thoroughly
- Consider creating a dedicated "Communications Agent" with the Twilio tool group rather than adding it to general-purpose agents
- Monitor messaging costs regularly using the Account Overview tool or the Twilio Console
- If you only need read-only access (search, lookup, call logs), leave autonomous sends disabled
Security
- Use API Keys (not Auth Tokens) for this integration - API keys can be revoked without affecting other Twilio integrations
- Rotate your Twilio API key periodically from the Twilio Console, then update it on the connection page
- Review agent execution logs to monitor what messages are being sent and to whom
- Configure the Safety Gateway to scan outbound message content for sensitive information
- Disconnect the Twilio integration if your organization no longer needs messaging capabilities
Related Topics
- Tools Overview - All available agent tools
- Agents - Configure agents to use tools
- Agent Executions - View tool execution logs