How the callers take turns
- The variant’s persona starts the call. It is the main caller. The other personas are with them on their end of the line.
- One person holds the phone at a time. Only the persona holding the phone speaks. When it changes hands, the voice and the behaviour change with it; two personas never talk at once.
- Whoever takes the phone heard the call so far. They pick up the conversation where it is, and don’t ask the agent to repeat what was already covered unless their persona would.
- A handover sounds like one. The persona passing the phone says a short, natural line, such as “hang on, let me get her”, before the next voice comes on.
In an Improv flow
In an Improv flow, you write the handover into the brief, in plain language, and the simulated caller decides when the moment has come.1
Mention the persona in the brief
Click Hand over in the brief’s footer. It writes “hand over to” at the cursor and opens a persona picker. You can also type
@ anywhere in the brief to open the same picker. The persona you pick appears in the brief as a chip.2
Say when, and whether it comes back
The sentences around the mention are the instructions: when to hand over, what the other person does, and when the phone comes back. The caller follows them as the conversation unfolds rather than at a fixed turn.
3
Check the cast
The Persona chip under the brief shows the main caller with +N for the personas the brief hands the phone to. Hover it for the list: ” starts the conversation and hands over to”, then each name.
You are calling to move your follow-up appointment to next week. When the agent asks which medications you are taking, you aren’t sure, so hand over to @Daughter, who reads the list. Once she has finished, she gives the phone back to you and you confirm the new time.In an Improv flow:
- Every extra persona hands back to the main caller, once its part is done or when the agent asks to speak to the main caller again. One extra persona can’t pass the phone straight to another; it goes back to the main caller first.
- Edge cases inherit the brief and its handovers from the happy path, the same way they inherit the rest of the brief. The Persona chip says “Inherited from the happy path”. Click Edit brief to start an edge case’s own brief from a copy and change who takes over.
- The model chooses the moment, so the exact turn the phone changes hands can differ from call to call. Use a Scripted flow when the handover has to happen at a specific point.
In a Scripted flow
In a Scripted flow, a handover is a step in the graph: Hand over to another persona (“Another persona takes over from here, or the flow persona takes back over”). Add it between two steps, like a silence.- In the inspector, Hand over to picks the persona who takes over. Every customer step after it is spoken by that persona, until the next handover.
- Once someone other than the flow persona has the phone, a later handover can choose Back to the flow persona instead.
- A handover can pass the phone from one extra persona to another; it doesn’t have to go back to the flow persona in between.
scriptAdherence: STRICT over the API), the switch happens exactly at the step and no line is added.
Rules and limits
- Voice calls only. Handovers need voices to switch between. A Scripted flow run as a chat simulation skips its handover steps, and Improv flows don’t run as chat simulations.
- The main caller can’t be handed to. A brief that mentions the variant’s own persona is refused on save. If a run plan’s persona override makes the main caller the same persona the brief hands over to, that handover is dropped for the run.
- Mentioned personas must be in the project. A brief or step that names a persona the project can’t read is refused on save.
- Personas in a cast can’t be deleted. A persona that a brief mentions or a handover step names is in use, the same as a persona a variant calls as. Choose another persona there before deleting it.
- Each persona keeps its own voice, including when the personas’ voices come from different speech providers.
Personas are stored in the brief by id, not name, so renaming a persona never breaks a handover.
Reading the results
On a call with more than one persona, the transcript labels every customer turn with the persona who said it, as Customer (name), the main caller included. Each handover appears as a divider, such as “Maria handed the phone to Daughter”, so you can see exactly where the agent met a new voice. A handover from a preceding flow works differently. That flow’s persona performs its part (an IVR, for example) and passes the phone to the persona under test without a word, and the part before that handover is left out of the metrics.Config as code
In a scripted flow, a handover is aCUSTOMER_HANDOFF step. handoffPersona names the persona who takes over, by its config name; leave it out to hand the phone back to the flow’s own persona.
prompt takes the same token the editor stores, with the persona’s id: @{persona:<persona-id>}.
API
Improv. A variant’sprompt carries mentions as @{persona:<persona-id>} tokens. Set it when you create the flow, or with PUT /v1/customer-flow/{flowId}/happy-path and the edge-case endpoints. The variant’s handoffPersonas lists the personas its brief hands the phone to, in order of first mention. It is read-only and derived from prompt; on an edge case that inherits the happy path’s brief it is empty, so read the happy path’s list.
{ "type": "CUSTOMER_HANDOFF", "handoffPersonaId": "<persona-id>" } hands the phone to that persona. handoffPersonaId: null hands it back to the flow’s own persona. Send the graph with PUT /v1/customer-flow/{flowId}/graph.
Errors to handle, all 400: