CallTakeover
Take a live call over from the browser and hand it back to the agent.
CallTakeover lets a person on your team talk to the caller on a live call, from a browser tab with a microphone. While they are on the call the agent stays silent: it stops listening and stops speaking. When they hand the call back, the agent takes over again.
import { CallTakeover } from '@spekoai/client';Your backend mints the credentials with speko.calls.webJoin(callId). The Supervise live calls guide shows the full flow.
Connect
const takeover = await CallTakeover.connect({
// Called once the microphone is granted, so a slow permission prompt never
// eats into the join window. Passing `url` and `token` works too.
credentials: () => fetch(`/api/calls/${callId}/take-over`, { method: 'POST' }).then((r) => r.json()),
onStatusChange: (status) => setStatus(status),
onEnded: ({ reason }) => setNote(reason === 'call_ended' ? 'Call ended' : 'Handed back'),
onError: (error) => setNote(error.code === 'MICROPHONE_FAILED' ? 'Microphone lost' : 'Connection lost'),
onSpeakersChange: (speakers) => setSpeakers(speakers),
onAudioPlaybackBlocked: () => setNeedsResume(true),
});connect() asks for the microphone first and joins the call only once it has one. Then it waits for Speko to confirm the take-over: the caller hears the person and the agent is silent. It resolves at that point, usually a second or two after the join. It rejects with a SpekoClientError whose code is:
MICROPHONE_FAILEDwhen the browser gives no microphone, for example because the person denied permission. Nothing joined the call, so the agent carries on.CONNECTION_FAILEDwhen the join fails, for example because the token is older than 60 seconds, or whencredentials()rejects.TAKE_OVER_FAILEDwhen the take-over is not confirmed withinconfirmTimeoutMs(20 seconds by default). The browser leaves and the agent carries on.
Mint the credentials when the person clicks, and prefer credentials over url and token: Speko waits about a minute after the mint for the microphone to reach the call. If the call ends during the join, connect() resolves to a take-over whose status is already ended, and onEnded has already fired with reason: 'call_ended'. Read takeover.status before you show a live state.
If a CallListener is playing the same call in this tab, disconnect it before you connect, or the person hears the call twice.
Hand the call back
await takeover.handBack();The browser leaves the call and the agent takes it back. It is told that a teammate spoke with the caller, which it did not hear, and it asks the caller whether there is anything else it can help with. A Fish Live 3 agent picks the call back up without the note or the question. Closing the tab hands the call back too.
Mute
await takeover.setMuted(true);Muting only stops the caller hearing you. The call stays yours: the agent stays silent until you hand the call back.
Options
| Option | Type | Description |
|---|---|---|
credentials | () => Promise<{ url, token }> | Fetches url and token from speko.calls.webJoin() once the microphone is granted. Use this, or url and token. |
url | string | url from speko.calls.webJoin(). |
token | string | token from speko.calls.webJoin(). Mint one per take-over. |
confirmTimeoutMs | number | How long to wait for Speko to confirm the take-over. Default 20000. |
signal | AbortSignal | Cancels the take-over at any point before connect() settles: the browser never joins or leaves at once, and the microphone is released. connect() then resolves with status ended. Abort it when the person leaves the page. |
inputDeviceId | string | Microphone device id from navigator.mediaDevices.enumerateDevices(). |
outputDeviceId | string | Output device id. The call plays on this device only. |
volume | number | Playback volume from 0 to 1. Default 1. |
onStatusChange | (status) => void | connecting, live, ended or failed. |
onEnded | ({ reason }) => void | handed_back or call_ended. |
onError | (error) => void | DISCONNECTED when the connection is lost. MICROPHONE_FAILED when the microphone stops while live (unplugged, or permission revoked): the connection stays up and the agent stays silent, but the caller no longer hears you, so hand the call back. |
onSpeakersChange | (speakers) => void | Who is speaking: you, agent or caller. An empty array means silence. |
onAudioPlaybackBlocked | () => void | The browser blocked playback. Call startAudio() from a click handler. |
onOutputDeviceError | (error) => void | The call could not be played on outputDeviceId. |
Methods and properties
| Member | Description |
|---|---|
status | connecting, live, ended or failed. A take-over never leaves ended or failed: to take over again, mint a new token and connect a new one. |
isMuted | Whether your microphone is muted. |
setMuted(muted) | Mute or unmute your microphone. |
setVolume(volume) | Set playback volume from 0 to 1. |
startAudio() | Resume playback after onAudioPlaybackBlocked. Call it from a click handler. |
handBack() | Leave the call and give it back to the agent. Safe to call more than once. |