Skip to main content
PATCH
Update persona

Authorizations

X-API-Key
string
header
required

API key for authentication

Headers

X-Coval-Workspace-Id
string

Workspace that scopes this operation. When omitted, the organization's active default workspace is used when one can be resolved.

Required string length: 1 - 26

Path Parameters

persona_id
string
required

Persona resource ID

Body

application/json

All fields are optional. Omitted fields are unchanged. Null behavior is documented per field.

silent_mode
boolean | null

Keep the persona silent for the whole simulation. Null clears the override.

multi_phone_config
object | null

Caller number selection from GET /v1/personas/phone-numbers. Omit to let the simulation select a random available number. Null clears it.

initialization_parameters
object | null

Persona-level initialization parameters. Null clears; an empty object replaces existing parameters. String values substitute into the initialization payload as JSON-escaped text (quote the "{{persona.key}}" placeholder); all other JSON values substitute as their JSON encoding.

custom_persona_data
string | null

Additional serialized JSON object sent as the chat request's customPersonaData, overriding the agent-level customPersonaData. Included only when the HTTP text agent does not configure input_template; a template-configured agent shapes its own request and does not receive it. Must parse as a JSON object and stay under 16 KiB. Null clears it.

Maximum string length: 16383
voice
enum<string> | null

Agent voice override for OpenAI Realtime endpoint simulations. Null clears it.

Available options:
alloy,
ash,
ballad,
coral,
echo,
marin,
sage,
shimmer,
verse
custom_voice_id
string | null

Server-issued custom voice reference belonging to this organization. Null selects the built-in voice again.

Minimum string length: 1
name
string | null

Human-readable persona name. Null is ignored; omit the field to leave it unchanged.

Required string length: 1 - 200
persona_prompt
string | null

Instructions describing persona behavior and personality. Send null to clear only when the persona's resulting silent_mode is true; otherwise the request is rejected.

voice_name
string | null

Coval voice name. Use GET /personas/voices to discover available voices and their supported language codes. Null is ignored; omit the field to leave it unchanged.

language_code
string | null

BCP-47 language code for voice synthesis. Must be supported by the selected voice. Use GET /personas/voices to discover valid voice and language combinations. Null is ignored; omit the field to leave it unchanged.

background_sound
string | null

Built-in background sound id, or custom:<background_sound_id> for an active custom sound returned by GET /personas/background-sounds. Send null to clear an existing background sound.

Maximum string length: 100
Pattern: ^(off|office|lounge|crowd|airport|bus|playground|doorbell|train-arrival|portable-air-conditioner|skatepark|small-dog-bark|cafe|ferry-and-announcement|heavy-rain|moderate-wind|newborn-baby-crying|office-with-alarm|street-with-sirens|construction-work|backchanneling|custom:[A-Za-z0-9_-]+)$
background_sound_volume
number<float> | null

Volume level for background sound (>= 0.0, no upper limit). Send null to clear an existing configured volume.

Required range: x >= 0
Example:

0.3

voice_volume
number<float> | null

Voice gain multiplier. Send null to clear an existing configured volume.

Required range: 0 <= x <= 2
Example:

1.25

voice_speed
number<float> | null

Voice speed multiplier accepted and stored from 0.25 to 2.0. Send null to clear an existing configured speed. The selected voice may enforce a narrower effective range or ignore speed changes.

Required range: 0.25 <= x <= 2
Example:

0.85

wait_seconds
number<float> | null

Response delay in seconds. Send null to clear an existing configured delay.

Required range: 0.1 <= x <= 2
conversation_initiation
enum<string> | null

Who initiates the conversation. Send null to clear an existing selection.

Available options:
speak_first,
wait_for_user
interruption_rate
enum<string> | null

How often the persona interrupts the agent. While the agent is speaking, the persona forces a new turn once about 90 seconds (LOW), 45 seconds (MEDIUM), or 30 seconds (HIGH) have passed since the call started or since its last interruption. NONE never interrupts. This is a timer, not a semantic barge-in. null is ignored; send NONE to disable.

Available options:
NONE,
LOW,
MEDIUM,
HIGH
multi_language_stt
boolean | null

Enable multilingual speech-to-text so callers speaking languages other than the primary language_code are still transcribed accurately. Send null to clear an existing override.

Example:

true

hold_music_timeout_seconds
number<float> | null

Disconnect after this many seconds of no speech (5-300). Send null to clear an existing timeout.

Required range: 5 <= x <= 300
situate_speaker
enum<string> | null

Persona placement preset. Send null to clear an existing preset.

  • speakerphone-easy: User speaking from a distance from the microphone
  • speakerphone-hard: User speaking from a distance from the microphone in an acoustically challenging environment.
Available options:
speakerphone-easy,
speakerphone-hard
audio_degradation
object | null

Channel degradation preset. Send null to clear an existing audio_degradation preset.

tags
string[] | null

Tags to associate with this persona. Null or omitted leaves tags unchanged. Pass [] to clear all tags.

Maximum array length: 20
Maximum string length: 200
Pattern: \S
Example:

Response

Persona updated successfully

persona
object
required

Persona resource representation returned by API responses.