Skip to main content

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.

No multiplexing - one connection per call

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:

  1. Recompute HMAC-SHA256(secret, "{timestamp}.{call_control_id}") using the timestamp and call_control_id from the same start frame.
  2. Compare it to x-leadhero-stream-signature using a constant-time comparison.
  3. Reject if x-leadhero-stream-timestamp is more than a few minutes old, to bound how long a captured signature stays replayable.
Validation happens on the second frame, not at connection time

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.

Generate a secret before relying on auth

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:

EventWhen
connectedSent once, immediately after the WebSocket handshake completes
startSent once, right after connected - carries the call and audio format details
mediaSent repeatedly for the duration of the call - one audio chunk per frame
stopSent 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"
}
}
  • payload is base64-encoded raw audio in whatever start.media_format.encoding reported - not a WAV or other container, no headers.
  • track is inbound or outbound (see Tracks below). When you've configured only one side, every media frame 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:

SettingWhat you get
Both sidesEvery media frame has a track of inbound (the lead) or outbound (the rep), interleaved by arrival time on the same connection
Rep onlyOnly outbound frames
Lead onlyOnly 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.

Decoding non-PCMU audio

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}`);
}
});
});