Vaja - Telephony Integration Guide

Quick Start

Connect your FreeSWITCH to Vaja by updating your WebSocket URL:

# Change this line in your FreeSWITCH configuration:
WS_URL = "wss://vaja.ai/ws?apiKey=YOUR_API_KEY&protocol=json&encoding=mulaw"
                

That's it! No other code changes needed.

1. WebSocket Connection

URL Format

wss://vaja.ai/ws?apiKey=YOUR_API_KEY&protocol=json&encoding=mulaw

Required Parameters

Parameter	Value	Description
`apiKey`	Your API key	Provided by Vaja team
`protocol`	`json`	Enables telephony mode
`encoding`	`mulaw`	Audio codec (use mulaw for North America)

2. Message Protocol

1Start Call

Send when call begins:

{
  "event": "start",
  "streamSid": "unique-call-id"
}
                

2Send Audio

Send audio chunks (recommended: 20ms chunks):

{
  "event": "media",
  "media": {
    "payload": "base64_encoded_mulaw_audio"
  },
  "streamSid": "unique-call-id"
}
                

Audio Format: 8kHz sample rate, μ-law encoded, Base64-encoded

3Receive Response

Vaja sends AI responses in the same format:

{
  "event": "media",
  "media": {
    "payload": "base64_encoded_mulaw_audio"
  }
}
                

Decode the base64 payload and play to caller.

4End Call

Send when call ends:

{
  "event": "stop",
  "streamSid": "unique-call-id"
}
                

3. Audio Requirements

Setting	Value
Sample Rate	8000 Hz (8kHz)
Encoding	μ-law (PCMU)
Format	Base64-encoded
Chunk Size	160 bytes (20ms) recommended

4. Testing Your Integration

Update your FreeSWITCH WebSocket URL with the Vaja endpoint
Make a test call to your DID number
Verify audio is being sent/received
Confirm AI responses are audible
Test call end scenarios

5. Common Issues

Connection Failed

Verify API key is correct
Ensure protocol=json is in the URL
Check WebSocket URL is wss:// (not ws://)

No Audio Response

Confirm audio is 8kHz μ-law encoded
Verify payload is base64-encoded
Check audio chunks are at least 160 bytes
Ensure streamSid matches between messages

Poor Audio Quality

Verify sample rate is exactly 8000 Hz
Check for network latency/packet loss
Ensure proper μ-law encoding

6. Support

Need help? Contact us:

Email: support@vaja.ai
Dashboard: vaja.ai/dashboard

Vaja Telephony Integration