> ## 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.

# Monitor a Call

> Dial a supervisor into an established call's conference to listen in or coach the agent.

Dials a supervisor into the conference behind an established call. Only a `primary` call in the `established` state can be monitored. The supervisor joins as a new `monitor` leg — either listening silently or whispering coaching audio to the agent, depending on `role`.

Requires the `voice_calls.write` scope and the **Voice Calls** product entitlement.

## Path Parameters

<ParamField path="callId" type="string" required>
  The id of the `primary` call to monitor.
</ParamField>

## Body Parameters

<ParamField body="to" type="string" required>
  The supervisor to dial in. Accepts either an E.164 number or the `id` of a [voice agent](/api-reference/voice/agents/create-agent). The resolved destination is screened against your account's compliance suppression (DNC, opt-out, quiet hours) before dialing.
</ParamField>

<ParamField body="role" type="string" default="monitor">
  `monitor` to listen only, or `advisor` to whisper/coach the agent (audible to the agent, not the far end).
</ParamField>

## Response Fields

<ResponseField name="call" type="object">
  The created monitor leg.

  <Expandable title="Call properties" defaultOpen>
    <ResponseField name="call.id" type="string">The monitor leg's unique identifier.</ResponseField>
    <ResponseField name="call.direction" type="string">Always `outbound` — a monitor leg is dialed out to the supervisor.</ResponseField>
    <ResponseField name="call.state" type="string">Lifecycle state. See [Call states](/api-reference/voice/overview#call-states).</ResponseField>
    <ResponseField name="call.legKind" type="string">`monitor` for a leg created here.</ResponseField>
    <ResponseField name="call.from" type="string">The calling number.</ResponseField>
    <ResponseField name="call.to" type="string">The supervisor's number.</ResponseField>
    <ResponseField name="call.connectTo" type="string | null">The resolved bridge target, if any.</ResponseField>
    <ResponseField name="call.queueId" type="string | null">The queue this call is parked in, if any.</ResponseField>
    <ResponseField name="call.conferenceId" type="string | null">The provider conference id the monitor leg is attached to. Always `null` in this response — it is populated only once the supervisor answers and the monitor leg joins the conference, so read it with a later [Get a Call](/api-reference/voice/calls/get-call). The parent call already carries the conference id by the time this monitor leg is dialed.</ResponseField>
    <ResponseField name="call.parentCallId" type="string | null">The primary call this monitor leg belongs to.</ResponseField>
    <ResponseField name="call.bridgedCallId" type="string | null">For a primary call, the currently bridged agent leg.</ResponseField>
    <ResponseField name="call.monitorRole" type="string | null">`MONITOR` or `ADVISOR` for this monitor leg.</ResponseField>
    <ResponseField name="call.record" type="boolean">Whether recording was requested.</ResponseField>
    <ResponseField name="call.recordingState" type="string | null">`requested`, `started`, `stopped`, `ready`, `failed`, or `deleted`.</ResponseField>
    <ResponseField name="call.recordingFileIds" type="array">Provider file ids for completed recordings.</ResponseField>
    <ResponseField name="call.customData" type="object">Metadata carried on the call object.</ResponseField>
    <ResponseField name="call.error" type="string | null">A machine-readable reason when the call failed.</ResponseField>
    <ResponseField name="call.startedAt" type="string | null">ISO 8601 timestamp when the leg was placed.</ResponseField>
    <ResponseField name="call.answeredAt" type="string | null">ISO 8601 timestamp when the leg was answered.</ResponseField>
    <ResponseField name="call.endedAt" type="string | null">ISO 8601 timestamp when the leg ended.</ResponseField>
    <ResponseField name="call.createdAt" type="string | null">ISO 8601 timestamp when the record was created.</ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.tracklysms.com/api/v1/voice/calls/665f1e2a9c4b1a0012ab34cd/monitor \
    -H "X-Api-Key: trk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+14155550100",
      "role": "advisor"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "call": {
      "id": "665f1e2a9c4b1a0012ab99ff",
      "direction": "outbound",
      "state": "calling",
      "legKind": "monitor",
      "from": "+18005551234",
      "to": "+14155550100",
      "connectTo": null,
      "queueId": null,
      "conferenceId": null,
      "parentCallId": "665f1e2a9c4b1a0012ab34cd",
      "bridgedCallId": null,
      "monitorRole": "ADVISOR",
      "record": false,
      "recordingState": null,
      "recordingFileIds": [],
      "customData": {},
      "error": null,
      "startedAt": "2026-08-21T18:05:00.000000Z",
      "answeredAt": null,
      "endedAt": null,
      "createdAt": "2026-08-21T18:05:00.000000Z"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Status | Code                                                                                           | Meaning                                                              |
| ------ | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| 403    | `voice_not_entitled`                                                                           | Voice calling is not enabled for your account.                       |
| 404    | `call_not_found` / `agent_not_found`                                                           | The referenced call or agent does not exist in your account.         |
| 409    | `call_not_established`                                                                         | The call is not in the `established` state and cannot be monitored.  |
| 422    | `not_a_primary_call`                                                                           | The target call is not a `primary` leg.                              |
| 422    | `invalid_role`                                                                                 | `role` must be `monitor` or `advisor`.                               |
| 422    | `invalid_number`                                                                               | The supervisor `to` is not a valid E.164 number.                     |
| 403    | `compliance_dnc` / `compliance_opted_out` / `compliance_suppressed` / `compliance_quiet_hours` | The resolved supervisor destination is blocked by a compliance rule. |
| 429    | `concurrency_limit`                                                                            | Your account has too many concurrent calls in progress.              |
| 502    | `provider_error`                                                                               | The upstream telephony provider rejected the request.                |