Update Phone Number Configuration
Bind a call agent to a phone number and change its recording, office hours, transfer caller ID, tags and label.
Every field is optional. A field you leave out keeps its current value, so you can send only what you want to change. To unassign the agent, send "agentId": null.
Binding an agent attaches the number to that agent's live call flow and sets the number's status to active. If the agent has no call flow yet, the number is saved with status ready and goes live when you create the agent's call flow. An agent whose call flows are all archived or inactive is refused (see Errors).
Your role needs the phone_number:edit permission. Otherwise the request fails with 403 {"error": "Insufficient permissions"}.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
Path Parameters
phoneNumberIdstringrequiredThe number's _id from List Phone Numbers.
Request Body
agentIdstring | nullThe call agent to bind to this number. null unassigns the current agent.
recordingEnabledbooleanWhether calls on this number are recorded.
officeHoursobject | nullOffice hours for the number. The object you send replaces the stored one, so send every field you want to keep. null clears it.
transferCallerIdModestringCaller ID shown on transferred calls: from-transferee (default, the original caller's number) or from-transferor (your Trillet number).
metadataTagsobjectKey/value tags as an object of strings, for example {"location": "Downtown"}. Replaces all existing tags.
secretBindingsobjectMap of alias to workspace secret name, for example {"crm_key": "acme-crm"}. Aliases and names use lowercase letters, numbers, hyphens and underscores. Every name must be an existing secret in this workspace, otherwise the request fails with 400. Replaces all existing bindings.
labelstringA label for the number.
Maximum call duration is not a phone number setting. It belongs to the call flow (settings.callSetting.maxCallDuration), and a maxCallDuration sent here is ignored.
Response
The updated phone number, in the same shape as an item from List Phone Numbers. agentId and pathwayId are returned as full objects, or null.
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 |
404 | {"error": "Phone number not found"} | No number with that ID in this workspace (also for a malformed ID) |
404 | {"message", "code": "AGENT_NOT_FOUND", "error"} | agentId isn't an agent in this workspace |
409 | {"message", "code": "CALL_FLOW_ARCHIVED", "error"} | Every call flow of the agent is archived or inactive. Restore or turn one on first |
500 | {"error": "Failed to update phone number configuration", "message": "..."} | Server error |
When a request is refused, nothing is changed.
{
"agentId": "a5a5a5a5a5a5a5a5a5a5a5a5",
"recordingEnabled": true,
"officeHours": {
"enabled": true,
"start": "09:00",
"end": "17:00",
"timezone": "America/New_York",
"allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"],
"blockedDates": []
},
"transferCallerIdMode": "from-transferee",
"metadataTags": {
"location": "Downtown"
},
"label": "Front desk"
}{
"_id": "a4a4a4a4a4a4a4a4a4a4a4a4",
"phoneNumber": "+14155550123",
"sid": "1293384261075731499",
"provider": "telnyx",
"status": "active",
"flowType": "call",
"agentId": {
"_id": "a5a5a5a5a5a5a5a5a5a5a5a5",
"name": "Front Desk"
},
"pathwayId": {
"_id": "a6a6a6a6a6a6a6a6a6a6a6a6",
"name": "Front Desk Call Flow"
},
"recordingEnabled": true,
"officeHours": {
"enabled": true,
"start": "09:00",
"end": "17:00",
"timezone": "America/New_York",
"allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"],
"blockedDates": []
},
"transferCallerIdMode": "from-transferee",
"metadataTags": {
"location": "Downtown"
},
"label": "Front desk",
"workspaceId": "a1a1a1a1a1a1a1a1a1a1a1a1"
}Last updated on