Personas

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

Language options

English, Spanish, French, German, Italian, Portuguese, Dutch, Arabic, Greek, Hebrew, Hindi, Indonesian, Malay, Tagalog, Thai, Japanese, Chinese, Turkish

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

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.

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.

Deleting a persona doesn’t break existing flows silently — but customer-flow variants pinned to it will need a new persona.

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:

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.

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.

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.

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.

Personas at run time

When a run 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.

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

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"
    }
  }'

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.

For all parameters and response formats, see the Persona API Reference.

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

Getting Started

Observability

Metrics

Simulations

Recipes

Integrations

SDKs & Libraries

Resources

Overview

Persona fields

Built-in vs Custom

Pinning personas to flow variants

The inline persona editor

Personas at run time

API

Best practices

Next steps

Customer flows

Running simulations

​Overview

​Persona fields

​Built-in vs Custom

​Pinning personas to flow variants

​The inline persona editor

​Personas at run time

​API

​Best practices

​Next steps

Customer flows

Running simulations

Overview

Persona fields

Built-in vs Custom

Pinning personas to flow variants

The inline persona editor

Personas at run time

API

Best practices

Next steps