> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Twilio

> Connect Serval to your Twilio account so workflows can send WhatsApp template messages and call the Twilio REST, Messaging, and Content APIs.

## About Twilio

Twilio is a cloud communications platform for messaging, including WhatsApp and SMS, and voice. This integration connects a Serval Workspace to one Twilio account so workflows can send WhatsApp messages from your Content templates and call the Twilio API.

**Authentication:** Your Twilio Account SID and Auth Token. Serval checks them against Twilio when you save the connection, stores the Auth Token encrypted, and adds the credentials to each request server-side, so workflows never handle them. Serval sends them only to `api.twilio.com`, `messaging.twilio.com`, and `content.twilio.com`.

**Data sync:** None. Connecting doesn't sync anything into Serval, and you don't configure a webhook in Twilio. Workflows call Twilio on demand.

## What the Twilio integration enables

| Capability | Description |
| - | - |
| Send WhatsApp messages | Workflows use the "Send WhatsApp Message" action (`twilio.common.sendWhatsAppMessage`) to send a Content template from a WhatsApp sender in the connected account, filling in the template's variables. See [Send WhatsApp notifications](https://docs.serval.com/sections/documentation/workflows/Configure/build-guide.md#send-whatsapp-notifications). |
| Twilio API access | The "Twilio API request" action (`twilio.apiRequest`) calls the Twilio REST API (`api.twilio.com`), the Messaging API (`messaging.twilio.com`), and the Content API (`content.twilio.com`) with `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. The workflow's Twilio context carries the connected Account SID for paths that need it. |
| Connection health checks | Three built-in checks confirm the credentials work and that Serval can read the account's WhatsApp senders and phone numbers. |

## Get your credentials

**1. Pick the Twilio account**

Use the account that owns the WhatsApp senders and Content templates your workflows will use. The Send WhatsApp Message action always sends from the connected account.

**2. Copy the Account SID and Auth Token**

Sign in to the [Twilio Console](https://console.twilio.com/). The **Account Info** panel on the dashboard shows the **Account SID**, which starts with `AC`, and the **Auth Token**, which stays hidden until you reveal it.

> [!NOTE]
>
> Twilio gives the Account SID and Auth Token the same access as a Main API key: full access to every Twilio API resource in the account. The Twilio API request action can send `POST`, `PUT`, `PATCH`, and `DELETE` requests, so a workflow that uses it can do anything the account can through the REST, Messaging, and Content APIs, such as sending messages or changing phone number settings.

## Prepare WhatsApp messaging in Twilio

The Send WhatsApp Message action needs a WhatsApp sender and at least one Content template in the connected account.

**1. Register a WhatsApp sender**

Register your business phone number as a WhatsApp sender in the Twilio Console. Twilio's [WhatsApp Self Sign-up guide](https://www.twilio.com/docs/whatsapp/self-sign-up) covers the requirements, including a Meta Business Portfolio and a number that isn't already registered with WhatsApp.

**2. Create Content templates**

In the Twilio Console, open **Communications** > **Messaging** > **Templates** (in the legacy Console, **Messaging** > **Content Template Builder**) and create a template. Each saved template has a Content SID that starts with `HX`. Workflows pass that SID to the action.

**3. Submit templates for WhatsApp approval**

WhatsApp's customer service window lasts 24 hours after a person's last message to you. Outside that window, you can send only approved templates, so choose **Save and submit for WhatsApp approval** for any template you send outside it.

## Connect in Serval

**1. Open the Twilio connect form**

Add a new Twilio connection from your Serval integrations page, in the Workspace that owns the workflows that will use it.

**2. Enter the Account SID**

Paste the Account SID. It must be `AC` followed by 32 hexadecimal characters. The form flags any other value before you save.

**3. Enter the Auth Token**

Paste the Auth Token. It's stored encrypted and shown masked after saving.

**4. Save**

Serval verifies the Account SID and Auth Token with Twilio before it saves the connection. If Twilio rejects them, the form shows "Invalid Twilio Account SID or Auth Token." If Twilio is unreachable or returns an unexpected status, the message starts with "Could not verify Twilio credentials." Save again to retry.

> [!TIP]
>
> When you edit the connection, leave the masked Auth Token unchanged to keep the stored token. Serval verifies the credentials again on every save. A connection stays tied to the Account SID it was created with: saving a different Account SID on an existing connection fails. To use another Twilio account, add a new connection.

## Verifying the connection

The connection ships three health checks that make live calls to Twilio. Run them from the **Health Checks** section under the connection's **API Integration** settings in Serval:

* **Test Twilio Connection:** authenticates with the stored credentials and reads the account. On success: "Successfully authenticated with Twilio account" followed by the account's friendly name, when Twilio returns one. When it passes, the credentials and Serval's path to Twilio both work.
* **List Twilio WhatsApp Senders:** reads one WhatsApp sender through the Messaging API. It reports the first sender it finds, or passes with "Messaging API reachable, but the account has no WhatsApp senders" when there are none.
* **List Twilio Phone Numbers:** reads one of the account's incoming phone numbers. An account with no numbers still passes, with the message "Phone Numbers API reachable, but the account has no incoming phone numbers."

If **Test Twilio Connection** passes but another check fails, the credentials are valid but Serval can't read from that API with this account.

## Gotchas and troubleshooting

> [accordion] Invalid Twilio Account SID or Auth Token
>
> Twilio rejected the pair. Copy both values from the **Account Info** panel of the same account, and check that the Auth Token hasn't been rotated since you copied it.

> [accordion] API keys aren't supported
>
> The connection signs in with the Account SID and the account's Auth Token. A Twilio API key (its SID starts with `SK`) and its secret don't work in either field.

> [accordion] Rotating the Auth Token breaks the connection
>
> Promoting a secondary Auth Token in Twilio deletes the old primary token, and Serval's requests then fail. Before you promote, edit the connection and enter the secondary token, then confirm the health checks pass.

> [accordion] Phone numbers must be E.164, without the whatsapp: prefix
>
> Pass `fromPhoneNumber` and `toPhoneNumber` as E.164 numbers with a leading `+`, for example `+15551234567`. The action adds Twilio's `whatsapp:` prefix itself, so it rejects `whatsapp:+15551234567`, and a number without `+`, before sending anything.

> [accordion] The action sends templates only
>
> `contentSid` must be a Content SID: `HX` followed by 32 hexadecimal characters. The action has no free-text body. To send a free-form reply within the customer service window, call the Messages API with the Twilio API request action instead.

> [accordion] Twilio could not send the WhatsApp message
>
> Twilio accepted the request but reported the message as failed or undelivered, or returned an error code. Find the message in your Twilio messaging logs for the reason. If Twilio rejects the request outright, the action fails with the HTTP status Twilio returned instead.

> [accordion] Twilio accepted the request but returned an invalid message receipt
>
> Twilio may have sent the message even though Serval couldn't read the response. Check your Twilio messaging logs before you run the workflow again, or the recipient may get the message twice.

> [accordion] A returned status isn't a delivery confirmation
>
> The action returns `messageSid` and Twilio's `status` at the moment it accepted the message, such as `queued`. It doesn't wait for delivery. Use the `messageSid` to look up the message in Twilio later.

> [accordion] The WhatsApp Sandbox isn't listed as a sender
>
> The **List Twilio WhatsApp Senders** check lists the account's registered WhatsApp senders. Twilio's shared Sandbox number isn't one, so an account that only uses the Sandbox passes with a message that says the account has no WhatsApp senders.

> [accordion] Use form for form-encoded endpoints and body for JSON
>
> The Twilio API request action takes `form` for endpoints that expect form-encoded parameters, such as Messages, and `body` for JSON endpoints, such as the Content API. Supplying both fails with "Specify either body or form, not both."

> [accordion] Only three Twilio hosts are reachable
>
> Requests go only to `api.twilio.com`, `messaging.twilio.com`, and `content.twilio.com`. Other Twilio hosts, such as `verify.twilio.com` or `lookups.twilio.com`, are blocked. These hostnames don't name a Twilio Region, so Twilio handles the requests in its default US1 Region. Region-specific hosts such as `api.sydney.au1.twilio.com` aren't reachable.

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Twilio integration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.