Trillet AI logo

Update Phone Number Configuration

Bind a call agent to a phone number and change its recording, office hours, transfer caller ID, tags and label.

PUThttps://api.trillet.ai/v1/api/twilio/phone-numbers/{phoneNumberId}/config

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-idstringrequired

Workspace identifier for the API.

Path Parameters

phoneNumberIdstringrequired

The number's _id from List Phone Numbers.

Request Body

agentIdstring | null

The call agent to bind to this number. null unassigns the current agent.

recordingEnabledboolean

Whether calls on this number are recorded.

officeHoursobject | null

Office hours for the number. The object you send replaces the stored one, so send every field you want to keep. null clears it.

transferCallerIdModestring

Caller ID shown on transferred calls: from-transferee (default, the original caller's number) or from-transferor (your Trillet number).

metadataTagsobject

Key/value tags as an object of strings, for example {"location": "Downtown"}. Replaces all existing tags.

secretBindingsobject

Map 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.

labelstring

A 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

StatusBodyWhen
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"
}
Trimmed
{
  "_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