Voice Calls is a distinct product served under the
/v1/voice path. It is unrelated to the deprecated v1 SMS API. It must be enabled on your account before use — requests from an unentitled account return 403 voice_not_entitled.Base URL
Authentication & scopes
Every request uses the same API-key authentication as the rest of the Trackly API — anX-Api-Key header (or Authorization: Bearer). See Authentication.
Voice endpoints additionally require a product scope on the API key:
Calling numbers
Use List Calling Numbers atGET /api/v1/voice/calling-numbers to discover the account’s owned caller IDs. Inventory confirms ownership; call placement still checks current admission requirements. Provision programmable voice numbers in Calling.
Who Am I returns this endpoint in voice.calling_numbers_url. Its api_key.send_policy.list_numbers field describes SMS sending-list restrictions; an empty array means unrestricted by that list policy. The /v1/voice/numbers endpoint belongs to the separate SIP-trunking product. SMS registration uses /v2/number-requests for ordinary API keys or the agent-only preparation flow for delegated trackly.registration authority.
Core concepts
Calls
A single call leg. Telephone calls use a
primary customer-facing leg and separate bridge and monitor legs for agents and supervisors. Browser calls have a separate agent-first workflow; see Salesforce and browser calling.Queues
Inbound callers are parked on hold audio in a queue, then claimed FIFO by an agent via dequeue.
Agents
A phone agent is a named telephone destination usable in
connectTo or monitor’s to. A browser agent identifies an authenticated headset user and uses browser sessions and calls instead. The to on Place a Call is an E.164 number, not an agent ID.Recordings
Start/stop recording on an active call, then list and download the resulting audio files.
Call states
A call moves through these states.status=active on List Calls matches any non-terminal state.
Compliance
Every outbound dial to a phone number —to on Place a Call, and the resolved connectTo on place/answer/dequeue or the to on monitor — is screened against your account’s compliance suppression: Do-Not-Call, per-number opt-out, litigation/reassignment suppression, and TCPA quiet hours. This includes numbers that resolve from an agent. A blocked dial returns 403 with a compliance_* code.
Recipient screening is an optional, date-qualified reassignment check for authorized businesses. Normal Voice accounts do not need that lookup or a date or source-record reference in call requests. A confirmed reassignment can restrict new calls to that recipient for the calling business; a no or no_data result does not establish consent or override other compliance suppression.
Concurrency
Each account has a ceiling on simultaneous active calls. When it is reached, new calls return429 concurrency_limit. Retry once existing calls complete.
The limit counts individual legs, including callers on hold, agents, and supervisors. API-key request limits also apply to reads and controls; they are separate from simultaneous-call capacity.
Idempotency
Place a Call defaults to hosted calling and returns201. Its optional account-scoped Idempotency-Key returns an existing call without comparing the body; validation and compliance checks still apply. A definitive rejection can release the key, while an uncertain result can leave the call pending.
Trackly-managed calling returns 202 and requires a nonblank key of at most 128 characters. Reuse the same key, API key and input; changed input returns 409 idempotency_conflict. Acceptance does not mean the call has answered.
Trackly-managed monitor accepts an idempotency key and replays the same supervisor attempt. Without a key, requests share the default monitor attempt; use a new key for an intentional additional supervisor. Trackly-managed dequeue requires a key and retains the selected caller on replay. Hosted monitor and dequeue do not provide these replay guarantees. After an uncertain response, inspect the existing call before starting another attempt.
Joining an existing conversation
Monitor a Call dials a new phone supervisor into an established primary call. It does not attach an existing call ID or provide a browser supervisor, general conference-management, barge, or role-change API.MONITOR is listen-only. For Trackly-managed calls, ADVISOR coaches the browser agent or an established telephone bridge agent; a telephone call without that agent leg returns 409 agent_leg_required. Hosted calling accepts ADVISOR but does not expose directed coaching through this request contract.
Call recording
Recording controls select a call leg. On the hosted backend, joining a conference ends that leg’s individual recording; these endpoints do not start hosted conference recording. For Trackly-managed calls, Trackly records the selected call leg, andrecord: true schedules capture to start on answer. Neither path guarantees a complete recording of every participant or arbitrary conference.
The optional recordingControl object describes the latest explicit recording command: action (start or stop), generation, and status (pending, running, complete, cancelled, or outcome_unknown). It describes command processing, not observed audio. cancelled means the command was suppressed before provider submission. A submitted command with an unknown outcome remains outcome_unknown after the call ends. recordingState is aggregate telemetry and can retain stopped after a later start. Repeating the current action can reuse that command; repeating an older start after a stop requests a new generation. An unresolved opposite action returns 409 recording_control_in_progress. Each call permits at most 128 explicit starts (409 recording_control_limit); stop and hangup remain available.
Webhooks
Attach anotifyUrl to a queue to receive call.received and call.ended events; set a notifySecret to have them signed with X-Trackly-Signature. These notifications do not provide general outbound call-status delivery. Poll Get a Call for recorded state. See Queue Webhooks.