Twilio | Bridged User Guide

Twilio Integration Guide

Overview

This guide explains how to connect Bridged with Twilio to enable messaging capabilities across SMS, WhatsApp, and other communication channels. The integration supports sending and receiving messages, managing conversations, and syncing message status updates.

Twilio is a cloud communications platform that provides APIs for SMS, voice, WhatsApp, and other messaging channels. It enables businesses to communicate with customers programmatically at scale.

Prerequisites

Before starting, ensure you have:

A Twilio account (sign up at twilio.com)
A Twilio phone number with messaging capabilities enabled
Your Account SID and Auth Token (found in the Twilio Console dashboard)
For WhatsApp: A Twilio WhatsApp Business account configured

Connection Methods

Bridged supports two authentication methods for Twilio:

Method	Best for	Setup complexity
API Key (Preferred)	Server-to-server, automation, enhanced security	Low
Account SID + Auth Token	Basic integration, legacy setups	Low

Recommendation: API Key authentication is preferred for production integrations as it provides better security and allows separate access control per key.

Step 1: Obtain Your Twilio Credentials

Option A: API Key (Preferred)

Log in to the Twilio Console.
Navigate to Settings → API Keys & Tokens.
Click Create new API Key.
Enter a friendly name (e.g., Bridged Integration).
Choose key type: Standard (recommended for integrations).
Click Create.
Copy and save the following securely:
- API Key ID (acts as username)
- API Secret (acts as password)

Important: The API Secret is shown only once. Store it securely.

Option B: Account SID + Auth Token

Log in to the Twilio Console.
Locate your Account SID and Auth Token in the Account Summary section .
Copy both values for use in Bridged.

Step 2: Configure Your Twilio Phone Number

In the Twilio Console, navigate to Phone Numbers → Manage → Active Numbers .
Click on the phone number you want to use with Bridged.
Under Messaging, configure the webhook URL:
Setting
Value
A message comes in
https://gateway.bridged.media/webhooks/twilio
Primary handler
Webhook
Status callback URL
https://gateway.bridged.media/webhooks/twilio/status
Click Save.

Setting	Value
A message comes in	`https://gateway.bridged.media/webhooks/twilio`
Primary handler	Webhook
Status callback URL	`https://gateway.bridged.media/webhooks/twilio/status`

Note: The webhook URL must use HTTPS. Twilio will not deliver callbacks to HTTP endpoints .

Step 3: Configure Bridged to Connect to Twilio

Log in to your Bridged dashboard.
Navigate to the Integrations section. If you do not see this section, contact support@bridged.media.
Click Twilio → Connect Account.
Choose your authentication method:

Option A: API Key (Preferred)

Field	Description	Where to find
API Key ID	Your API key identifier	Step 1 - API Key ID
API Secret	Your API key secret	Step 1 - API Secret
Account SID	Your Twilio account identifier	Twilio Console → Account Summary
Phone Number	Your Twilio phone number (E.164 format, e.g., `+1234567890`)	Active Numbers page

Option B: Account SID + Auth Token

Field	Description	Where to find
Account SID	Your Twilio account identifier	Twilio Console → Account Summary
Auth Token	Your authentication token	Twilio Console → Account Summary
Phone Number	Your Twilio phone number (E.164 format)	Active Numbers page

Step 4: Configure Webhook for Inbound Messages

Twilio sends inbound messages to your webhook URL as HTTP POST requests with Content-Type: application/x-www-form-urlencoded .

Step 4.1: Verify Webhook Configuration

After configuring the webhook URL on your Twilio phone number (Step 2), Twilio will:

Send a POST request to your callback URL when an inbound message arrives.
Expect a 200 OK response. For status callbacks, no TwiML is required .

Step 4.2: Sample Inbound Webhook Payload

javascript

{
  "ToCountry": "US",
  "ToState": "CA",
  "SmsMessageSid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "NumMedia": "0",
  "ToCity": "",
  "FromZip": "",
  "SmsSid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "FromState": "",
  "SmsStatus": "received",
  "FromCity": "",
  "Body": "Hello from the customer!",
  "FromCountry": "US",
  "To": "+1234567890",
  "ToZip": "",
  "NumSegments": "1",
  "MessageSid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "AccountSid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "From": "+1987654321",
  "ApiVersion": "2010-04-01"
}

Step 5: Configure Sync Settings

Once connected, configure the following:

Setting	Options	Description
Message direction	Inbound only, Outbound only, Both	Define which messages to sync
Channel types	SMS, WhatsApp, Voice	Choose which Twilio channels to use
Webhook events	Messages, Statuses, Both	Choose which events to receive
Media handling	Enabled, Disabled	Process MMS media attachments

