Providers · Twilio

Connect a Twilio WhatsApp sender

For numbers hosted on Twilio as your BSP. New here? Read Connect WhatsApp first for the shared essentials.

// 01

Prerequisites

Requirement	Notes
Twilio account (or subaccount) with WhatsApp	Subaccount sender → use that subaccount's SID + Auth Token everywhere.
Approved WhatsApp sender	Console → Messaging → Senders → WhatsApp senders. Must be active, not “pending”.
The number in E.164	e.g. `+14155238886` — leading `+`, no spaces. Used as both routing key and From.
Admin access to SupportWize	Requires the Channel Manage permission.

// 02

Point the webhooks

In Messaging → Senders → WhatsApp senders, open your number and set both fields to your Twilio webhook URL (shown on Admin → Channels):

Twilio setting	Value
When a message comes in	the Twilio webhook URL · HTTP POST
Status callback URL	the same URL

SupportWize accepts inbound messages and status callbacks on the one URL and routes them internally. Leave the body encoding as Twilio's default (form-encoded).

// 03

Connect in SupportWize

Important

Use the account's primary Auth Token, not an API Key/Secret. Twilio signs webhooks (X-Twilio-Signature) with the Auth Token, and SupportWize verifies against it — an API Key connects but inbound gets rejected as invalid signatures. Subaccount sender → subaccount Auth Token.

Option A — UI

Go to Admin → Channels, choose Twilio.
Enter the number (E.164), Account SID (AC…), and Auth Token.
Click Connect number.

Option B — API

POST /api/channels/whatsapp
// the number is the routing key, so it is sent as both fields
{
  "provider": "TWILIO",
  "phoneNumberId": "+14155238886",
  "displayPhone": "+14155238886",
  "twilioAccountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "accessToken": "<twilio-auth-token>"
}

Rotation

Rotating the Auth Token in Twilio immediately breaks inbound verification. After rotating, use Update token on the channel card to paste the new one — no re-connection needed.

Then verify end-to-end using Test & go live.