Supervise live calls
Steer the agent, take a call over from the browser, or end it, while the call is live.
While one of your agents is on a call, a person on your team can:
- Listen without anyone on the call knowing.
- Steer the agent with an instruction it follows for the rest of the call.
- Take over and talk to the caller directly from the browser, then hand the call back to the agent.
- End the call.
The Speko dashboard has these controls on a live call's session page. Your own app can call the same API. Every call id below is the session id returned by speko.voice.dial() or delivered in your webhooks.
These controls work for calls that run in a LiveKit room: phone, browser and WhatsApp calls, on cascade agents and on speech-to-speech agents hosted by Speko. Pipecat calls and provider-direct speech-to-speech sessions can only be ended.
Steer the agent
await speko.calls.sendMessage(callId, {
mode: 'instruct',
text: 'The caller is a returning customer. Offer the 20% loyalty discount before you end the call.',
});The agent follows the instruction from its next reply until the call ends. It never reads the instruction out and never mentions it. Nothing is spoken when the instruction arrives. Send another instruction to change course: where two conflict, the later one wins. An instruction is at most 1000 characters, and a call keeps at most 20.
The call's events record each instruction as call.message_sent, and worker.agent_message_delivered with mode: 'instruct' reports the outcome: instruction_applied, limit_reached, or unsupported when the call's speech-to-speech model cannot change its instructions mid-call. A workspace that does not store transcripts keeps only the instruction's length.
To have the agent tell the caller something now, in its own words, send mode: 'respond' instead.
Take over the call
Mint the credentials on your backend:
// POST /api/calls/:id/take-over
const { url, token } = await speko.calls.webJoin(callId, { displayName: 'Supervisor' });
return { url, token };Connect in the browser with CallTakeover. It asks for the microphone first, then fetches the credentials:
import { CallTakeover } from '@spekoai/client';
const takeover = await CallTakeover.connect({
credentials: () => fetch(`/api/calls/${callId}/take-over`, { method: 'POST' }).then((r) => r.json()),
onEnded: ({ reason }) => showNote(reason === 'call_ended' ? 'Call ended' : 'Handed back'),
});As soon as the microphone reaches the call, the caller hears the person and the agent goes silent: it stops listening and stops speaking. connect() resolves once Speko confirms that, and rejects with TAKE_OVER_FAILED if it does not within 20 seconds, in which case the agent keeps the call. Nothing announces the take-over to the caller. If the caller hangs up, the call ends.
To give the call back to the agent:
await takeover.handBack();The agent is told that a teammate spoke with the caller and that it did not hear what was said, 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.
Things to know:
- Transcript. The agent was not listening, so the call's transcript has no turns for the time it was taken over. The call's events show when the take-over started (
bridge.web_joined,worker.bridge_muted) and ended (worker.bridge_resumed). - Listening at the same time. Disconnect any
CallListenerplaying the same call in the tab before you take over, or the person hears the call twice. - Billing. The time a call is taken over is billed like the rest of the call.
- Errors.
webJoin()fails withCALL_NOT_ANSWEREDwhile an outbound call is still ringing,WEB_JOIN_UNSUPPORTEDfor a call with no LiveKit room,CALL_NOT_LIVEonce the call ended, andRATE_LIMITED(429, withRetry-After) after 10 requests for a call or 60 for your organization in a minute.
End the call
await speko.calls.end(callId);end() hangs up every leg of the call. It resolves with status: 'ending' once the hang-up is requested, ended for a call ended at once, or already_ended if the call was over. The call's end_reason is ended_by_api.