Speko Docs

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

OptionTypeDescription
urlstringurl from speko.calls.listen().
tokenstringtoken from speko.calls.listen(). Mint one for each connect() call.
volumenumber?Playback volume from 0 to 1. The default is 1.
outputDeviceIdstring?An output device id from navigator.mediaDevices.enumerateDevices(). See Play on a chosen output device.
onStatusChange(status) => voidCalled on every status change, connecting included.
onEnded({ reason }) => voidCalled when the status becomes ended.
onError(error) => voidCalled when the status becomes failed after the listener was listening. error.code is DISCONNECTED.
onSpeakersChange(speakers) => voidCalled when the set of roles that are speaking changes.
onAudioPlaybackBlocked() => voidCalled when the browser blocks playback. See Resume blocked audio.
onOutputDeviceError(error: Error) => voidCalled when the browser cannot play the call on outputDeviceId. See Play on a chosen output device.

Status

listener.status has four values.

StatusMeaning
connectingconnect() is in progress.
listeningThe listener is on the call and plays its audio.
endedThe call is over or Speko removed the listener (reason: 'call_ended'), or your code called disconnect() (reason: 'stopped').
failedThe 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

MethodDescription
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.

ValueWho
'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(), []);

On this page