ANanam
Personas

update persona

Changed on

Update a persona by id

put/v1/personas/{id}

Request

  • Base URL
    https://api.anam.ai
  • URL
    https://api.anam.ai/v1/personas/{id}
  • Auth
    HTTP bearer

Path parameters

idstring required

Persona id

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.1-express' | 'cara-4-latest'

Avatar model version. cara-4 is pinned to a stable checkpoint; cara-4.1-express is the Cara-4.1 Express model; cara-4-latest tracks the newest Cara 4 checkpoint and may change between sessions.

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

maxSessionLengthSecondsinteger nullable

Maximum length in seconds of every session with this persona. It can only shorten the plan's session limit, never extend it. Send null to remove it.

languageCodestring

Supported ISO 639 language code override (including "yue" for Cantonese) for transcription, replaces organisation level settings and multilingual (default) mode.

toolIdsstring[]

Array of tool IDs to attach to the persona. Replaces any existing tool associations.

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.",
  "maxSessionLengthSeconds": 600,
  "voiceDetectionOptions": {
    "endOfSpeechSensitivity": 0.5,
    "silenceBeforeSkipTurnSeconds": 5,
    "silenceBeforeSessionEndSeconds": 60,
    "silenceBeforeAutoEndTurnSeconds": 5,
    "speechEnhancementLevel": 0.8,
    "sttProvider": "anam"
  },
  "languageCode": "en",
  "voiceGenerationOptions": {
    "stability": 0.5,
    "speed": 1
  },
  "toolIds": [
    "tool-id-1",
    "tool-id-2"
  ],
  "widgetConfig": {
    "callToAction": "Chat with our assistant",
    "allowedOrigins": [
      "https://example.com",
      "https://app.example.com"
    ]
  }
}

Response

Successfully updated persona

idstring uuid

Unique identifier for the persona.

namestring

Human-readable name of the persona.

descriptionstring nullable

Free-form description of the persona.

personaPresetstring

Deprecated. Name of the legacy preset an older persona was created from, if any. Presets can no longer be set; use avatarId and voiceId.

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.

maxSessionLengthSecondsinteger nullable

Maximum length in seconds of every session with this persona, or null when only the plan's session limit applies.

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,
    "sttProvider": "anam"
  },
  "voiceGenerationOptions": {
    "stability": 0.5,
    "speed": 1
  }
}

Changes