> ## 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.

# Personas

> The callers your simulations run as

## Overview

A persona is the caller a simulation runs as. It bundles who the customer is — language, accent, gender, base emotion, and how they speak — into a reusable caller that you pin to a [customer flow](/documentation/simulation-testing/customer-flows) variant. Roark ships a starter set of **Built-in** personas; add your own **Custom** personas for the callers you care about.

Open **Personas** in the sidebar to see every persona in your project. From the hub you can search, create new personas, and edit or delete the custom ones.

## Persona fields

Click **New persona** to open the persona dialog. Every field except Name is optional or has a sensible default.

| Field               | Options                                                                | Default  | Notes                                                                |
| :------------------ | :--------------------------------------------------------------------- | :------- | :------------------------------------------------------------------- |
| **Name**            | Free text                                                              | —        | Required. Use something descriptive, e.g. "Returning client — Sarah" |
| **Display name**    | Free text                                                              | Name     | Shown in pickers and variant chips. Defaults to the name             |
| **Description**     | Free text                                                              | —        | One or two sentences on who this caller is (hub dialog only)         |
| **Language**        | 18 languages                                                           | English  | See the full list below                                              |
| **Accent**          | 23 accents                                                             | American | Includes American (Southern) as a distinct option                    |
| **Gender**          | Female, Male, Neutral                                                  | Female   | Affects the synthesized voice                                        |
| **Base emotion**    | Neutral, Cheerful, Frustrated, Skeptical, Rushed, Distracted, Confused | Neutral  | The caller's underlying emotional tone                               |
| **Speech pace**     | Very slow, Slow, Normal, Fast, Very fast                               | Normal   | How quickly the persona speaks                                       |
| **Clarity**         | Clear, Vague, Rambling                                                 | Clear    | How directly they express themselves                                 |
| **Response timing** | Quick, Normal, Relaxed                                                 | Normal   | How quickly the persona responds to pauses in conversation           |
| **Disfluencies**    | On / Off                                                               | Off      | Natural ums, ahs, false starts. Off means the persona speaks cleanly |

<AccordionGroup>
  <Accordion title="Language options">
    English, Spanish, French, German, Italian, Portuguese, Dutch, Arabic, Greek,
    Hebrew, Hindi, Indonesian, Malay, Tagalog, Thai, Japanese, Chinese, Turkish
  </Accordion>

  <Accordion title="Accent options">
    American, American (Southern), British, Australian, New Zealand, Indian,
    Spanish, French, German, Italian, Portuguese, Dutch, Greek, Arabic, Hebrew,
    Indonesian, Malaysian, Filipino, Singaporean, Hong Kong, Thai, Japanese,
    Turkish
  </Accordion>
</AccordionGroup>

<Note>
  Background noise is not a persona setting. It's configured per flow variant
  via the **Environment** chip (Silent, Office, Coffee shop, City street,
  Driving, Airport, Children playing, Thunderstorm) — see [Customer
  flows](/documentation/simulation-testing/customer-flows).
</Note>

## Built-in vs Custom

Every persona has a source badge:

* **Built-in** — the starter set Roark ships with each project. Built-in personas are read-only in the hub: they have no edit or delete actions.
* **Custom** — personas you create. Fully editable and deletable.

You can still start from a Built-in persona: load it in the inline persona editor inside a flow, tweak it, and save. Roark shows the note "System persona — saving creates an editable copy." and creates a Custom copy with your changes, leaving the original intact.

<Warning>
  Deleting a persona doesn't break existing flows silently — but customer-flow
  variants pinned to it will need a new persona.
</Warning>

## Pinning personas to flow variants

Personas do their work inside customer flows. Each variant in a flow carries a chip strip — **Persona · Environment · Variables** — and the Persona chip shows which caller that variant runs as.

