Call Supervision

Real-time call supervision for supervisors. These endpoints allow supervisors to monitor, coach, and join active calls handled by agents in teams they supervise.

caution

Supervisor Only

All endpoints on this page require the supervisor role in a team that the call's agent belongs to. See Roles & Permissions for details.

Endpoints

Method	Endpoint	Description
POST	/call-center/calls/:call_id/listen	Silent monitor
POST	/call-center/calls/:call_id/whisper	Coach agent
POST	/call-center/calls/:call_id/barge	Join as 3-way call
DELETE	/call-center/calls/:call_id/supervision	Stop supervision

Authentication

All endpoints require Bearer JWT with agent-api audience and supervisor role.

Supervision Modes

Mode	Supervisor hears	Agent hears supervisor	Caller hears supervisor
Listen	✅	❌	❌
Whisper	✅	✅	❌
Barge	✅	✅	✅

---

Call Session Token (call_token)

Every successful supervision call (listen, whisper, barge) returns a short-lived call_token (JWT valid for 15 minutes).

This call_token is used by the Client SDK (or WebRTC app) to connect directly to the Signaling Server / WebRTC media stream with zero-latency authentication.

call_token JWT Payload Structure

{
  "sub": "supervisor.jane",
  "aud": "call-session",
  "workspace_id": "ws_123456789",
  "call_id": "cl_a1b2c3d4e5f6",
  "mode": "listen",
  "fs_uuid": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  "exp": 1753114200
}

tip

Unified Call Token Architecture The call_token architecture is unified across all call interactions:

• Participant / Inbound Push: Included in VoIP Push payload data so mobile apps can connect immediately to WebSocket without extra HTTP roundtrips.
• Supervision: Returned by supervision APIs to authorize WebRTC audio streams (listen, whisper, barge).

---

Silent Listen

POST /call-center/calls/:call_id/listen

Start silently monitoring an active call. Neither the agent nor the caller will know you are listening.

Path Parameters

Parameter	Type	Description
call_id	string	ID of the active call

Request

curl -X POST "https://{workspace_id}.firetell.app/api/v1/call-center/calls/cl_a1b2c3d4e5f6/listen" \
  -H "Authorization: Bearer YOUR_SUPERVISOR_JWT"

Response 200 OK

{
  "call_id": "cl_a1b2c3d4e5f6",
  "mode": "listen",
  "supervisor": "supervisor.jane",
  "status": "supervision_started",
  "call_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900
}

---

Whisper (Coach)

POST /call-center/calls/:call_id/whisper

Start whispering to the agent. The agent can hear you, but the caller cannot. Useful for real-time coaching.

Request

curl -X POST "https://{workspace_id}.firetell.app/api/v1/call-center/calls/cl_a1b2c3d4e5f6/whisper" \
  -H "Authorization: Bearer YOUR_SUPERVISOR_JWT"

Response 200 OK

{
  "call_id": "cl_a1b2c3d4e5f6",
  "mode": "whisper",
  "supervisor": "supervisor.jane",
  "status": "supervision_started",
  "call_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900
}

---

Barge-in (3-Way Call)

POST /call-center/calls/:call_id/barge

Join the call as a third participant. Both the agent and the caller can hear you.

Request

curl -X POST "https://{workspace_id}.firetell.app/api/v1/call-center/calls/cl_a1b2c3d4e5f6/barge" \
  -H "Authorization: Bearer YOUR_SUPERVISOR_JWT"

Response 200 OK

{
  "call_id": "cl_a1b2c3d4e5f6",
  "mode": "barge",
  "supervisor": "supervisor.jane",
  "status": "supervision_started",
  "call_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900
}

---

Stop Supervision

DELETE /call-center/calls/:call_id/supervision

Stop any active supervision session on a call.

Request

curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/call-center/calls/cl_a1b2c3d4e5f6/supervision" \
  -H "Authorization: Bearer YOUR_SUPERVISOR_JWT"

Response 200 OK

{
  "call_id": "cl_a1b2c3d4e5f6",
  "supervisor": "supervisor.jane",
  "status": "supervision_stopped"
}

---

Call Transfer

Any active agent can transfer an active call to another agent or department.

POST /call-center/calls/:call_id/transfer

Request Body

Field	Type	Required	Description
target_username	string	✅	Username of the target agent to receive the transfer
team_id	string	❌	Optional target team ID (auto-detected if omitted)

Request

curl -X POST "https://{workspace_id}.firetell.app/api/v1/call-center/calls/cl_a1b2c3d4e5f6/transfer" \
  -H "Authorization: Bearer YOUR_AGENT_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "target_username": "agent.bob"
  }'

Response 200 OK

{
  "call_id": "cl_a1b2c3d4e5f6",
  "status": "transfer_initiated",
  "from_agent_id": "ag_original123",
  "to_agent": {
    "id": "ag_target456",
    "username": "agent.bob"
  },
  "transferred_by": "agent.jane"
}

Error Responses

Status	Description
400	Target agent not found, not in specified team, or not available
404	Call not found or not active

tip

The target agent must have available presence state to receive a transfer. Check agent states first using GET /call-center/teams/:team_id/agents/states.

Error Responses

Status	Description
403	Not a supervisor, or call agent is not in a supervised team
404	Call not found or not active