Transfer and escalation

Escalation is a direction in the voice's behaviour block and a queued action on the guidance log, not a completed handover. telephony.can asks the provider whether transfer is available before anything attempts it, and on the live carrier that capability is not enabled — so a caller who asks for a person gets an honest ending and a dated call-back rather than a hold that goes nowhere.

Status: Foundation In development What this means
Audience: both
Channels: phone
In the app: #/calls
Last verified: 2026-09-10
Product version: 6.3.2

What exists, and what it stops short of#

Piece	State	What it does
The escalation direction	Available	A behaviour setting telling the voice when to stop handling something itself
The queued transfer	Foundation	`engine:transfer` on the guidance log; the worker reads it
The capability question	Available	`telephony.can(provider, 'transfer')` — asked, never assumed
A completed warm handover to a colleague	Not enabled on the live carrier	The provider capability it depends on is off, so the leg is not bridged
The follow-up that carries the request	Available	A dated commitment on the `phone` channel, with the reason

The gap between rows three and four is the whole page. The code path is written, tested and gated on a provider capability; the live carrier account does not have that capability enabled. Describing this as "transfer works" would be true of the repository and false of every real call, which is precisely the kind of overclaim the status vocabulary exists to prevent.

Why a capability is asked instead of assumed#

Nothing above the adapter layer knows a provider's name. telephony.py holds what a line is, what an event means and who may be called when; providers differ from each other only through a CAPABILITIES table, and anything that wants to know whether recording, transfer or WebRTC is possible calls telephony.can(provider, capability).

Branching on a provider's name is how a system ends up unable to remove that provider. The consequence here is small and useful: the day a carrier account has transfer enabled, the capability answers true and the existing path runs. Nothing above it changes, and nothing has to be found and unpicked first.

What a caller experiences when they ask for a person#

The caller says something the escalation direction matches — asking for a manager, refusing to deal with an automated voice, raising something the hard rules say not to answer.
Result The voice stops trying to resolve it. What it says next comes from the escalation text on the profile, so a business writes its own words for this moment rather than inheriting a stock apology.
The request is recorded on the call and a follow-up is scheduled.
Result A call-back goes on the phone channel; work for a person — "send the quotation", "look at the account" — goes on the task channel. The commitment is dated, so it is a promise the system can keep rather than a sentence in a transcript.
If a colleague is watching the call, they can act on it directly.
Result The supervisor panel can hang up, mute the voice, send tones or queue the transfer. Guidance typed into the panel changes what the voice says next without the caller hearing the instruction.
The call ends and the record is written.
Result hangup_by attributes the ending to caller, model, owner, engine, carrier or agent, and the outcome and disposition are kept apart so a late provider webhook cannot overwrite what a person decided about the call.

Failure modes worth knowing#

The voice promises a colleague will ring back in ten minutes: That is a promise, and it is checked. A time the caller never said and never agreed to is refused by the follow-up tool, which answers "NOT recorded" so the model cannot claim a booking it does not have.
The escalation text is empty: The voice falls back to its general tone, which usually means it keeps trying to help. Write the escalation line; it is the one moment where a generic answer is most expensive.
Somebody expects a warm handover: Set the expectation in the escalation wording. A caller told "I will have someone call you straight back" and then called back within the hour has had a good experience; a caller left listening to a hold that never connects has not.
A queued transfer appears on the record: It means the action was recorded, not that a leg was bridged. Read the call outcome for what actually happened to the call.

Questions#

Can Connect put a caller through to a colleague right now?

Not on the live carrier. The capability is asked of the provider before anything attempts it and the answer today is no, so the escalation path ends in a recorded request and a dated call-back instead of a bridged leg. A colleague who is already watching the call can take control of it through the supervisor panel.

Is this a limitation of Connect or of the carrier?

Of the account. The provider capability is not enabled, and Connect refuses to attempt something the provider has not said it can do rather than failing in front of a customer. The path above the capability check is the same either way.

What should the escalation wording say?

What will actually happen and when — that the request is being recorded and somebody will ring back. Wording that implies an immediate transfer will be contradicted by the next ten seconds of the call, which is worse for the caller than a plain answer.