Transfers

Inbound calls expose a transfer_to_human tool to the conversation model. When invoked, OpenPhn walks a fallback chain of up to five destination phones configured on the number.

Configuring destinations

Each number has a transfer_destinations list:

[
  {
    "label": "Front desk",
    "phone": "+14155551111",
    "enabled": true,
    "order": 0,
    "max_attempts": 1
  },
  {
    "label": "On-call manager",
    "phone": "+14155552222",
    "enabled": true,
    "order": 1,
    "max_attempts": 1
  }
]

Rules:

• Up to 5 destinations.
• order must be contiguous starting at 0.
• phone must be a valid E.164 NANP number.
• enabled: false skips the destination without reordering.

Transfer flow

1. Conversation model decides a human is needed and invokes transfer_to_human.
2. OpenPhn plays a brief hold message to the caller (best-effort).
3. Twilio dials destination at order=0. If no answer / busy / voicemail, falls through to order=1, and so on.
4. On success, the call's outcome logs the destination's label and phone.

Update destinations

PATCH /v1/numbers/{number_id} with a new transfer_destinations array. The whole list is replaced.