Bulk sync limit: Each bulk operation is limited to 50 records per request. For high-volume messaging, queue messages in batches.

Step 6: Send Outbound Messages

Bridged uses the Twilio REST API to send outbound messages. Below is an example of how messages are sent:

Example: Send an SMS

bash

curl -X POST "https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json" \
  -u "{ApiKeyId}:{ApiSecret}" \
  --data-urlencode "To=+1234567890" \
  --data-urlencode "From=+1987654321" \
  --data-urlencode "Body=Hello from Bridged!" \
  --data-urlencode "StatusCallback=https://gateway.bridged.media/webhooks/twilio/status"

Example: Send a WhatsApp Message

bash

curl -X POST "https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json" \
  -u "{ApiKeyId}:{ApiSecret}" \
  --data-urlencode "To=whatsapp:+1234567890" \
  --data-urlencode "From=whatsapp:+1987654321" \
  --data-urlencode "Body=Hello from Bridged on WhatsApp!" \
  --data-urlencode "StatusCallback=https://gateway.bridged.media/webhooks/twilio/status"

Status Callback Events

Twilio will POST to your StatusCallback URL when message status changes . Status values include:

Status	Description
`queued`	Message accepted by Twilio, waiting to send
`sending`	Message being sent to carrier
`sent`	Message delivered to carrier
`delivered`	Message delivered to recipient device
`failed`	Message failed to send
`undelivered`	Carrier could not deliver

Step 7: Test the Integration

In Bridged, go to Integrations → Twilio → Test Connection.
Send a test message from Bridged to your own phone number.
Reply to the message from your phone to verify inbound webhook delivery.
Check the Twilio Debugger at console.twilio.com/develop/debugger for any errors .

Common Use Cases

Playbook	Direction	Description
Activation	Outbound	Broadcast SMS marketing messages to leads
Qualification Agent	Inbound + Outbound	Receive user responses, qualify leads through SMS conversation
Nurture & Conversion	Outbound	Send order confirmations, shipping updates, appointment reminders
Customer Support	Inbound + Outbound	Two-way SMS support with agents

Rate Limiting & Performance

Rate limits depend on your Twilio account type and phone number type :

Phone Number Type	Messages per Second (MPS)
US/CA Long Code	1 MPS per number
Toll-Free	3 MPS (up to 25 MPS with approval)
Short Code	50 MPS
Twilio Account (Long Code)	50 MPS aggregate

Note: Rate limits are enforced by Twilio, not by Bridged. Exceeding limits will result in HTTP 429 responses .

Security & Permissions

Bridged supports API Key (preferred) and Account SID + Auth Token authentication.
API keys can be created with specific permissions and rotated periodically .
Webhook requests include an X-Twilio-Signature header for verification .
All API calls are made over TLS 1.2+.
You can revoke access at any time by deleting the API key in the Twilio Console.

Webhook Signature Verification

To verify that webhook requests are genuinely from Twilio, use the following code pattern :

javascript

const twilio = require("twilio");

app.post("/webhooks/twilio", express.urlencoded({ extended: false }), (req, res) => {
  const signature = req.headers["x-twilio-signature"];
  const url = "https://gateway.bridged.media/webhooks/twilio";

  const isValid = twilio.validateRequest(
    process.env.TWILIO_AUTH_TOKEN,
    signature,
    url,
    req.body
  );

  if (!isValid) {
    return res.status(403).send("Forbidden");
  }

  // Process the message...
  res.status(200).send();
});

Troubleshooting

Issue	Likely cause	Solution
Webhook not received	URL not publicly accessible	Ensure URL uses HTTPS and is reachable from the internet
Webhook verification fails	Signature mismatch	Check that validation URL exactly matches configured URL (trailing slashes matter)
Message send fails	Invalid phone number format	Use E.164 format: `+1234567890`
Rate limiting (429)	Exceeding Twilio MPS limits	Queue messages or upgrade phone number type
No inbound messages	Webhook not configured on phone number	Verify the phone number's "A message comes in" URL is set
Status callbacks not arriving	StatusCallback not set on message	Include `StatusCallback` parameter when sending messages
Authentication error (401)	Invalid API Key or Auth Token	Regenerate credentials in Twilio Console
Body empty in webhook	Expecting JSON instead of form-encoded	Use `express.urlencoded()` middleware, not `express.json()`

Support

For integration support, contact your Bridged account manager or email support@bridged.media.