Skip to main content
This guide will walk you through setting up Twilio to handle phone calls with WebSocket streaming for Highway’s real-time voice verification system.

​
Prerequisites

  • A Twilio account
  • Access to purchase a phone number
  • A publicly accessible domain for webhooks

​
Creating a Twilio Account

1

Sign up for Twilio

Go to twilio.com and create a new account. You’ll need to verify your email and phone number.
2

Verify your account

Complete the account verification process. For production use, you’ll need to upgrade from a trial account.

​
Getting Your Credentials

1

Navigate to Account Dashboard

Once logged in, go to your Twilio Console.
2

Locate Account SID and Auth Token

On the console home page, you’ll find:
  • Account SID: A unique identifier for your account
  • Auth Token: Your authentication token (keep this secret)
Copy both values - you’ll need them for your environment variables.
Store your Auth Token securely. Never commit it to version control or share it publicly.

​
Purchasing a Phone Number

1

Go to Phone Numbers section

In the Twilio Console, navigate to Phone Numbers > Manage > Buy a number.
2

Select capabilities

Choose a number with the following capabilities:
  • Voice: Required for making and receiving calls
  • SMS: Optional, but useful for notifications
3

Choose your number

Search for numbers by country, area code, or specific digits. Once you find a suitable number, click Buy.
4

Save the number

Copy your new phone number (in E.164 format, e.g., +15551234567) for your environment variables.

​
Configuring Environment Variables

Add the following to your .env file: 
TWILIO_ACCOUNT_SID=your_account_sid_here
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+15551234567

​
TwiML Configuration for WebSocket Streaming

Highway uses TwiML (Twilio Markup Language) to connect calls to a WebSocket stream. The configuration is handled programmatically in your backend:
routes.js
const call = await client.calls.create({
  to: to,
  from: TWILIO_PHONE_NUMBER,
  twiml: `<?xml version="1.0" encoding="UTF-8"?>
          <Response>
              <Connect>
                  <Stream url="wss://${req.headers.host}/media-stream/${verification}/${data[0].id}" />
                  <Record transcribe="true" transcribeCallback="https://your-webhook-url.com/transcription"/>
              </Connect>
              <Hangup/>
          </Response>`,
});

​
Key TwiML Elements

  • <Connect>: Establishes the WebSocket connection
  • <Stream>: Specifies the WebSocket URL for bi-directional audio streaming
  • <Record>: Enables call recording with transcription
  • <Hangup>: Ends the call when the stream closes
The WebSocket URL must be accessible over HTTPS/WSS in production. Use a service like ngrok for local development.

​
Testing the Integration

1

Start your backend server

Ensure your Highway backend is running and accessible:
npm start
2

Make a test call

Use the /call-customer endpoint to initiate a call:
curl -X POST http://localhost:3000/call-customer \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15559876543",
    "verification": 123
  }'
3

Verify the call

  • Check that the call is received on the destination number
  • Verify that audio streams correctly through the WebSocket
  • Monitor the Twilio console for call logs

​
Webhook Setup

​
Transcription Callback

The transcription callback receives the transcribed text after the call ends: 
transcribeCallback="https://your-webhook-url.com/transcription"
1

Create a webhook endpoint

Set up an endpoint to receive transcription data from Twilio.
2

Update the TwiML

Replace https://your-webhook-url.com/transcription with your actual webhook URL.
3

Verify webhook security

Validate that requests are coming from Twilio by checking the X-Twilio-Signature header.
Always validate webhook signatures to prevent unauthorized access to your endpoints.

​
Call Recording and Transcription

Highway automatically enables recording and transcription: 
<Record transcribe="true" transcribeCallback="https://your-webhook-url.com/transcription"/>

​
Recording Features

  • Automatic transcription: Twilio converts speech to text
  • Callback URL: Receives transcription results when ready
  • Recording access: View and download recordings from the Twilio console

​
Accessing Recordings

1

Go to Call Logs

Navigate to Monitor > Logs > Calls in the Twilio Console.
2

Select a call

Click on a call SID to view details.
3

Download recording

Find the recording section and download or play back the audio.

​
Troubleshooting

​
Common Issues

Call not connecting
  • Verify your Twilio credentials are correct
  • Check that your phone number has voice capabilities
  • Ensure the WebSocket URL is accessible
No audio streaming
  • Confirm the WebSocket connection is established
  • Check that the audio format is set to g711_ulaw
  • Verify firewall settings allow WebSocket connections
Transcription not working
  • Ensure the callback URL is publicly accessible
  • Check webhook logs in the Twilio console
  • Verify the endpoint returns a 200 status code

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us