* The flow's **default variant** (the happy path) must always have a concrete persona. New flows are pre-seeded with the Built-in **Polite First-Time Caller** persona (or your project's first persona if that one isn't available).
* **Non-default variants inherit** the default variant's persona automatically — the chip shows the name in muted italics, e.g. "Sarah (inherited)". Pin a different persona on a variant to override the inheritance for that variant only.

### The inline persona editor

Clicking a variant's Persona chip opens an inline editor with two paths:

<Steps>
  <Step title="Pick an existing persona">
    Click **Pick from existing personas** to open the "Pick a persona" dialog.
    Search by name, language, or accent; each row shows the persona's name,
    Language · Accent, and its Built-in or Custom badge. Picking one pins it to
    the variant.
  </Step>

  <Step title="Or author a caller in place">
    Fill in the same fields as the hub dialog (minus Description) directly in
    the panel — including a color-coded Base emotion pill grid — and click
    **Create & use** to create the persona and pin it in one step.
  </Step>

  <Step title="Tweak a pinned persona">
    With a persona pinned, the editor shows "Pinned: \<name>". Editing a
    Custom persona and clicking **Save changes** updates it in place. Editing a
    Built-in persona creates an editable Custom copy instead.
  </Step>
</Steps>

<Tip>
  Because Custom personas are shared across flows, "Save changes" in the inline
  editor updates that persona everywhere it's pinned. If you want a variant-only
  tweak, create a new persona instead.
</Tip>

## Personas at run time

When a [run](/documentation/simulation-testing/running-simulations) executes, each simulated call is placed as the persona pinned to its flow variant. On the resulting call records, the persona appears as `simulationPersonaName` — the display name of the persona used in the simulation that created the call.

If a persona used by a run has properties without values, Roark prompts for them in the runtime-variables step before the run starts; the values you enter are saved onto the persona itself, so future runs reuse them. See [Variables](/documentation/simulation-testing/variables).

## API

Manage personas programmatically to build them from real customer data or wire persona management into CI:

* **Create Persona** — `POST /v1/persona`
* **Update Persona** — `PUT /v1/persona/{personaId}`
* **Get Persona** — `GET /v1/persona/{personaId}`
* **List Personas** — `GET /v1/persona`

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
curl -X POST https://api.roark.ai/v1/persona \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Emma Johnson",
    "language": "EN",
    "accent": "US",
    "gender": "FEMALE",
    "baseEmotion": "NEUTRAL",
    "speechPace": "NORMAL",
    "speechClarity": "CLEAR",
    "responseTiming": "NORMAL",
    "hasDisfluencies": false,
    "properties": {
      "accountNumber": "ACC-123456",
      "zipCode": "90210"
    }
  }'
```

<Note>
  The API exposes some capabilities the platform UI doesn't surface: a
  `backstoryPrompt`, key/value `properties`, `secondaryLanguage`, idle-message
  settings, and the behavioral fields `backgroundNoise`, `intentClarity`,
  `confirmationStyle`, and `memoryReliability`. Personas created in the UI use
  system defaults for these (`NONE`, `CLEAR`, `EXPLICIT`, `HIGH`); set them via
  the API if you need finer control.
</Note>

For all parameters and response formats, see the [Persona API Reference](/api-reference/simulation-persona/create-a-new-persona).

## Best practices

* **Start with 3–5 core personas** representing your most common caller types, then add edge cases as you discover them.
* **Mirror reality** — base personas on real customer data and call recordings.
* **Test extremes** — a Frustrated, Fast, Rambling caller stresses your agent in ways a Neutral one won't.
* **Name for the test** — "Confused elder — password reset" tells your team more than "Robert".

## Next steps

<CardGroup cols={2}>
  <Card title="Customer flows" icon="git-branch" href="/documentation/simulation-testing/customer-flows">
    Pin personas to flow variants and define what should happen on the call
  </Card>

  <Card title="Running simulations" icon="play" href="/documentation/simulation-testing/running-simulations">
    Plan and launch runs that execute your flows as these callers
  </Card>
</CardGroup>