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,
"active_windows": null,
"fallback_rule_id": 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).
Active windows
active_windows limits when a rule transfers. Leave it null (or send []) and the rule is always active. Otherwise it is a list of windows in the agent's time zone:
"active_windows": [
{ "days": ["mon","tue","wed","thu","fri"], "start": "07:00", "end": "08:00" },
{ "days": ["mon","tue","wed","thu","fri"], "start": "17:30", "end": "18:00" }
]Times are 24-hour HH:MMand a window must end after it starts. For one that crosses midnight, send two windows. When a rule has windows, they alone decide when it transfers. The agent's department business hours are not checked for that rule.
Outside its windows the rule uses fallback_rule_id, which must be another rule on the same agent, such as the department voicemail. With no fallback the transfer is refused, and the agent books what it can or takes a message. Clearing active_windows also clears the fallback. A fallback that would loop back to the rule is rejected.
Transfer types
transfer_type selects how the hand-off happens. Changing it recomputes the type-specific fields.
cold(default) — a blind transfer. The agent dialsdestination_phoneand drops off.warm— the agent calls the destination first, readswarm_briefto whoever answers, then bridges the caller in.sip_refer— hands the call off over one of your BYO-carrier SIP trunks. Requiressip_trunk_id;destination_sip_uriis an optionalsip:/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/:ruleIdPATCHis 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.