Request agent

Rings one or more of your team's extensions in the background and immediately continues the flow. Place a Say or Play node next to give callers a hold exp…

What it does

Rings one or more of your team's extensions in the background and immediately continues the flow to the next node. The flow you put next to it controls what the caller hears while they wait (Say "please hold", a looping Play Audio, an IVR Gather "press 1 for voicemail", etc.). When an agent picks up, the caller is bridged in — interrupting whatever node they were on. If the flow chain finishes before any agent answers, the call follows the chain's own terminal: voicemail, hangup, transfer to a fallback flow, whatever you wired.

This shape is intentional. The node doesn't decide what hold music to play, doesn't have a "no answer" branch, doesn't park the call in a silent room while it waits. All of that belongs to the rest of your flow — Request agent just kicks off the rings and gets out of the way.

Every device on a single extension (desk phone, softphone, mobile app) always rings together. The strategy field controls behavior between extensions: parallel rings every selected extension at once and the first answer wins; sequential rings the first extension's devices for the ring window, then the next extension, and so on (hunt-group).

When to use it

• Ring a small team of agents and start a hold-music loop next to it — when someone picks up, they're auto-bridged with the caller
• Implement a tiered escalation: ring the on-shift agent first, then fall back to the manager's extension after the first ring window expires (use sequential)
• Route a phone number to "an extension" via the phones page binding — set extensionIdsFromBinding: true so the target id is read from the phone's config.extensionId instead of being hardcoded
• Pick the target dynamically from a Custom script: write the resolved id into vars.targetExtensionId, then put "{{vars.targetExtensionId}}" in the extensionIds list. Templated entries are rendered before the originate fanout

Configuration

Rings one or more of your team's extensions in the background and immediately continues the flow. Place a Say or Play node next to give callers a hold experience while agents ring (e.g. "please hold" + looping music). When an agent answers, the caller is bridged in — interrupting whatever node was playing. If the flow's chain finishes before any agent answers, the call follows the flow's terminal (voicemail, hangup, etc.).

Outgoing events: next

Example: ring two agents, play hold music, fall to voicemail

The Say + Play Audio chain plays to the caller while both extensions ring. Whichever device picks up first is bridged in (the caller hears the music cut off mid-loop and the agent comes on the line). If neither answers before the music chain ends, the flow lands on Record and takes a voicemail.

[onFlowStart]
   ↓
[answer]
   ↓
[say "Thanks for calling — connecting you now."]
   ↓
[requestAgent extensionIds=[alice, bob] timeoutSecs=25]   ← fire-and-forget
   ↓
[playAudio https://cdn.example.com/hold-loop.mp3]
   ↓
[record voicemail]
   ↓
[hangup]

The corresponding JSON for the Request agent node:

{
  "id": "ring-team",
  "type": "requestAgent",
  "config": {
    "extensionIds": ["ext-alice-uuid", "ext-bob-uuid"],
    "strategy": "parallel",
    "timeoutSecs": 25
  },
  "on": { "next": "play-hold-music" }
}

Gotchas

• No more no.answer / failed / call.bridged branches. The node has a single outgoing edge (next). Existing flows wired against the old branched model still route via legacy on['no.answer'] / on['call.hangup'] fall-back priority, but new flows should wire through next and let the chain's terminal handle the no-agent case.
• Hold music belongs to the flow, not the extension. Earlier versions read dialMusic / dialMusicFromBinding off the extension. Those fields are ignored now; put a Play Audio node after Request agent to control what callers hear.
• The agent's answer interrupts whatever the caller is on. If Request agent is followed by a Gather Digits and an agent picks up while the caller is mid-press, the gather is cancelled and the bridge happens immediately. Side-chain onAgentAnswered triggers fire at the same moment, so whispers / screen pops / CRM logging still run.
• The flow's terminal cancels still-ringing agents. If the chain reaches a Hangup or finishes a Record node before any agent answers, all in-flight originate legs are REST-cancelled. Agents see their phone stop ringing.
• Per-extension ring timeouts win. The timeoutSecs on this node is a default; an extension that has its own ringTimeoutSecs set on its DB row will use that value instead.
• first is a deprecated alias for parallel. Old saved flows may have strategy: 'first'; the runtime treats it as parallel for back-compat. New flows should use parallel or sequential only.