Listen to live calls
Play the audio of a live AI call in your own web app, receive-only.
This guide shows how to let a user of your web app hear a call while the call is in progress. Your backend mints a short-lived credential with your API key. The browser uses the credential to join the call as a hidden listener.
The listener only receives. It cannot speak, nobody on the call can hear or see it, and the agent keeps talking. To put a person on a call, use a transfer instead.
Mint the credential on your backend
Call the listen endpoint with the session id, which is the same id that /v1/sessions/{id} uses. Mint one credential for each click on your play button. The token is accepted for 60 seconds, so do not store it.
With the TypeScript SDK:
import { Speko } from '@spekoai/sdk';
const speko = new Speko({ apiKey: process.env.SPEKO_API_KEY! });
app.post('/api/calls/:id/listen', async (req, res) => {
// Check here that this user may hear this call.
const { token, url } = await speko.calls.listen(req.params.id);
res.json({ token, url });
});With the Python SDK:
import os
from spekoai import Speko
speko = Speko(api_key=os.environ["SPEKO_API_KEY"])
@app.post("/api/calls/{call_id}/listen")
def listen(call_id: str):
# Check here that this user may hear this call.
credentials = speko.calls.listen(call_id)
return {"token": credentials.token, "url": credentials.url}With the REST API:
curl -X POST https://api.speko.dev/v1/calls/$SESSION_ID/listen \
-H "Authorization: Bearer $SPEKO_API_KEY"The response has five string fields.
{
"token": "eyJ...",
"url": "wss://...",
"identity": "listen-7f3a...",
"roomName": "...",
"expiresAt": "2026-11-11T10:01:00.000Z"
}Never send your API key to the browser. Send only token and url.
Play the call in the browser
Install @spekoai/client and connect a CallListener from the click handler of your play button.
import { CallListener } from '@spekoai/client';
playButton.onclick = async () => {
const { token, url } = await fetch(`/api/calls/${sessionId}/listen`, {
method: 'POST',
}).then((r) => r.json());
const listener = await CallListener.connect({
url,
token,
onEnded: ({ reason }) => {
// 'call_ended': the call is over. 'stopped': you called disconnect().
showIdle(reason === 'call_ended' ? 'Call ended' : '');
},
onError: () => showIdle('Connection lost'),
onSpeakersChange: (speakers) => highlight(speakers), // ['agent'], ['caller'], or both
onAudioPlaybackBlocked: () => showResumeButton(() => listener.startAudio()),
});
// The call can end while the join is in progress. onEnded has then already run.
if (listener.status !== 'listening') return;
showListening();
stopButton.onclick = () => listener.disconnect();
};CallListener never asks for the microphone. Call disconnect() when the user leaves the page.
If the call ends while the join is in progress, connect() still resolves. The listener that it returns has the status ended, and onEnded has already fired with call_ended. Read listener.status before you show a listening state.
Use livekit-client directly
If you do not want @spekoai/client, join with livekit-client. Do not publish a track. The token forbids it, so the publish fails.
import { DisconnectReason, Room, RoomEvent, Track } from 'livekit-client';
const room = new Room();
room.on(RoomEvent.TrackSubscribed, (track) => {
if (track.kind === Track.Kind.Audio) document.body.appendChild(track.attach());
});
room.on(RoomEvent.TrackUnsubscribed, (track) => {
for (const el of track.detach()) el.remove();
});
room.on(RoomEvent.Disconnected, (reason) => {
const callEnded =
reason === DisconnectReason.PARTICIPANT_REMOVED ||
reason === DisconnectReason.ROOM_DELETED ||
reason === DisconnectReason.ROOM_CLOSED;
showIdle(callEnded ? 'Call ended' : 'Connection lost');
});
await room.connect(url, token, { autoSubscribe: true });What the listener hears
The listener receives each audio source on the call as a separate track, and CallListener plays all of them.
| Source | Content |
|---|---|
| The agent | The voice of the AI agent. |
| The caller | The person on the phone, or the microphone of the browser user in a web session. On a call between two AI agents, the other agent. |
| Background audio | Ambience and thinking sounds, if the agent has them configured. |
| A transfer recipient | The person that the call was transferred to, while that person is on the call. |
onSpeakersChange reports who is speaking as 'agent', 'caller', or both. On a call between two AI agents, both sides report 'agent', so the array cannot tell the two agents apart.
When the call is over, Speko removes the listener. CallListener reports onEnded with reason: 'call_ended'.
Limits
| Limit | Value |
|---|---|
| Listeners on one call | 5. Speko checks the limit when you mint a credential and again when the listener joins. |
| Listen requests for one call | 20 in 60 seconds. A request counts when the call is live and has an audio room, even if it returns no credential. |
| Listen requests for all the calls in your workspace | 120 in 60 seconds, counted the same way. |
| Token lifetime | 60 seconds, for the join only. A connected listener stays connected until the call ends. |
| Direction | Receive-only. The listener cannot publish audio or data. |
| Call types | Calls whose audio passes through Speko's media servers. Other calls return LISTEN_NOT_SUPPORTED. |
Four call types return LISTEN_NOT_SUPPORTED:
- A browser session that sends audio directly to a speech-to-speech provider with
RealtimeVoiceConversation. The audio of this session does not pass through Speko. - A call on the Pipecat runtime.
- The receiving leg of a call that one of your agents places to another of your agents. Listen to the calling leg instead. The calling leg carries the same conversation.
- A call that has a limit on the number of participants. Some demo calls have this limit.
A mint request for a call that already has five listeners returns LISTENER_LIMIT_REACHED. Several credentials can be minted before any of them is used, so Speko counts again at the join. A listener beyond the fifth is disconnected at once, and onEnded fires with call_ended.
A listener can join only while another party is on the call with the agent. The other party is a person or, on a call between two AI agents, the second agent. If no other party is connected, for example before the caller joins, the listener is disconnected at once and onEnded fires with call_ended.
What the credentials allow
The credentials give receive access to everything in the call, not only to the audio. That includes any media that is published into the call and the messages that your backend sends into the call. CallListener plays audio only.
Give the credentials only to people who are allowed to hear the whole call. Check that permission in your backend before you mint a credential.
Errors
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | VALIDATION_ERROR | The request body has a field, or it is not valid JSON. The endpoint takes no fields. | Send the request with no body, or with {}. |
| 404 | NOT_FOUND | No session with this id exists in your workspace. | Check the id. |
| 409 | CALL_NOT_LIVE | The call has ended, or it has not connected yet. | For an ended call, hide the play button and use the recording. For a call that is still connecting, try again when it is active. |
| 409 | LISTEN_NOT_SUPPORTED | The call is live, but this call type has no audio that a listener can join. | Hide the play button for this call type. |
| 409 | LISTENER_LIMIT_REACHED | Five listeners are already on the call. | Try again after a listener leaves. |
| 429 | RATE_LIMITED | Too many listen requests were made in the last 60 seconds, or too many arrived at the same moment. | Wait for the number of seconds in the Retry-After header, then try again. The header is 60 for the first case and 1 for the second. |
| 503 | LISTEN_DISABLED | Listening is temporarily unavailable. | Try again later. Contact support if it continues. |
| 503 | UNAVAILABLE | Speko could not read the media state of the call, so it did not mint a credential. | Try again. |
The SDKs raise SpekoApiError with these values in code.
In the browser, CallListener.connect() rejects with CONNECTION_FAILED when the join fails. A token that is older than 60 seconds fails the join, and so does a network connection that fails.
A call that ended after you minted the credential is a different case. The join can still succeed, because the token is valid, and Speko then disconnects the listener. onEnded fires with call_ended, and onError does not fire. The disconnect can arrive before connect() resolves, and then the listener has the status ended. The disconnect can also arrive a moment after connect() resolves with the status listening.
Consent
You are responsible for any call-monitoring and consent rules that apply to you and to the people on the call.