Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Input for creating a new persona

name
string
required

The name the agent will identify as during conversations

language
enum<string>
required

Primary language ISO 639-1 code for the persona

Available options:
EN,
ES,
DE,
HI,
FR,
NL,
AR,
EL,
IT,
ID,
TH,
JA,
TL,
MS,
ZH,
TR,
PT,
HE
accent
enum<string>
required

Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants

Available options:
US,
US_X_SOUTH,
GB,
ES,
DE,
IN,
FR,
NL,
SA,
GR,
AU,
IT,
ID,
TH,
JP,
NZ,
PH,
SG,
MY,
HK,
TR,
PT,
IL
gender
enum<string>
required

Gender of the persona

Available options:
MALE,
FEMALE
displayName
string | null

Label shown in place of the name across the dashboard (e.g. a short descriptor like "Irate Escalator"). The persona still identifies as name on calls. Omit or set null to display the name itself.

description
string | null

Human-readable description of the persona

secondaryLanguage
enum<string> | null

Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)

Available options:
EN
understoodLanguages
enum<string>[]

Languages the persona can understand. Defaults to the languages the persona speaks.

Minimum array length: 1
Available options:
EN,
ES,
DE,
HI,
FR,
NL,
AR,
EL,
IT,
ID,
TH,
JA,
TL,
MS,
ZH,
TR,
PT,
HE
age
enum<string>
default:ADULT

How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports.

Available options:
CHILD,
TEENAGER,
ADULT,
ELDERLY
backgroundNoise
enum<string>
default:NONE

Background noise setting

Available options:
NONE,
AIRPORT,
CHILDREN_PLAYING,
CITY,
COFFEE_SHOP,
CONSTRUCTION,
CRYING_BABY,
DRIVING,
LIBRARY,
OFFICE,
THUNDERSTORM,
TRAIN
speechPace
enum<string>
default:NORMAL

Speech pace of the persona

Available options:
SUPER_SLOW,
SLOW,
NORMAL,
FAST,
SUPER_FAST
speechClarity
enum<string>
default:CLEAR

Speech clarity of the persona

Available options:
CLEAR,
VAGUE,
RAMBLING
hasDisfluencies
boolean
default:false

Whether the persona uses filler words like "um" and "uh"

baseEmotion
enum<string>
default:NEUTRAL

Base emotional state of the persona

Available options:
NEUTRAL,
CHEERFUL,
CONFUSED,
FRUSTRATED,
SKEPTICAL,
RUSHED,
DISTRACTED,
ANGRY,
ANXIOUS,
SAD
intentClarity
enum<string>
default:CLEAR

How clearly the persona expresses their intentions

Available options:
CLEAR,
INDIRECT,
VAGUE
confirmationStyle
enum<string>
default:EXPLICIT

How the persona confirms information

Available options:
EXPLICIT,
VAGUE
memoryReliability
enum<string>
default:HIGH

How reliable the persona's memory is

Available options:
HIGH,
LOW
responseTiming
enum<string>
default:NORMAL

Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use interruption for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as responseTiming: QUICK with interruption: OCCASIONAL.

Available options:
RELAXED,
NORMAL,
QUICK,
BARGE_IN
interruption
enum<string>

How much the persona talks over the agent. Defaults to OFF, a caller that waits its turn.

Available options:
OFF,
BACKCHANNEL,
OCCASIONAL,
HEAVY
backstoryPrompt
string | null

Background story and behavioral patterns for the persona

Example:

"A busy professional calling during lunch break"

idleMessages
string[] | null

Messages the persona will say when the agent goes silent during a call. Defaults to language-appropriate phrases when omitted or sent as null.

idleTimeoutSeconds
integer
default:10

Seconds of silence before the persona sends an idle message

Required range: 5 <= x <= 60
idleMessageMaxSpokenCount
integer
default:3

Maximum number of idle messages the persona will send before giving up

Required range: 1 <= x <= 10
idleMessageResetCountOnUserSpeechEnabled
boolean
default:true

Whether the idle message counter resets when the agent speaks

properties
object

Additional custom properties about the persona

Example:

Response

The created persona

data
object
required