Call Forwarding

A forward sends a call to an external PSTN number: find-me/follow-me to a mobile, an after-hours cell, or a backup site. It’s a route target like any other (dest_kind: "forward"), so a DID, extension, queue exit, or ring-group exit can all forward, and it can also appear as a forward flow node.

The forward object

{
  "id": "fwd_01j3nnnyejaj858ffg9t764m43",
  "account_id": "acc_01jf18ah3jeb5w6dfp27sgjsbt",
  "name": "Alice mobile",
  "number": "12025550100",
  "trigger": "always",
  "timeout_sec": 30,
  "cid_mode": "passthrough",
  "confirm": 1,
  "overflow_dest_kind": "voicemail",
  "overflow_dest_id": "vm_01jg8asp59ps9rtt7azhrhvcre"
}

Field	Purpose
number	E.164 destination, dialed out through the normal outbound path.
trigger	When the forward fires: always · busy · no_answer · unreachable.
timeout_sec	How long to ring the forward before it’s a no-answer.
cid_mode	Caller-ID presentation: passthrough (the original caller), did (the inbound DID), or custom (use cid_number).
confirm	1 enables press-1 screening.
overflow_dest_kind / overflow_dest_id	Where the call goes if the forward isn’t answered (see Overflow).

The forwarded leg reaches the PSTN through the same outbound infrastructure as any other external call: outbound routes to a trunk, or the wholesale carrier by default.

Press-1 confirm screening

The classic problem with forwarding to a mobile: the carrier’s voicemail answers when the phone is off or unreachable, swallowing the call so it never falls back. Confirm screening fixes that. With confirm: 1, when the forward leg answers, the callee hears a prompt before the call is bridged:

“You have a call. Press 1 to accept, or press 2 to decline.”

• Press 1 → the call bridges normally.
• Press 2, no press, or timeout → treated as no-answer, so the call follows the overflow path instead of being eaten by the mobile’s voicemail.

This is the same confirm fence used by ring groups, and the prompt is available in every supported TTS language. It’s what makes find-me/follow-me reliable.

Overflow

When a forward isn’t answered (no_answer, busy, or a declined/unconfirmed screen), the call recurses to the configured overflow target rather than simply hanging up:

• overflow_dest_kind / overflow_dest_id is an ordinary route target, most often a voicemail, but it can be a flow, queue, another forward, and so on.
• If no overflow is set, the call hangs up (the fail-safe default).

Overflow is synthesized recursively, exactly like queue and ring-group exits, so chains terminate cleanly (bounded against loops).

Forward as an overflow target, too

Because forward is itself a valid dest_kind, it works in both directions: a queue or ring group can overflow to a forward (e.g. roll unanswered support calls to an on-call mobile), and a forward can overflow to voicemail. Compose them to build find-me/follow-me escalation.

Triggers

The trigger decides when a forward applies:

trigger	Fires when
always	Unconditionally: the number always forwards.
busy	The target is on another call.
no_answer	The target didn’t answer within timeout_sec.
unreachable	The target’s device has no live registration.

always is a straight redirect; the conditional triggers let you forward only when the primary destination can’t take the call.

Status & roadmap

The forward model, confirm screening, and overflow are live. A first-class /v1 CRUD API for managing forwards is on the roadmap; today they’re configured through the control plane alongside the other routing objects.