Trillet AI logo

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.

POSThttps://api.trillet.ai/v1/api/agents/{agentId}/bind/{phoneNumberId}

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

agentIdstringrequired

The ID of the agent whose call flow will be bound to the phone number.

phoneNumberIdstringrequired

The _id of the phone number to bind, from List Phone Numbers. It must belong to this workspace.

Headers

x-workspace-idstringrequired

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

recordCallsboolean

Whether calls on this number are recorded. Left out, the current setting is kept.

recordingPublicboolean

Whether recordings are publicly accessible. Left out, the current setting is kept.

officeHoursobject

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

metadataTagsobject

Key/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.

labelstring

A label for the number. Left out, the current label is kept.

transferCallerIdModestring

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

secretBindingsobject

Map 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

agentobject

The updated agent object, including its bound phone number IDs.

phoneNumberobject

The updated phone number object after binding and SIP trunk configuration.

pathwayIdstring

The ID of the call flow associated with this assignment.

directionstring

The direction of the call flow (outbound or bidirectional).

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