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": "monitor"
}'
{
"call": {
"id": "665f1e2a9c4b1a0012ab99ff",
"direction": "outbound",
"state": "calling",
"legKind": "monitor",
"from": "+18005551234",
"to": "+14155550100",
"connectTo": null,
"queueId": null,
"conferenceId": null,
"parentCallId": "665f1e2a9c4b1a0012ab34cd",
"bridgedCallId": null,
"monitorRole": "MONITOR",
"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"
}
}
Voice Calls (v1)
Monitor a Call
Dial a phone supervisor to listen to or coach an established call.
POST
/
v1
/
voice
/
calls
/
{callId}
/
monitor
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": "monitor"
}'
{
"call": {
"id": "665f1e2a9c4b1a0012ab99ff",
"direction": "outbound",
"state": "calling",
"legKind": "monitor",
"from": "+18005551234",
"to": "+14155550100",
"connectTo": null,
"queueId": null,
"conferenceId": null,
"parentCallId": "665f1e2a9c4b1a0012ab34cd",
"bridgedCallId": null,
"monitorRole": "MONITOR",
"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"
}
}
Dials a phone supervisor into an established conversation. A new monitor attempt requires a
primary call in the established state. The supervisor joins as a new monitor leg after answering. This endpoint cannot attach an existing call ID, invite a browser supervisor, or change a participant’s role. Controls use the call’s saved backend.
The optional recipient screening route concerns the outbound customer recipient. It does not apply to a supervisor joining an existing call.
For Trackly-managed calls, a stable Idempotency-Key replays the same supervisor attempt; changing its destination or role returns 409 idempotency_conflict. Without a key, requests share the default monitor attempt. Use a new key for an intentional additional supervisor. Hosted calling has no equivalent replay contract: retrying after a timeout can dial another supervisor. Inspect the existing call after an uncertain response.
Requires the voice_calls.write scope and the Voice Calls product entitlement.
Decide which users may listen or coach in your authenticated application before its backend calls this endpoint. Keep the Trackly API key on your server. For accounts enrolled in customer-managed supervisor authorization, an account owner also approves the supervisor’s phone number and role in Calling setup. Creating a phone agent or holding the dialer API key does not approve that destination. The account owner chooses the supervisors; Trackly does not approve individuals.
An enrolled account needs an active grant for the resolved to number and requested role before a new monitor leg can be dialed. Trackly checks again before submitting an unsubmitted attempt; a revocation observed then stops it. A change after that final check can race with submission. A leg already accepted or with an uncertain provider outcome keeps its existing recovery path. A fresh attempt without a matching grant returns 403 monitor_not_authorized; an unavailable grant check returns 503 monitor_grant_unavailable. A replay of a saved pending leg may return that leg before its control rechecks the grant and cancels it. Read the leg’s state after replay. This control is staged by account; its presence in this reference does not mean it is enabled for your account.
Path Parameters
string
required
The id of the
primary call to monitor.Body Parameters
string
required
The supervisor’s telephone destination. Accepts either an E.164 number or the
id of a phone agent, not a browser agent. The resolved destination is screened against your account’s compliance suppression (DNC, opt-out, quiet hours) before dialing.string
default:"monitor"
Case-insensitive
monitor (listen only) or advisor. For Trackly-managed calls, advisor coaches the browser agent or an established telephone bridge agent. A telephone call without an established agent leg returns 409 agent_leg_required. Hosted calling accepts advisor but does not expose directed coaching through this request contract. Barge and role changes are not supported.Headers
string
For Trackly-managed calls, a nonblank key of at most 128 characters identifying one supervisor attempt. Reuse the same key and input on retry. The hosted backend does not provide this replay guarantee.
Response Fields
object
The created monitor leg.
Hide Call properties
Hide Call properties
string
The monitor leg’s unique identifier.
string
Always
outbound — a monitor leg is dialed out to the supervisor.string
Lifecycle state. See Call states.
string
monitor for a leg created here.string
The calling number.
string
The supervisor’s number.
string | null
The resolved bridge target, if any.
string | null
The queue this call is parked in, if any.
string | null
The hosted conference ID when present. Trackly-managed monitoring does not require one. Read Get a Call for later state.
string | null
The primary call this monitor leg belongs to.
string | null
For a primary call, the currently bridged agent leg.
string | null
MONITOR or ADVISOR for this monitor leg.boolean
Whether recording was requested.
string | null
requested, started, stopped, ready, failed, or deleted.array
Provider file ids for completed recordings.
object
Metadata carried on the call object.
string | null
A machine-readable reason when the call failed.
string | null
ISO 8601 timestamp when the leg was placed.
string | null
ISO 8601 timestamp when the leg was answered.
string | null
ISO 8601 timestamp when the leg ended.
string | null
ISO 8601 timestamp when the record was created.
Examples
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": "monitor"
}'
{
"call": {
"id": "665f1e2a9c4b1a0012ab99ff",
"direction": "outbound",
"state": "calling",
"legKind": "monitor",
"from": "+18005551234",
"to": "+14155550100",
"connectTo": null,
"queueId": null,
"conferenceId": null,
"parentCallId": "665f1e2a9c4b1a0012ab34cd",
"bridgedCallId": null,
"monitorRole": "MONITOR",
"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"
}
}
Error Codes
| Status | Code | Meaning |
|---|---|---|
| 403 | voice_not_entitled | Voice calling is not enabled for your account. |
| 403 | monitor_not_authorized | A fresh monitor request for an enrolled account lacks a matching number and role grant. A pending replay can instead return its saved leg before the control is cancelled. |
| 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. |
| 409 | agent_leg_required | Trackly-managed advisor mode requires an established agent leg. |
| 409 | idempotency_conflict | The Trackly-managed monitor key was already used with a different destination or role. |
| 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. |
| 503 | monitor_grant_unavailable | Supervisor authorization could not be confirmed. Check the retained call before retrying the same monitor attempt. |