Skip to content
SIP.IO
DocsStart free

Supervision (Listen, Whisper, Barge)

A supervisor can step into any live, connected agent call in their account in one of three modes, and switch between them without hanging up:

ModeSupervisor hearsAgent hears the supervisorCaller hears the supervisor
listenboth sidesnono
whisperboth sidesyes (coaching)no
bargeboth sidesyesyes (a 3-way call)

Supervision works on queue calls, direct calls, flow calls and click-to-call calls alike, wherever the call is anchored on the media engine media edge.

  1. The supervisor’s own browser device (the embedded softphone) is rung. With auto_answer: true it connects without a click.
  2. Once answered, the platform taps the live call on the node that carries it. The agent and caller see no change to their call.
  3. A mode change is sent to the running supervision as a single keypress on the spy leg, so going from listen to whisper to barge is instant and does not re-ring anyone.
  4. Hanging up the supervisor’s device, or calling DELETE, ends the supervision. The call itself carries on.

Each supervisor runs at most one supervision at a time, and nobody can supervise their own call.

All three endpoints need the calls:all scope. A session token is never accepted: supervision is a supervisor’s tool, so use an API key held by the supervisor’s app, which names the supervisor explicitly.

Start:

Terminal window
curl -X POST 'https://api.sip.io/v1/calls/{callId}/supervise' \
-H 'x-api-key: sk_…' -H 'content-type: application/json' \
-d '{ "mode": "listen", "auto_answer": true, "supervisor": "us_supervisor" }'

callId is the call as the live board or GET /v1/agents names it (the caller’s SIP Call-ID works too). The supervisor can be given by user id or extension.

{ "ok": true, "callId": "…", "mode": "listen", "supervisor_device": "dev_…", "spy_uuid": "…" }

Switch mode:

Terminal window
curl -X POST 'https://api.sip.io/v1/calls/{callId}/supervise/mode' \
-H 'x-api-key: sk_…' -H 'content-type: application/json' -d '{ "mode": "whisper" }'

Stop:

Terminal window
curl -X DELETE 'https://api.sip.io/v1/calls/{callId}/supervise?supervisor=us_supervisor' -H 'x-api-key: sk_…'
StatuserrorMeaning
400supervisor_requiredAn API key must name the supervisor.
404call_not_foundNo live call by that id in this account.
404not_supervisingMode change or stop with no running supervision.
409not_supervisableThe call is not connected yet, or is not on the media edge.
409supervisor_no_deviceThe supervisor has no reachable browser device.
409already_supervisingThis supervisor is already on another call.
409cannot_supervise_selfA supervisor cannot monitor their own call.
502node_error · no_nodeThe node carrying the call could not be reached.