Sign in

v4

latestOpenAPI 3.1.02026-08-086635375.7 KB
Personas

create persona

Create a new persona

post/v1/personas

Request body

namestring

Name of the persona

descriptionstring

Description of the persona, for example "A helpful assistant". Does not affect the persona's behavior.

avatarIdstring

The avatar to use.

avatarModel'cara-3' | 'cara-4' | 'cara-4-latest'

Avatar model version. cara-3 and cara-4 are generally available; models with the '-latest' suffix are invite only and require organization-level access.

voiceIdstring

The voice to use.

llmIdstring

The LLM to use. To disable the LLM, use 'CUSTOMER_CLIENT_V1'.

systemPromptstring

System prompt for the LLM

skipGreetingboolean

Whether to skip the greeting message when starting a session with this persona.

uninterruptibleGreetingboolean

When true, the greeting message cannot be interrupted by the user.

initialMessagestring nullable

Custom first message the persona speaks to open the conversation. If empty or not provided, the persona generates its own greeting.

zeroDataRetentionboolean

When true, session data is not stored after the conversation ends

languageCodestring

ISO 639-1 formatted language code override for transcription, replaces organisation level settings and multilingual (default) mode.

toolIdsstring[]

Array of tool IDs to attach to the persona.

Example request

{
  "name": "Cara",
  "avatarId": "071b0286-4cce-4808-bee2-e642f1062de3",
  "avatarModel": "cara-4",
  "voiceId": "de23e340-1416-4dd8-977d-065a7ca11697",
  "llmId": "a7cf662c-2ace-4de1-a21e-ef0fbf144bb7",
  "systemPrompt": "You are a helpful assistant",
  "initialMessage": "Hi there! I'm excited to chat with you today.",
  "voiceDetectionOptions": {
    "endOfSpeechSensitivity": 0.5,
    "silenceBeforeSkipTurnSeconds": 5,
    "silenceBeforeSessionEndSeconds": 60,
    "silenceBeforeAutoEndTurnSeconds": 5,
    "speechEnhancementLevel": 0.8
  },
  "languageCode": "en",
  "voiceGenerationOptions": {
    "stability": 0.5,
    "speed": 1
  },
  "toolIds": [
    "tool-id-1",
    "tool-id-2"
  ]
}

Response

Successfully created persona

idstring uuid

Unique identifier for the persona.

namestring

Human-readable name of the persona.

descriptionstring nullable

Free-form description of the persona.

personaPresetstring

Name of the preset the persona was cloned from, if any.

avatarModelstring nullable

Public model version (e.g. cara-3, cara-4) used when rendering the avatar.

voiceSpeednumber nullable

Speech rate multiplier applied to the voice.

llmIdstring uuid nullable

ID of the LLM the persona uses, or null for presets that don't run an LLM.

toolsobject[]

Tool configurations currently attached to the persona.

knowledgeobject[]

Knowledge group attachments currently active on the persona.

enableAudioPassthroughboolean

Whether audio is passed through from the client instead of being generated server-side.

skipGreetingboolean

Whether the persona skips the greeting message at the start of a session.

zeroDataRetentionboolean

Whether session data is discarded instead of stored after the conversation ends.

widgetConfigobject

Widget rendering overrides (e.g. removing the watermark).

createdAtstring date-time

Timestamp when the persona was created.

updatedAtstring date-time

Timestamp when the persona was last updated.

Example response

{
  "voiceDetectionOptions": {
    "endOfSpeechSensitivity": 0.5,
    "silenceBeforeSkipTurnSeconds": 5,
    "silenceBeforeSessionEndSeconds": 60,
    "silenceBeforeAutoEndTurnSeconds": 5,
    "speechEnhancementLevel": 0.8
  },
  "voiceGenerationOptions": {
    "stability": 0.5,
    "speed": 1
  }
}