> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Caller cues

> Change how the simulated caller feels, what language it speaks, where it is, or when it cuts in, at a point in the call

A [persona](https://docs.roark.ai/documentation/simulation-testing/personas.md) sets who the caller is for the whole call: language, accent, mood, pace. Real callers change partway through. They get angry when the agent reads back the wrong card, switch to Spanish when they get stuck, walk out onto a busy street, or talk over the agent the moment they hear a mistake. **Caller cues** let a [customer flow](https://docs.roark.ai/documentation/simulation-testing/customer-flows.md) steer the simulated caller like that, at a point you choose.

A cue is a token written inline in the flow's text: an Improv brief, or the content of a Scripted step. From that point on, the caller follows it.

## The four cues

| Cue | Token | From that point, the caller |
| :- | :- | :- |
| **Emotion** | `#{emotion:angry}` | Feels that emotion |
| **Language** | `#{language:es}` | Speaks that language |
| **Noise** | `#{noise:<environment-id>}` | Moves somewhere that sounds different |
| **Interrupt** | `#{interrupt}` | Cuts in on the agent. The sentence around the token says when, and what to say |

* **Emotion** takes one of the persona base emotions, in lower case: `neutral`, `cheerful`, `confused`, `frustrated`, `skeptical`, `rushed`, `distracted`, `angry`, `anxious`, `sad`. The persona's base emotion is where the call starts; an emotion cue moves it from there.
* **Language** takes an ISO 639-1 code with an optional region, such as `es`, `fr` or `pt-BR`. Your agent has to understand the language for the rest of the call to make sense.
* **Noise** takes the id of one of your project's [environments](https://docs.roark.ai/documentation/simulation-testing/environments.md), so renaming the environment never breaks the cue. Pick one whose background noise matches the new place, such as a train or a street. An environment with no background noise moves the caller somewhere quiet.
* **Interrupt** takes no value. Write the condition in the same sentence: "When the agent reads back the card number, `#{interrupt}` and say it's wrong."

## Adding a cue in the app

In the brief editor of an Improv flow, or in a step's content on the Scripted canvas, type `#`. A menu opens with **Emotion**, **Interrupt**, the environments the caller can move to, and the languages it can speak. The cue you pick appears in the text as a chip, such as **Feels angry**, **Speaks Spanish** or **Interrupt**.

## In an Improv flow

An Improv brief is one set of instructions the caller follows as the conversation unfolds, so each cue takes effect when the condition you wrote around it comes true. Write the token where it reads as part of the sentence:

> You were charged twice for last week's cleaning and want one charge refunded. When the agent asks for the card, read out 4111 1111 1111 1111. When the agent reads the card number back, `#{interrupt}` and say that is the card. If the agent says the refund takes more than a week, `#{emotion:angry}`. Once the refund is agreed, `#{noise:<street environment id>}` and say you have to go.

* **The caller chooses the moment** from the condition, so the exact turn a cue fires on can differ between calls. Use a Scripted flow with strict script adherence when it must happen at one step.
* **An edge case with its own brief** takes its interrupts from that brief only.

Over the API the brief is the variant's `prompt`, and the tokens are plain text in it:

```typescript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
await client.customerFlow.updateHappyPath(flowId, {
  prompt:
    "You were charged twice for last week's cleaning and want one charge refunded. " +
    'When the agent reads the card number back, #{interrupt} and say that is the card. ' +
    'If the agent says the refund takes more than a week, #{emotion:angry}.',
})
```

## In a Scripted flow

In a Scripted flow, put the cue in the content of the step where it should happen. How it runs depends on the flow's script adherence (`scriptAdherence` over the API):

* **Strict**: each step's cues take effect when the call reaches that step. On an **Agent** step, `#{interrupt}` means cut in while the agent is speaking that step, and the rest of the sentence says when. The tokens and the interrupt sentence are taken out of what is said or listened for.
* **Loose** (the default): the whole script is handed to the caller as one set of instructions, so cues read as instructions in it and each `#{interrupt}` sentence says when to cut in during the call. Lines said word for word (the **First message**, and verbatim customer turns) lose their cues here; put a cue on a **Customer** step instead.

This strict script uses every cue. Each next step sits inside the previous step's `steps`:

```typescript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
await client.customerFlow.create({
  type: 'SCRIPTED',
  title: 'Double charge, card read back',
  scriptAdherence: 'STRICT',
  graph: [
    {
      type: 'CUSTOMER_FIRST_MESSAGE',
      content: '#{emotion:angry} Hi, I was charged twice for my cleaning.',
      steps: [
        {
          type: 'AGENT_TURN',
          content: 'The agent asks for the card that was charged.',
          steps: [
            {
              type: 'CUSTOMER_TURN',
              content: '#{emotion:frustrated} Read out the card number 4111 1111 1111 1111.',
              steps: [
                {
                  type: 'AGENT_TURN',
                  content:
                    'The agent reads the card number back. #{interrupt} Cut in once it has read eight digits and say that is the card.',
                  steps: [
                    {
                      type: 'CUSTOMER_TURN',
                      content: '#{noise:<train environment id>} Say you are boarding a train.',
                    },
                  ],
                },
              ],
            },
          ],
        },
      ],
    },
  ],
})
```

> [!NOTE]
>
> Steps side by side in one `steps` array (or at the top level of `graph`) are alternative branches, not a sequence. Nest each step inside the one before it, as above.

## In the transcript

Each cue that fires is marked in the call's transcript, at the point it happened:

| Cue | Shown as |
| :- | :- |
| Emotion | Emotion changed to cheerful |
| Language | Language switched to Spanish |
| Noise | Environment changed to Train |
| Interrupt | Interrupted the agent |

Use these to check that a cue fired where you expected before reading what the agent did next.

## Rules and limits

* **Voice calls only.** In a [chat simulation](https://docs.roark.ai/documentation/simulation-testing/chat-simulations.md) there is no voice or sound to change: an emotion cue on a step the caller phrases still reads as an instruction, every other cue is dropped, and a message sent word for word loses all its cues. Improv flows don't run as chat simulations.
* **Emotion is audible only on ElevenLabs v3 and v4 voices.** On any other voice an emotion cue changes what the caller says, not how it sounds.
* **Up to eight languages per call**, counting the one the call starts in.
* **A noise cue whose environment was deleted is dropped** when the run starts.
* **One switch per step.** If a Scripted step holds two cues of the same kind, the last one wins.
* In [config as code](https://docs.roark.ai/documentation/config-as-code/flows.md), cues are plain text in `prompt` and step `content`, and a noise cue still takes the environment's id, not its name.

> [card] [Customer Flows](https://docs.roark.ai/documentation/simulation-testing/customer-flows.md)
>
> Briefs, scripted graphs, and how variants become calls

> [card] [Personas](https://docs.roark.ai/documentation/simulation-testing/personas.md)
>
> The caller's starting language, voice and base emotion

> [card] [Environments](https://docs.roark.ai/documentation/simulation-testing/environments.md)
>
> The background noise a noise cue moves the caller into

> [card] [Multiple callers](https://docs.roark.ai/documentation/simulation-testing/multiple-callers.md)
>
> Hand the phone to another persona mid-call


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.