curl -X POST https://api.tracklysms.com/api/v1/voice/agents \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Front Desk",
"type": "phone",
"number": "+14155559876"
}'
{
"agent": {
"id": "665f1e2a9c4b1a0012ab34cd",
"name": "Front Desk",
"type": "phone",
"number": "14155559876",
"createdAt": "2026-08-21T18:00:00.000000Z"
}
}
Voice Calls (v1)
Create an Agent
Create a reusable phone destination or an allowlisted, issuer-bound browser agent.
POST
/
v1
/
voice
/
agents
curl -X POST https://api.tracklysms.com/api/v1/voice/agents \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Front Desk",
"type": "phone",
"number": "+14155559876"
}'
{
"agent": {
"id": "665f1e2a9c4b1a0012ab34cd",
"name": "Front Desk",
"type": "phone",
"number": "14155559876",
"createdAt": "2026-08-21T18:00:00.000000Z"
}
}
Creates a named voice agent. A
The
phone agent is a reusable destination you can reference by its id in the connectTo field on place a call, answer a call, or dequeue, as well as the to field when dialing a monitor leg. Referencing a phone agent by id keeps its underlying number out of your request payloads. Every dial is compliance-screened regardless of whether the destination is a raw number or a phone agent.
Accounts explicitly enabled for the browser media backend can also create a webrtc agent bound to the authenticated API key and an externalSubject. Browser onboarding is closed by default: other accounts receive 503 browser_voice_unavailable for type: "webrtc". Source support does not establish activation for your account. A WebRTC agent cannot be used as a phone connectTo or monitor destination. Agent creation does not issue a browser credential or initiate a call; follow Salesforce and browser calling for the browser session and call workflow.
Creating an agent does not check a customer recipient for reassignment. Authorized businesses can optionally Screen a Calling Recipient before an outbound call; that lookup concerns the customer recipient, not the agent.
Requires the voice_calls.write scope and the Voice Calls product entitlement.
Body Parameters
string
required
A human-readable label for the agent.
string
default:"phone"
phone or webrtc. Omitted, null, or an empty string defaults to phone. WebRTC creation requires explicit account enablement.string
Required for
phone: the destination number in E.164 format (e.g. +14155559876), normalized to digits when stored. Omit this field entirely for webrtc; even null or an empty string is rejected.string
Required for
webrtc: a nonblank stable user identifier, at most 200 characters, derived by your backend from the authenticated salesperson. It is bound to the calling API key; request fields cannot select a different issuer. Keep the Trackly API key server-side and authorize each person’s later session/call access in your backend.Response Fields
object
The created agent.
Hide Agent properties
Hide Agent properties
string
The agent’s unique identifier. Phone-agent IDs can be used in
connectTo.string
The label you supplied.
string
phone or webrtc.string | null
The normalized phone destination, or
null for a WebRTC agent.string
Included only for a WebRTC agent: the issuer-bound user identifier.
string | null
ISO 8601 timestamp when the agent was created.
Examples
curl -X POST https://api.tracklysms.com/api/v1/voice/agents \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Front Desk",
"type": "phone",
"number": "+14155559876"
}'
{
"agent": {
"id": "665f1e2a9c4b1a0012ab34cd",
"name": "Front Desk",
"type": "phone",
"number": "14155559876",
"createdAt": "2026-08-21T18:00:00.000000Z"
}
}
Browser agent onboarding
For an explicitly enabled account, send this body through your authenticated backend using the same API key that will own browser sessions. Omitnumber:
{
"name": "Salesforce Agent",
"type": "webrtc",
"externalSubject": "salesperson-123"
}
201 response has the same agent envelope, with type: "webrtc", number: null, and externalSubject: "salesperson-123". There is no Idempotency-Key replay contract for agent creation. A duplicate account-wide name or issuer-bound subject returns 409 agent_exists; use List Agents to resolve the intended mapping after an uncertain response.
Error Codes
| Status | Code | Meaning |
|---|---|---|
| 403 | voice_not_entitled | Voice calling is not enabled for your account. |
| 409 | agent_exists | An account-wide name or WebRTC subject binding for this issuing key already exists. |
| 422 | missing_fields | name, a phone agent’s number, or a WebRTC agent’s externalSubject is missing or empty. |
| 422 | invalid_field | A supplied string field has the wrong JSON type. |
| 422 | agent_type_unsupported | type is not phone or webrtc. |
| 422 | invalid_browser_agent | WebRTC input includes number, or its subject is blank or exceeds 200 characters. |
| 503 | browser_voice_unavailable | Browser-agent onboarding is not enabled for this account. Phone-agent creation keeps its existing behavior. |