Assign Phone Number to Agent
Assign a phone number to an agent's call flow, set recording, office hours and metadata, and configure the SIP trunks.
This is how a number gets attached to an agent: Create Call Agent ignores phoneNumberIds. The agent must already belong to a live call flow. If the number was on another agent, it is moved to this one.
Requires the agent:edit permission.
Path Parameters
agentIdstringrequiredThe ID of the agent whose call flow will be bound to the phone number.
phoneNumberIdstringrequiredThe _id of the phone number to bind, from List Phone Numbers. It must belong to this workspace.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API. Required to scope the binding operation.
Request Body
A JSON body is required. Send {} if you don't want to set anything.
recordCallsbooleanWhether calls on this number are recorded. Left out, the current setting is kept.
recordingPublicbooleanWhether recordings are publicly accessible. Left out, the current setting is kept.
officeHoursobjectOffice hours for the number, in the same shape as Update Phone Number Configuration: enabled, start and end (HH:MM), timezone (IANA), allowedDays (Mon to Sun) and blockedDates. Left out, the stored office hours are kept.
metadataTagsobjectKey/value tags to store with the number, as an object of strings, for example { "department": "sales", "priority": "high" }.
The tags you send replace all existing tags, and leaving metadataTags out clears them. Send the current tags again to keep them.
labelstringA label for the number. Left out, the current label is kept.
transferCallerIdModestringCaller ID shown on transferred calls: from-transferee (default, the original caller's number) or from-transferor (your Trillet number).
secretBindingsobjectMap of alias to workspace secret name, for example { "crm_key": "acme-crm" }. Every name must be an existing secret in this workspace. Replaces all existing bindings; left out, they are kept.
Response Fields
agentobjectThe updated agent object, including its bound phone number IDs.
phoneNumberobjectThe updated phone number object after binding and SIP trunk configuration.
pathwayIdstringThe ID of the call flow associated with this assignment.
directionstringThe direction of the call flow (outbound or bidirectional).
Errors
| Status | Body | When |
|---|---|---|
400 | {"error": "Workspace ID is required"} | No x-workspace-id |
400 | {"error": "..."} | secretBindings is malformed or names a secret that doesn't exist |
403 | {"error": "Insufficient permissions"} | Your role doesn't have agent:edit |
404 | {"message", "code": "AGENT_NOT_FOUND", "error"} | No agent with this ID in the workspace |
404 | {"message", "code": "PHONE_NUMBER_NOT_FOUND", "error"} | No number with this ID in the workspace |
409 | {"message", "code": "CALL_FLOW_ARCHIVED", "error"} | Every call flow of the agent is archived or inactive. Restore or turn one on first |
409 | {"message", "code": "AGENT_HAS_NO_CALL_FLOW", "error"} | The agent isn't used by any call flow |
500 | {"error": "..."} | Unexpected server error |
When a request is refused, nothing is changed.
{
"recordCalls": true,
"recordingPublic": false,
"officeHours": {
"enabled": true,
"start": "09:00",
"end": "17:00",
"timezone": "America/New_York",
"allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"],
"blockedDates": []
},
"metadataTags": {
"department": "support",
"priority": "high"
}
}{
"agent": {
"_id": "d5d5d5d5d5d5d5d5d5d5d5d5",
"status": "ready",
"phoneNumberIds": ["d6d6d6d6d6d6d6d6d6d6d6d6"]
},
"phoneNumber": {
"_id": "d6d6d6d6d6d6d6d6d6d6d6d6",
"agentId": "d5d5d5d5d5d5d5d5d5d5d5d5",
"pathwayId": "d2d2d2d2d2d2d2d2d2d2d2d2",
"flowType": "call",
"status": "active",
"recordingEnabled": true,
"recordingPublic": false,
"officeHours": {
"enabled": true,
"start": "09:00",
"end": "17:00",
"timezone": "America/New_York",
"allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"],
"blockedDates": []
},
"metadataTags": {
"department": "support",
"priority": "high"
},
"transferCallerIdMode": "from-transferee"
},
"pathwayId": "d2d2d2d2d2d2d2d2d2d2d2d2",
"direction": "bidirectional"
}Last updated on