Skip to main content
Plenty of real calls have more than one person on the caller’s end. A patient starts the call and hands the phone to the caregiver who knows the medication list. A couple books a table and the second partner takes over to sort out the date. A parent passes the phone to a teenager to confirm their own details. Your agent has to notice that someone new is speaking, keep track of who said what, and not ask the second person for what the first already gave. Roark simulates this by letting the simulated caller hand the phone to another persona in the middle of the call. Each persona speaks in its own voice, with its own accent, pace and temperament, so your agent hears a real change of speaker.

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.
What decides when the phone changes hands depends on the authoring mode.

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.
For example, with a persona for the patient on the variant and a second persona for her daughter:
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.
The editor won’t save a handover that names the persona who already has the phone at that step, or a handover with no persona picked while the flow persona still has it. The canvas flags both on the step itself. By default the persona passing the phone says a short line as it does, the same as in Improv. In a flow that runs its script strictly (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 a CUSTOMER_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.
In an improv flow, there is no name-based mention yet. The prompt takes the same token the editor stores, with the persona’s id: @{persona:<persona-id>}.

API

Improv. A variant’s prompt 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.
Scripted. A graph step { "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: