---
sidebar_position: 8
title: Call Supervision
description: Supervisor-only endpoints for real-time call monitoring — listen, whisper, and barge into active calls with short-lived call_token JWTs via the Firetell Agent API.
---

# 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](/docs/rest-api/agent-api/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

```json
{
  "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

```bash
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`

```json
{
  "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

```bash
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`

```json
{
  "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

```bash
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`

```json
{
  "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

```bash
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`

```json
{
  "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

```bash
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`

```json
{
  "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                                |