CallListener
Play a live call in the browser, receive-only.
CallListener plays the audio of a live call in a browser tab. It only receives. It never asks for the microphone, and it publishes no audio and no data. Nobody on the call can hear or see the listener, and the agent keeps talking.
import { CallListener } from '@spekoai/client';Your backend mints the credentials with speko.calls.listen(callId). The Listen to live calls guide shows the full flow.
Connect
const listener = await CallListener.connect({
url,
token,
onStatusChange: (status) => setStatus(status),
onEnded: ({ reason }) => setNote(reason === 'call_ended' ? 'Call ended' : ''),
onError: () => setNote('Connection lost'),
onSpeakersChange: (speakers) => setSpeakers(speakers),
onAudioPlaybackBlocked: () => setNeedsResume(true),
});connect() resolves when the listener has joined the call. The listener plays every audio track on the call as the track arrives. connect() rejects with a SpekoClientError whose code is CONNECTION_FAILED when the join fails. The most common cause is a token older than 60 seconds.
The call can end while the join is in progress, and Speko can turn a listener away at the join, for example a sixth listener. In both cases connect() resolves. The listener that it returns has the status ended, and onEnded has already fired once with reason: 'call_ended'. connect() does not reject, because the join did not fail. Read listener.status before you show a listening state.
if (listener.status === 'listening') showListening();Options
| Option | Type | Description |
|---|---|---|
url | string | url from speko.calls.listen(). |
token | string | token from speko.calls.listen(). Mint one for each connect() call. |
volume | number? | Playback volume from 0 to 1. The default is 1. |
outputDeviceId | string? | An output device id from navigator.mediaDevices.enumerateDevices(). See Play on a chosen output device. |
onStatusChange | (status) => void | Called on every status change, connecting included. |
onEnded | ({ reason }) => void | Called when the status becomes ended. |
onError | (error) => void | Called when the status becomes failed after the listener was listening. error.code is DISCONNECTED. |
onSpeakersChange | (speakers) => void | Called when the set of roles that are speaking changes. |
onAudioPlaybackBlocked | () => void | Called when the browser blocks playback. See Resume blocked audio. |
onOutputDeviceError | (error: Error) => void | Called when the browser cannot play the call on outputDeviceId. See Play on a chosen output device. |
Status
listener.status has four values.
| Status | Meaning |
|---|---|
connecting | connect() is in progress. |
listening | The listener is on the call and plays its audio. |
ended | The call is over or Speko removed the listener (reason: 'call_ended'), or your code called disconnect() (reason: 'stopped'). |
failed | The join failed, or the connection was lost and did not recover. |
ended and failed are final. To listen again, mint a new token and connect a new listener.
Speko removes every listener when the call is over. That removal is how the listener learns that the call ended, so you do not need to poll the session.
Methods
| Method | Description |
|---|---|
setVolume(volume) | Set the playback volume from 0 to 1. |
startAudio() | Resume playback after the browser blocked it. Call it from a click or tap handler. |
disconnect() | Stop listening and remove the audio elements. A second call does nothing. |
Speakers
onSpeakersChange receives the roles that are speaking now.
| Value | Who |
|---|---|
'agent' | The AI agent. |
'caller' | A person on the call: the phone caller, a browser user, or a transfer recipient. |
The array holds each role once, with 'agent' first. An empty array means that nobody is speaking.
On a call between two AI agents, both sides report 'agent'. The array is ['agent'] whichever agent speaks, so it cannot tell the two agents apart.
Resume blocked audio
Browsers block audio that does not follow a click or a tap. If your page connects the listener from a click handler, playback starts. If the page connects on load, or the click was long ago, the browser can block playback. The listener stays connected but the user hears nothing.
onAudioPlaybackBlocked reports the block. Show a button, and call startAudio() from its click handler.
resumeButton.onclick = () => listener.startAudio();Play on a chosen output device
Without outputDeviceId, the call plays on the default output device of the browser.
With outputDeviceId, the call plays on that device only. An audio track makes no sound until the browser has routed the track to the device, so the call never starts on the default speakers.
If the browser cannot route to the device, the track stays silent and the listener stays connected. The listener does not fall back to the default device. onOutputDeviceError reports the failure, at most once for each listener. The two causes are a device id that the browser refuses, for example an unplugged headset, and a browser that has no setSinkId().
To recover, call disconnect(), mint a new token, and connect a new listener with another device or without outputDeviceId.
const listener = await CallListener.connect({
url,
token,
outputDeviceId: headsetId,
onOutputDeviceError: () => setNote('Cannot play on this device. Choose another one.'),
});What the credentials allow
CallListener plays audio only, but the credentials are not limited to audio. They give receive access to everything in the call. That includes any media that is published into the call and the messages that your backend sends into the call.
Give the credentials only to people who are allowed to hear the whole call.
Clean up
Call disconnect() when the user leaves the view. In React, call it from the effect cleanup.
useEffect(() => () => void listenerRef.current?.disconnect(), []);