Sign in

v50

latestOpenAPI 3.1.0raw.githubusercontent.com2026-04-285553225.5 KB
Simulation Persona

Create a new persona

Creates a new persona for the authenticated project.

post/v1/persona

Request body

namestring required

The name the agent will identify as during conversations

descriptionstring nullable

Human-readable description of the persona

language'EN' | 'ES' | 'DE' | 'HI' | 'FR' | 'NL' | 'AR' | 'EL' | 'IT' | 'ID' | 'TH' | 'JA' | 'TL' | 'MS' | 'ZH' | 'TR' | 'PT' required

Primary language ISO 639-1 code for the persona

secondaryLanguage'EN' nullable

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

accent'US' | 'US_X_SOUTH' | 'GB' | 'ES' | 'DE' | 'IN' | 'FR' | 'NL' | 'SA' | 'GR' | 'AU' | 'IT' | 'ID' | 'TH' | 'JP' | 'NZ' | 'PH' | 'SG' | 'MY' | 'HK' | 'TR' | 'PT' required

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

gender'MALE' | 'FEMALE' required

Gender of the persona

backgroundNoise'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM'

Background noise setting

speechPace'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'

Speech pace of the persona

speechClarity'CLEAR' | 'VAGUE' | 'RAMBLING'

Speech clarity of the persona

hasDisfluenciesboolean

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

baseEmotion'NEUTRAL' | 'CHEERFUL' | 'CONFUSED' | 'FRUSTRATED' | 'SKEPTICAL' | 'RUSHED' | 'DISTRACTED'

Base emotional state of the persona

intentClarity'CLEAR' | 'INDIRECT' | 'VAGUE'

How clearly the persona expresses their intentions

confirmationStyle'EXPLICIT' | 'VAGUE'

How the persona confirms information

memoryReliability'HIGH' | 'LOW'

How reliable the persona's memory is

responseTiming'RELAXED' | 'NORMAL' | 'QUICK'

Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED)

backstoryPromptstring nullable

Background story and behavioral patterns for the persona

idleMessagesstring[]

Messages the persona will say when the agent goes silent during a call

idleTimeoutSecondsinteger

Seconds of silence before the persona sends an idle message

idleMessageMaxSpokenCountinteger

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

idleMessageResetCountOnUserSpeechEnabledboolean

Whether the idle message counter resets when the agent speaks

propertiesobject

Additional custom properties about the persona

Example request

{
  "backstoryPrompt": "A busy professional calling during lunch break",
  "properties": {
    "age": 35,
    "zipCode": "94105",
    "occupation": "Software Engineer"
  }
}

Response

The created persona

Example response

{
  "data": {
    "backstoryPrompt": "A busy professional calling during lunch break",
    "properties": {
      "age": 35,
      "zipCode": "94105",
      "occupation": "Software Engineer"
    }
  }
}