Skip to main content

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

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. 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.
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 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.
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

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.”
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 for assistance with your Twilio integration.