Call Audio Streaming
Call audio streaming forwards live call audio to a WebSocket server you run, in real time, as the call happens - for your own recording pipeline, live transcription, sentiment analysis, or a custom AI voice agent.
Enable it and generate an auth secret from Settings → Developer → Call audio streaming. The settings page only has the on/off toggle, your endpoint's URL, which side of the conversation to stream, and the secret - this page covers everything your server needs to implement to receive it correctly.
How it connects
Once enabled, every connected call opens its own WebSocket connection from Lead Hero to your URL - your server accepts incoming WebSocket connections, it does not poll or dial out anywhere.
Two calls in progress at the same time means two separate connections arrive at your server, each carrying only that call's audio. If your server keeps any state (buffers, counters, decoders), scope it to the individual connection - never to a variable shared across connections, since a second concurrent call reusing that shared state will corrupt or misattribute both calls' audio.
The start frame (see below) carries a call_control_id if you need to correlate a stream with other data about that call later - for example, a webhook you received for the same call.
Authentication
If a secret is set, the start frame's start.custom_parameters carries a signature instead of the raw secret:
{
"x-leadhero-stream-timestamp": "1700000000000",
"x-leadhero-stream-signature": "sha256=74c23ebff4108054b325745d7177cdaefab96bf979cb5ba913329d56da1971f7"
}
The signature is HMAC-SHA256(secret, "{timestamp}.{call_control_id}"), hex-encoded and prefixed with sha256= - the same convention as webhook signatures, just signing {timestamp}.{call_control_id} instead of {timestamp}.{body} (there's no request body here; call_control_id - also in start.start.call_control_id - plays the equivalent role of binding the signature to this one connection).
To verify:
- Recompute
HMAC-SHA256(secret, "{timestamp}.{call_control_id}")using the timestamp and call_control_id from the samestartframe. - Compare it to
x-leadhero-stream-signatureusing a constant-time comparison. - Reject if
x-leadhero-stream-timestampis more than a few minutes old, to bound how long a captured signature stays replayable.
Unlike a header you could check during the WebSocket upgrade, this signature only arrives inside the start frame - the second message, after connected. Your server has to accept the connection first, then validate once start arrives, and close it (code 1008) if the signature doesn't check out. There's no way to reject before accepting the handshake.
Auth is optional: if you enable streaming without generating a secret, no signature is sent and any client that knows your URL can connect. Generate one from the settings page before using this in anything beyond a local test.
Message format
Once connected, your server receives a sequence of JSON text frames:
| Event | When |
|---|---|
connected | Sent once, immediately after the WebSocket handshake completes |
start | Sent once, right after connected - carries the call and audio format details |
media | Sent repeatedly for the duration of the call - one audio chunk per frame |
stop | Sent once, when the call stops streaming (hangup, or streaming explicitly stopped) |
connected
{
"event": "connected",
"version": "1.0.0"
}
start
{
"event": "start",
"sequence_number": "1",
"stream_id": "32de0dea-53cb-4b21-89a4-9e1819c043bc",
"start": {
"call_control_id": "v3:...",
"custom_parameters": {
"x-leadhero-stream-timestamp": "1700000000000",
"x-leadhero-stream-signature": "sha256=74c23ebff4108054b325745d7177cdaefab96bf979cb5ba913329d56da1971f7"
},
"call_session_id": "...",
"from": "+15550001111",
"to": "+15550002222",
"media_format": {
"encoding": "PCMU",
"sample_rate": 8000,
"channels": 1
}
}
}
Use start.media_format to know exactly how to decode the media frames that follow - don't assume a fixed format (see Audio format below for why).
start.custom_parameters is only present when a secret is set (see Authentication above) - it's absent entirely otherwise.
media
{
"event": "media",
"sequence_number": "4",
"stream_id": "32de0dea-53cb-4b21-89a4-9e1819c043bc",
"media": {
"track": "inbound",
"chunk": "2",
"timestamp": "5",
"payload": "base64-encoded audio chunk"
}
}
payloadis base64-encoded raw audio in whateverstart.media_format.encodingreported - not a WAV or other container, no headers.trackisinboundoroutbound(see Tracks below). When you've configured only one side, everymediaframe has that one track.- Frame delivery order isn't guaranteed - use
chunk(an incrementing sequence number) to reorder if you need exact ordering.
stop
{
"event": "stop",
"sequence_number": "5",
"stream_id": "32de0dea-53cb-4b21-89a4-9e1819c043bc",
"stop": {
"call_control_id": "v3:..."
}
}
No further frames follow on this connection - the socket closes shortly after.
Tracks
The Audio to stream setting controls which side(s) of the call you receive:
| Setting | What you get |
|---|---|
| Both sides | Every media frame has a track of inbound (the lead) or outbound (the rep), interleaved by arrival time on the same connection |
| Rep only | Only outbound frames |
| Lead only | Only inbound frames |
Audio format
By default, audio is delivered as 8kHz mono PCMU (G.711 µ-law), regardless of the codec the call itself negotiated - Lead Hero requests a transcode to a fixed, well-known format so you don't have to handle every codec a call could end up using.
Transcoding isn't always possible for a given call leg, though. When it isn't, you'll receive the call's actual negotiated codec instead (commonly G.729). Always read start.media_format.encoding rather than assuming PCMU - a decoder that only handles PCMU will need a fallback (or to reject/log) for the codecs it doesn't support.
ffmpeg can decode plenty of telephony codecs from a raw bitstream once you tell it the format and sample rate, for example:
ffmpeg -f g729 -i raw-audio.g729 -ar 8000 -ac 1 output.wav
Check ffmpeg -formats | grep -i <codec> for whether a given codec has a matching raw-format demuxer before relying on this - not every codec does.
Minimal example
State lives on the connection object, so concurrent calls never cross-contaminate - see No multiplexing above.
// Node.js, using the `ws` package
const { createHmac, timingSafeEqual } = require('crypto');
const { WebSocketServer } = require('ws');
const server = new WebSocketServer({ port: 8080 });
const REPLAY_WINDOW_MS = 5 * 60 * 1000;
function isValidSignature(callControlId, timestamp, signature) {
if (!callControlId || !timestamp || !signature) return false;
if (Math.abs(Date.now() - Number(timestamp)) > REPLAY_WINDOW_MS)
return false;
const expected = `sha256=${createHmac('sha256', process.env.STREAM_SECRET)
.update(`${timestamp}.${callControlId}`)
.digest('hex')}`;
const expectedBuf = Buffer.from(expected);
const signatureBuf = Buffer.from(signature);
return (
expectedBuf.length === signatureBuf.length &&
timingSafeEqual(expectedBuf, signatureBuf)
);
}
server.on('connection', (socket) => {
let callControlId; // this connection's call only
socket.on('message', (raw) => {
const msg = JSON.parse(raw.toString());
if (msg.event === 'start') {
callControlId = msg.start.call_control_id;
const params = msg.start.custom_parameters ?? {};
if (
!isValidSignature(
callControlId,
params['x-leadhero-stream-timestamp'],
params['x-leadhero-stream-signature']
)
) {
socket.close(1008, 'unauthorized');
return;
}
console.log(
`stream started for ${callControlId}`,
msg.start.media_format
);
} else if (msg.event === 'media') {
const audioChunk = Buffer.from(msg.media.payload, 'base64');
// audioChunk is raw audio in msg.start.media_format.encoding for
// this connection's call (callControlId) only - decode/transcode
// or forward as needed.
} else if (msg.event === 'stop') {
console.log(`stream stopped for ${callControlId}`);
}
});
});