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:
| Mode | Supervisor hears | Agent hears the supervisor | Caller hears the supervisor |
|---|---|---|---|
listen | both sides | no | no |
whisper | both sides | yes (coaching) | no |
barge | both sides | yes | yes (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.
How it works
Section titled “How it works”- The supervisor’s own browser device (the embedded softphone) is rung. With
auto_answer: trueit connects without a click. - Once answered, the platform taps the live call on the node that carries it. The agent and caller see no change to their call.
- A mode change is sent to the running supervision as a single keypress on the spy leg, so going from
listentowhispertobargeis instant and does not re-ring anyone. - 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.
The API
Section titled “The API”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:
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:
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:
curl -X DELETE 'https://api.sip.io/v1/calls/{callId}/supervise?supervisor=us_supervisor' -H 'x-api-key: sk_…'Errors
Section titled “Errors”| Status | error | Meaning |
|---|---|---|
400 | supervisor_required | An API key must name the supervisor. |
404 | call_not_found | No live call by that id in this account. |
404 | not_supervising | Mode change or stop with no running supervision. |
409 | not_supervisable | The call is not connected yet, or is not on the media edge. |
409 | supervisor_no_device | The supervisor has no reachable browser device. |
409 | already_supervising | This supervisor is already on another call. |
409 | cannot_supervise_self | A supervisor cannot monitor their own call. |
502 | node_error · no_node | The node carrying the call could not be reached. |
Related
Section titled “Related”- Live Call Control: hold, mute, park, DTMF and hang-up on a live call.
- Live Supervisor Wallboard: find the call to supervise.
- Call Transfer: move the call once you’ve stepped in.