Skip to main content
Inbound routing runs a workflow at call time to decide which agent answers an incoming call. Each organization has at most one inbound-routing config. When a call arrives on one of your numbers, Anyreach passes the call details into your workflow, and the workflow returns the agent (and any per-call context) that should handle it. Use this when a single number should route to different agents depending on who is calling, which number was dialed, the time of day, or any logic you can express in a workflow. If you do not need dynamic routing, assign an agent directly to a number instead — see Telephony overview.

​
How it works

When a call comes in, Anyreach checks for an inbound-routing config on your organization. If one exists and enabled is true, it runs your workflow_definition, feeds in the call details, and reads the workflow’s output to resolve the agent. 
inbound call
    │
    ▼
routing config exists and enabled?
    │ no ──────────────► (number's own assignment / disconnect)
    │ yes
    ▼
run workflow_definition  ── fails / times out ──► fallback_agent_id?
    │ returns output                                  │ set ──► fallback agent answers
    ▼                                                 │ empty ─► disconnect
reject == true ──► disconnect
    │ false
    ▼
agent_id (+ version, initial_context, custom_metadata) answers
The config is built and edited with the same workflow builder used elsewhere in the product, so the input and output of the routing workflow are fixed contracts. See Workflows overview for how to build the workflow itself.

​
Workflow input

The workflow receives these fields on its input step:
FieldTypeDescription
caller_numberstringThe phone number of the person calling in (E.164 format).
called_numberstringThe phone number that was dialed (your number).
trunk_idstringThe SIP trunk ID the call arrived on.
organization_idstringYour organization ID.
timestampstringISO 8601 timestamp of when the call arrived.
sip_headersobjectSIP headers from the inbound call.

​
Workflow output

The workflow’s output step returns these fields. Every field is optional.
FieldTypeDefaultDescription
rejectbooleanfalseSet to true to decline the call. The call is disconnected and no agent runs.
agent_idstring—The agent ID to handle this call.
versionnumberlatest publishedAgent version to use. Omit to use the latest published version of agent_id.
initial_contextstring""Context injected into the agent’s system prompt for this call.
custom_metadataobject—Custom metadata attached to the resulting conversation.
skip_pre_conversation_workflowbooleanfalseIf true, skip the agent-level pre-conversation workflow.
If the workflow returns neither reject: true nor a resolvable agent, the config’s fallback agent is used. If there is no fallback agent, the call is disconnected.

​
Config fields

FieldTypeRequiredDefaultDescription
workflow_definitionobjectYes—The routing workflow that picks the agent. Cannot be empty.
fallback_agent_idstringNonullAgent used if the workflow fails or times out. Empty means the call is disconnected on failure.
fallback_agent_versionnumberNonullVersion of the fallback agent. Omit to use its latest published version. Cleared automatically when fallback_agent_id is removed.
enabledbooleanNotrueWhen false, the config is ignored and the workflow does not run.
The routing workflow runs only when a config exists and enabled is true. If the workflow throws or times out, Anyreach falls back to fallback_agent_id; with no fallback configured, the call is disconnected.

​
API

All routes are org-scoped — the config is resolved from the organization on the token. There is exactly one config per organization. Authenticate with Authorization: Bearer <token>; user PATs (pat_) also require X-Anyreach-Org: <organization_id>.
MethodPathDescriptionNotes
GET/core/inbound-routing-configGet the config for the current organization.Returns null if none exists.
POST/core/inbound-routing-configCreate the config.Returns 409 if a config already exists.
PUT/core/inbound-routing-configUpdate the existing config.Returns 404 if none exists.
DELETE/core/inbound-routing-configDelete the config.Returns 204; 404 if none exists.
Reading requires the inbound_routing_configs:read or inbound_routing_configs:manage scope. Creating, updating, and deleting require inbound_routing_configs:manage.

​
Create

curl -X POST https://api.anyreach.ai/core/inbound-routing-config \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_definition": { "...": "..." },
    "fallback_agent_id": "agent_123",
    "fallback_agent_version": 4,
    "enabled": true
  }'
The response is the stored config: 
{
  "id": "...",
  "organization_id": "...",
  "workflow_definition": { "...": "..." },
  "fallback_agent_id": "agent_123",
  "fallback_agent_version": 4,
  "enabled": true,
  "created_at": "...",
  "updated_at": "..."
}

​
Update

PUT accepts the same fields, all optional — only the fields you send are changed. Set fallback_agent_id to null to remove the fallback agent; fallback_agent_version is cleared automatically when you do. 
curl -X PUT https://api.anyreach.ai/core/inbound-routing-config \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Telephony overview

Numbers, trunks, and how inbound and outbound calls connect.

Workflows overview

Build the routing workflow and other automation.