Set up queue overflow with Max hold

Max hold is the longest a caller waits in a queue before the queue gives up on the wait. When the wait ends, the queue does one of two things: it offers the caller a call back, or it moves the caller to another queue. Chain the moves and you build an escalation ladder — a first line, a second line, a third line — with no new concept to learn.

Set Max hold per queue. Leave it empty and the caller waits for as long as they stay on the line.

Before you start

• At least two call queues, each with the team that answers it. See Set up a call queue.
• A clear order for the ladder: which queue is the first line, which is the second, and where the last line ends.

Set Max hold and the end action

1. Open Settings → Voice.
2. Under Phone numbers, select the phone number, then go to the Queues tab.
3. Select the queue you want to limit.
4. In Max hold, enter the wait limit in minutes, from 1 to 240. Leave it empty for no limit.
5. When you set a limit, At the end of max hold appears. Pick one:
   Offer a call back — the caller is asked whether they want a call back. When the number offers no call backs, the caller leaves a message instead.
   Transfer to another queue — pick the queue the caller moves to. The move is silent.
6. Click Save changes.

The end action only appears when there is a limit to end. With no limit, the caller holds until they hang up, and nothing after the wait ever runs.

Build an escalation ladder

Set one queue at a time. Each queue points at the next.

1. On the first-line queue, set Max hold, choose Transfer to another queue, and pick the second-line queue.
2. On the second-line queue, set Max hold, choose Transfer to another queue, and pick the third-line queue.
3. On the third-line queue, set Max hold and choose Offer a call back. This is the end of the ladder.

The ladder now reads: first-line queue → second-line queue → third-line queue → call back. A caller who waits out every line is offered a call back at the end.

A transfer target counts as the next step only when that queue has its own Max hold. A target queue with no limit is where the ladder stops: the caller waits there for as long as they stay on the line.

What the caller hears

• On a transfer, nothing new. The hold audio carries on. The caller does not press a key and hears no announcement. The wait starts again in the next queue, under that queue’s own Max hold.
• On a call back, a question. The caller is asked whether they want a call back. When the line offers none, the caller leaves a message.

The skip rule

A queue that nobody is signed in to answers nothing, so the ladder does not park a caller there.

• If nobody in the next queue is online, the caller skips ahead to that queue’s own next step.
• If no queue in the chain has anyone online, the caller stays in the queue they are in and gets that queue’s call back, or leaves a message.

What happens at the end of the wait

At the end of Max hold, only a call an agent has answered, or is connecting to at that moment, keeps the caller in place. A phone that only rings does not hold the caller. When Atender cannot tell, the caller waits one more round and Atender checks again. The caller moves on, and the ring on the agent’s screen is withdrawn.

The queue reads the wait limit once per hold cycle, and a cycle lasts about 30 to 60 seconds. Expect the move up to about a minute after the limit, not to the second. An agent may see a short ring that is withdrawn when the caller moves on.

No loop

A queue cannot transfer to itself. A ladder that comes back on itself — queue A to queue B to queue A — is refused when you save, and so is a chain longer than ten queues. Give the last line a call back, or a target queue with no Max hold, so the ladder has an end.

See it in the flow builder

Open a voice flow and select a Send to Queue node. Under the queue picker, a read-only line states the queue’s Max hold and its next step, for example “Max hold 3 min, then transfers to Second line UK.” A queue with no limit reads “No max hold — a caller waits for as long as they stay.” The line is read-only here; change Max hold on the queue itself, in the Queues tab.

Set it from the API

You can set Max hold when you create a queue over the API.

POST /api/v1/voice/call-queues

• maxHoldSeconds — number — Seconds a caller may hold before the queue gives up on the wait. 60 to 14400. Empty, or null, means no limit — the default.
• maxHoldAction — string — What happens at the end of the wait. offer_callback (the default) offers a call back and takes a message when the number offers none. transfer_to_queue moves the caller to maxHoldTargetQueueId without saying anything to them.
• maxHoldTargetQueueId — string — The queue a transfer_to_queue end action moves the caller to. Another queue of this tenant, and not one that transfers back.

{
  "name": "first-line-uk",
  "friendlyName": "First line UK",
  "teamId": "a1b2…",
  "maxHoldSeconds": 180,
  "maxHoldAction": "transfer_to_queue",
  "maxHoldTargetQueueId": "c3d4…"
}

The API creates a queue with an end action; it does not update one. Change the end action of a queue that already exists in the app.

On a queue with a Max hold, a transfer_to_queue action needs a target queue. Any target must be another queue of this tenant, and the chain it builds may not come back on itself. Anything else is a 400:

• MAX_HOLD_TARGET_REQUIRED — the queue has a Max hold, the action is transfer_to_queue, and there is no target queue. With no Max hold the action does nothing, so no target is needed.
• MAX_HOLD_TARGET_NOT_FOUND — the target names no queue of this tenant.
• MAX_HOLD_TARGET_LOOP — the queues would transfer to each other, or the chain is too long to prove it ends.

Troubleshooting

• Symptom: The caller waited past the limit and nothing happened. Fix: The queue reads the limit once per hold cycle, so a move lands up to about a minute after the limit. If it never happens, confirm the queue has a Max hold and that the end action is set.

• Symptom: A transferred caller never leaves the second queue. Fix: The second queue needs its own Max hold for the ladder to carry on. A target with no limit is where the ladder stops.

• Symptom: Saving the transfer is refused. Fix: A queue cannot transfer to itself, and a ladder may not come back on itself. Point the last line at a call back instead.

See also

• Set up a call queue
• Configure callback
• Configure language overflow