Skip to content

Explore Seny

Transfer rules

Documentation

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.

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.

Talk to Seny