Skip to main content
POST
Create persona
A persona is a reusable caller archetype. The same persona can sit behind dozens of cases, each one pairing the persona with a different agent or scenario.

Designing the prompt

Lead with the persona’s role and what brought them to the call:
Keep the prompt under ~120 words. Long prompts make the persona LLM rigid and the conversation less natural. Put adjustable axes (patience, verbosity, cooperation) in behavior_traits, not the prompt — that way one identity becomes many variants.

Common behavior_traits keys

The persona LLM reads whatever keys you pass — you can invent new ones.

Authorizations

Authorization
string
header
required

Your Yappr API key (e.g. ypr_live_...). Generate one in the dashboard under Settings → API Keys.

Body

application/json
name
string
required
Example:

"Frustrated tenant"

identity_prompt
string
required
description
string
behavior_traits
object
language
enum<string>
default:en
Available options:
he,
en
voice_config
object

Response

Persona created

Reusable caller archetype consumed by eval cases. The identity_prompt plus behavior_traits shape how the persona LLM responds; the same persona can be reused across many cases.

id
string<uuid>
required
company_id
string<uuid>
required
name
string
required
Example:

"Frustrated tenant"

identity_prompt
string
required

System prompt fragment defining who the persona is. Written second-person ("You are…").

Example:

"You are a 38-year-old tenant calling about a leaking pipe in your kitchen. You're frustrated because this is the third time you've reported it."

language
enum<string>
default:en
required
Available options:
he,
en
created_at
string<date-time>
required
description
string | null
behavior_traits
object

Free-form JSON. Common keys: patience (low|medium|high), verbosity (terse|chatty), cooperation (cooperative|adversarial), interruption_tendency (none|occasional|frequent), accent / dialect hints, goal (what the persona is trying to achieve in the call).

Example:
voice_config
object

Forward-compat for v2 voice-mode (TTS/STT loopback). Ignored in text mode.

updated_at
string<date-time>
deleted_at
string<date-time> | null