> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Choose Call Listeners

> Choose which phone numbers may listen to or advise on calls.

An account owner can choose a phone number for listen-only monitoring, `ADVISOR` mode, or both. Manage these numbers for each client account in Calling setup → Developer setup → Call listeners. Your dialer still decides which signed-in users may request monitoring; an approved destination does not grant a Salesforce user access to a call.

This setup uses the **signed-in owner's Trackly session** and the session's active account. It does not accept a Voice Calls API key. Select the client account before viewing or changing its supervisors. Trackly does not approve the people your account owner chooses. The account must have Voice Calls access.

Grant enforcement is enabled by account. When enabled, [Monitor a Call](/api-reference/voice/calls/monitor-call.md) requires a current grant for the resolved phone number and requested `MONITOR` or `ADVISOR` role. Creating a phone agent or giving someone a `voice_calls.write` key does not grant monitoring authority. A grant does not start or answer a call.

`MONITOR` is listen-only. On Trackly-managed calls, `ADVISOR` coaches the retained agent leg. Hosted calls accept `ADVISOR` but do not guarantee directed coaching of that agent. Neither mode offers barge or an in-call role change.

## List saved numbers

`GET /api/voice-calls/setup/monitor-grants` returns `{items, nextCursor, enforced}` for the active account. `enforced: true` means new listener calls require the saved destination and role; `false` means the list is saved but does not yet restrict calls for this account. Your dialer must still decide who may request monitoring. Each item has `id`, `number`, `roles`, `revision`, and `updatedAt`. A revoked entry remains visible with `roles: []`. Results are sorted by phone number.

The optional `limit` query parameter defaults to 20 and accepts 1–100. Pass a returned `nextCursor` as `cursor` to read the next page. To read the current state of one number, use `number` with its exact E.164 value instead of `cursor`. Do not reuse a cursor after switching accounts.

## Approve or revoke a number

`PUT /api/voice-calls/setup/monitor-grants` replaces one number's roles and returns its `id`, `number`, `roles`, `revision`, `updatedAt`, and `eventId`. Send JSON with these fields:

| Field | Meaning |
| - | - |
| `requestId` | A unique ID for this change, 1–128 printable ASCII characters. Retry an uncertain request with the same ID and body. |
| `expectedRevision` | `0` for a new number; otherwise the current `revision` from the list or prior change. |
| `number` | The supervisor destination in E.164 format, including `+` and country code. Use the exact phone number that the monitor request resolves to. |
| `roles` | `[]` to revoke, `["MONITOR"]` for listen-only, `["ADVISOR"]` for advisor mode, or `["ADVISOR", "MONITOR"]` to allow both. Keep the values unique and in that order. |

For example, an owner can approve a number for listening:

```json theme={null}
{
  "requestId": "supervisor-1-listen",
  "expectedRevision": 0,
  "number": "+12135550101",
  "roles": ["MONITOR"]
}
```

To revoke it, read its current revision and send another `PUT` for the same number with a new `requestId`, that revision, and `"roles": []`. When enforcement is active, Trackly checks again before an unsubmitted attempt; a revocation observed then blocks it. A saved pending monitor leg can be returned on replay before its control checks the new grant state and cancels. A change after the final check can race with submission. Revocation does not end a supervisor already connected to a call or authorize a second attempt after an uncertain outcome. It retains the earlier change records.

A successful change returns `200` with the saved number and revision:

```json theme={null}
{
  "id": "68e7e0795f2038a7313dd001",
  "number": "+12135550101",
  "roles": ["MONITOR"],
  "revision": 1,
  "updatedAt": "2026-10-09T18:05:00.000000Z",
  "eventId": "68e7e0795f2038a7313dd002"
}
```

A retry with the same `requestId` returns the original change result, even if another owner has since changed that number. After an uncertain retry, read the number with `GET` before treating its roles or revision as current.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 401 or 403 | — | Sign in as an owner of the selected client account. A dialer API key cannot manage this list. Session access errors do not carry a stable `code`. |
| 403 | — | Enable Voice Calls for the selected account. The entitlement error does not carry a stable `code`. |
| 409 | `revision_conflict` | Refresh the list and use the latest revision. |
| 409 | `idempotency_conflict` | This `requestId` was already used with different fields. |
| 409 | `monitor_grant_missing` | A number must be granted before it can be revoked. |
| 422 | `invalid_monitor_number`, `invalid_monitor_roles` | Correct the E.164 number or role list. |
| 422 | `invalid_fields`, `invalid_request_id`, `invalid_revision`, `invalid_limit`, `invalid_cursor` | Correct the request body or list parameters. |
| 429 | `rate_limited` | Wait for the returned `Retry-After` period before another change. |
| 503 | `setup_indexes_required`, `setup_transaction_unavailable`, `setup_unavailable`, `kyc_approval_unavailable` | The list or change could not be confirmed. Check the list before retrying the same request. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.