Transfer rules API

Transfer rules tell an agent when to bridge a caller to a human and how to reach them. They are scoped to one agent and gated on agents.read / agents.write.

The transfer rule object

{
  "id":                   "uuid",
  "widget_id":            "uuid",
  "name":                 "Manager escalation",
  "condition":            "caller asks for a manager",
  "destination_phone":    "+14165550199",
  "destination_label":    "Front desk",
  "enabled":              true,
  "priority":             0,
  "transfer_type":        "cold",
  "ring_timeout_seconds": 25,
  "warm_brief":           null,
  "sip_trunk_id":         null,
  "destination_sip_uri":  null,
  "created_at":           "2026-07-01T14:12:00Z",
  "updated_at":           "2026-07-01T14:12:00Z"
}

When several rules match, the highest priority wins. ring_timeout_seconds must be 10–60 and destination_phone must be E.164 (e.g. +14165550199).

Transfer types

transfer_type selects how the hand-off happens. Changing it recomputes the type-specific fields.

  • cold (default) — a blind transfer. The agent dials destination_phone and drops off.
  • warm — the agent calls the destination first, reads warm_brief to whoever answers, then bridges the caller in.
  • sip_refer — hands the call off over one of your BYO-carrier SIP trunks. Requires sip_trunk_id; destination_sip_uri is an optional sip: / sips: target.

List & create

GET  /api/v1/rest/agents/:id/transfer-rules
POST /api/v1/rest/agents/:id/transfer-rules
{
  "name":              "Manager escalation",
  "condition":         "caller asks for a manager",
  "destination_phone": "+14165550199",
  "transfer_type":     "warm",
  "warm_brief":        "A caller is on the line asking about a delivery."
}

Get, update, delete

GET    /api/v1/rest/agents/:id/transfer-rules/:ruleId
PATCH  /api/v1/rest/agents/:id/transfer-rules/:ruleId
DELETE /api/v1/rest/agents/:id/transfer-rules/:ruleId

PATCHis a partial update — only the fields you send change, and the type-specific fields you don't send are preserved. Switching an existing sip_refer rule's destination_sip_uri, for example, does not require re-sending sip_trunk_id.

Every field above is settable through the MCP tools create_transfer_rule / update_transfer_rule / get_transfer_rule / list_transfer_rules / delete_transfer_rule as well — see MCP. Full schemas are in the OpenAPI reference.