Skip to main content

​
Endpoint

POST /call-customer
Initiates an outbound phone call to a customer using Twilio. The call is tracked in the database and connected to a WebSocket stream for real-time audio processing.

​
Request Parameters

​
to
string
required
The phone number to call. Must be in E.164 format (e.g., +1234567890).
​
verification
number
required
Unique verification identifier for tracking this call session.

​
Request Body Example

{
  "to": "+12025551234",
  "verification": 98765
}

​
Response

​
Success Response

​
message
string
Success message containing the Twilio call SID
Example: 
Call initiated with SID: CA1234567890abcdef1234567890abcdef

​
Error Responses

​
400 Bad Request

Returned when request validation fails: 
"to" is required
or 
"verification" is required

​
500 Internal Server Error

Returned when the call fails to initiate: 
Failed to initiate call: {error message}

​
How It Works

  1. Validation: Request body is validated using Joi schema
  2. Database Record: Creates a new call record in Supabase with status “in_progress”
  3. Twilio Call: Initiates outbound call using Twilio API
  4. WebSocket Stream: Connects call to media stream endpoint for real-time processing
  5. Response: Returns Twilio call SID on success
The call automatically connects to a WebSocket stream at /media-stream/{verification}/{callId} for real-time audio processing.

​
Code Examples

curl -X POST https://your-server.com/call-customer \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+12025551234",
    "verification": 98765
  }'
Ensure the phone number is in E.164 format (starting with +) and is valid. Invalid phone numbers will cause the Twilio API call to fail.

​
Implementation Details

The endpoint performs the following operations from /home/daytona/workspace/source/highway-backend/routes.js:35:
  1. Validates request using Joi schema
  2. Inserts call record into Supabase calls table
  3. Creates Twilio call with TwiML instructions
  4. Connects call to WebSocket stream for media processing
  5. Enables call recording with transcription
The TwiML response includes:
  • WebSocket stream connection
  • Call recording with transcription
  • Automatic hangup after stream completes

Build docs developers (and LLMs) love

Get started for freeTalk to us