Speko Docs

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_FAILED when the browser gives no microphone, for example because the person denied permission. Nothing joined the call, so the agent carries on.
  • CONNECTION_FAILED when the join fails, for example because the token is older than 60 seconds, or when credentials() rejects.
  • TAKE_OVER_FAILED when the take-over is not confirmed within confirmTimeoutMs (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

OptionTypeDescription
credentials() => Promise<{ url, token }>Fetches url and token from speko.calls.webJoin() once the microphone is granted. Use this, or url and token.
urlstringurl from speko.calls.webJoin().
tokenstringtoken from speko.calls.webJoin(). Mint one per take-over.
confirmTimeoutMsnumberHow long to wait for Speko to confirm the take-over. Default 20000.
signalAbortSignalCancels 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.
inputDeviceIdstringMicrophone device id from navigator.mediaDevices.enumerateDevices().
outputDeviceIdstringOutput device id. The call plays on this device only.
volumenumberPlayback volume from 0 to 1. Default 1.
onStatusChange(status) => voidconnecting, live, ended or failed.
onEnded({ reason }) => voidhanded_back or call_ended.
onError(error) => voidDISCONNECTED 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) => voidWho is speaking: you, agent or caller. An empty array means silence.
onAudioPlaybackBlocked() => voidThe browser blocked playback. Call startAudio() from a click handler.
onOutputDeviceError(error) => voidThe call could not be played on outputDeviceId.

Methods and properties

MemberDescription
statusconnecting, 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.
isMutedWhether 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.

On this page