Skip to main content
POST
Attach Numbers to Agent

Overview

Points one or more of your phone numbers at the agent so inbound calls and texts run it. Any existing pathway or persona assignment on those numbers is replaced. Detach Numbers from Agent removes the agent but does not restore the previous assignment. Attaching also sets each Twilio number up for texting: Bland points its SMS webhook at Bland and adds it to a Messaging Service. This applies to numbers on your own Twilio account too, so an SMS webhook you set there is replaced. The step runs after the attach and doesn’t fail it. Calls answer with the agent’s production version once one is promoted; until then they run the newest version saved on the dev timeline at the time of the attach, so re-attach without environment after saving to refresh it. Texts run the version the binding was last compiled from: the version in compiled_from_version from the last attach that compiled one, or the production version after a later promote. Enterprise plans can pass environment: "staging" so calls run the version pinned to staging instead. The agent must have at least one saved version. A number bound to a V1 pathway that has a migration split can’t be attached while the split exists, even at 0%. The request returns 409 MIGRATION_EXPERIMENT_NUMBER and attaches nothing. Delete the split first. Requires an admin, owner, operator, or prompter role.

Headers

string
required
Your API key for authentication.

Path Parameters

string
required
The agent’s unique identifier.

Body Parameters

string[]
required
Phone numbers to attach, each exactly as it appears on your account (for example +18005551234). Must be a non-empty array of non-empty strings; surrounding whitespace is trimmed. Returns 400 INVALID_BODY if the array is missing, empty, or contains a non-string. Returns 400 INVALID_INBOUND_NUMBERS if any number is not on your account, in which case nothing is attached.
string
Which environment calls to these numbers run: production or staging. When you omit it, a number already attached to this agent on staging stays on staging, and every other number answers on production. Pass production to move a staging number back. Any other value returns 400 INVALID_BODY.staging is enterprise only and applies to calls. Texts to a staging number run the same version as texts to the agent’s other numbers, not the staging version. Every check below runs before anything is written:
  • 403 ENTERPRISE_REQUIRED if your organization is not on an enterprise plan.
  • 409 STAGING_NUMBER_UNSUPPORTED if your account or any of the numbers runs on dedicated infrastructure.
  • 409 AGENT_ENV_UNPINNED if nothing is published to staging.
  • 409 AGENT_VARIABLE_UNRESOLVED if a variable the staging version references has no staging value, or 409 AGENT_SNAPSHOT_INVALID if the staging version can’t run.
boolean
default:"false"
When true, attaches only numbers that have no persona and no pathway assigned. If any number in inbound_numbers is already assigned, the request returns 409 NUMBER_ALREADY_ASSIGNED and attaches nothing. Any value other than a boolean returns 400 INVALID_BODY.
boolean
default:"false"
When true, writes only numbers that are still attached to this agent. Use it with environment to move a number between production and staging without taking back a number that another request moved. If any number is no longer attached to this agent, the request returns 409 NUMBER_NOT_BOUND and changes nothing. Any value other than a boolean returns 400 INVALID_BODY.

Response

string
The agent ID from the request path.
string
ID of the persona the attached numbers route through. Created on the agent’s first attach and reused afterwards.
string
ID of the pathway compiled from the agent for this binding. The ID stays the same across attaches. An attach that compiles a version (see compiled_from_version) replaces this pathway’s graph.
string | null
ID of the agent version this attach compiled the binding from: the newest version on the dev timeline. Versions saved on branches are ignored.null when the attach kept the existing binding as it was. That happens on a staging attach, and when you pass environment and every number is already attached to this agent. If such an attach finds no binding to keep, it builds one from the production version (or from the newest version when nothing is promoted) and returns that version’s ID.
string[]
The numbers that were attached, after trimming.
null | array
null on success, or a list of error objects if the request failed. Returns 404 NOT_FOUND for an unknown agent, 400 NO_VERSIONS when the agent has no saved versions, 422 COMPILE_FAILED when the version to compile cannot be compiled, and 409 MIGRATION_EXPERIMENT_NUMBER when a number’s pathway has a migration split. With only_if_unassigned or only_if_bound, it can also return 409 NUMBER_ALREADY_ASSIGNED or 409 NUMBER_NOT_BOUND.

Docs for agents: llms.txt