---
title: "Update Digital Human"
method: PUT
path: "/v1/update-digital-human/{digital_human_id}"
tags: ["Digital Humans"]
---

# Update Digital Human

`PUT /v1/update-digital-human/{digital_human_id}`

Update a digital human by ID.

## Path parameters

- `digital_human_id` integer, required

## Headers

- `X-API-Key` string, required

## Request body

- UpdateDigitalHumanRequest — Request model for updating a digital human — only provided fields are changed. Every field must default to None: a non-None default gets filled in by Pydantic on partial payloads and silently overwrites the stored value on every update (MCP, bluejay-as-code, and FE bulk edits all send partial payloads).
  - `intent` string, nullable — Description of the digital human
  - `success_criteria` string, nullable — Success criteria for the digital human
  - `name` string, nullable — Name of the digital human
  - `tag` string, nullable — Tag for categorizing the digital human
  - `language` 'en' | 'es' | 'pt' | 'ja' | 'tr' | 'hi' | 'ar' | 'he' | 'ru' | 'zh' | 'ml' | 'fr' | 'yue' | 'vi' | 'de' | 'ko' | 'ur' | 'te' | 'ta' | 'mal' | 'kn' | 'mr' | 'gu' | 'ad' — Enum for supported language types.
  - `accent` 'multilingual' | 'american' | 'american2' | 'mature' | 'southern' | 'italian' | 'indian' | 'british' | 'australian' | 'scottish' | 'irish' | 'welsh' | 'mexican' | 'spanish' | 'portuguese' | 'french' | 'turkish' | 'japanese' | 'hindi' | 'arabic' | 'egyptian' | 'levantine' | 'hebrew' | 'russian' | 'chinese' | 'german' | 'korean' | 'urdu' | 'telugu' | 'tamil' | 'malayalam' | 'kannada' | 'marathi' | 'gujarati' | 'autodetect' — Enum for accent options.
  - `gender` 'male' | 'female' — Enum for gender options.
  - `custom_voice_id` string, nullable — ElevenLabs voice_id of a cloned voice. Send empty string or null to clear and revert to the stock accent voice.
  - `background_noise` 'none' | 'office' | 'talking' | 'traffic' | 'cafe' | 'park' | 'tv' | 'noisy_restaurant' | 'hospital' | 'custom' — Enum for background noise options.
  - `custom_background_noise_url` string, nullable — Bucket-relative path of the uploaded custom background noise audio; required when background_noise is 'custom'
  - `voice_speed` 'slowest' | 'slow' | 'normal' | 'fast' | 'fastest' — Enum for voice speed options.
  - `audio_quality` 'high' | 'medium' | 'low' | 'horrible' — Enum for audio quality options.
  - `fluency` 'beginner' | 'intermediate' | 'native' — Enum for fluency level options.
  - `verbosity` 'low' | 'medium' | 'high' — Enum for verbosity level options.
  - `phone_number` string, nullable — Phone number for the digital human
  - `extension` string, nullable — Extension dialed as DTMF after connecting when this DH calls an inbound agent
  - `outbound_text_number` string, nullable — Outbound text number
  - `follow_up_sms_success_criteria` string, nullable — Criteria the captured follow-up SMS is graded against
  - `background_noise_volume` number, nullable — Volume of background noise
  - `expected_tool_calls` ExpectedToolCall[], nullable — Expected tool call outputs
    - `name` string, required — Name of the expected tool call
    - `parameters` object, nullable — Expected parameters passed to the tool call
    - `output` unknown
  - `allow_end_call_tool` boolean, nullable — Allow the digital human to end the tool call
  - `allow_silence_tool` boolean, nullable — Allow the digital human to use the silence tool
  - `allow_dtmf_tool` boolean, nullable — Allow the digital human to use the DTMF tool
  - `default_dtmf_or_voiced` 'voiced' | 'dtmf' — Enum for DTMF vs voiced input mode.
  - `silence_tool_instructions` string, nullable — Tool instructions; set to "default" for built-in behavior or custom text
  - `endpointing_delay` number, nullable — Delay for endpointing
  - `creativity` number, nullable — How creative the digital human is (Model temperature)
  - `hangup_phrases` string[], nullable — Phrases that trigger hangup
  - `hangup_instructions` string, nullable — Freeform instructions for how/when to hang up
  - `silence_timeout` integer, nullable — Silence timeout in seconds
  - `simulation_ids` integer[], nullable — Array of simulation IDs to associate with this digital human. If provided, completely replaces existing associations.
  - `traits` SrcModelsTraitsTraitTrait[], nullable — List of traits associated with this digital human. If provided, completely replaces existing traits.
    - `trait_name` string, required — Name of the trait
    - `trait_data_type` 'BOOLEAN' | 'STRING' | 'DATE' | 'NUMBER', required — Enum for trait data types.
    - `value` unknown, required
    - `is_sip_header` boolean — Whether this trait is a SIP header
  - `interruptions` union — Interruption configuration for the digital human. If provided, completely replaces existing interruption config.
    - SimpleInterruptionConfig — Simple interruption configuration with predefined levels.
      - `type` 'none' | 'low' | 'medium' | 'high', required — Interruption level: none, low, medium, or high
    - KeywordsInterruptionConfig — Keywords-based interruption configuration.
      - `type` 'keywords', required — Type discriminator for keywords interruption (required)
      - `keyword_responses` KeywordResponse[], required — Array of keyword response objects, each with keyword, response, and optional probability
        - `keyword` string, required — The keyword to listen for and interrupt on
        - `response` string, required — Response to say when keyword is detected
        - `probability` number — Probability of responding (0.0-1.0) - defaults to 1.0
    - ContextualInterruptionConfig — Contextual/LLM-based interruption configuration.
      - `type` 'contextual', required — Type discriminator for contextual interruption
      - `contextual_prompt` string, required — Contextual prompt for LLM-based interruptions
  - `scripted_responses` ScriptedResponse[], nullable — List of scripted responses for the digital human. If provided, completely replaces existing scripted responses.
    - `match_type` 'exact' | 'context', required — Enum for scripted response match types.
    - `match_phrase` string, required — The phrase to match against
    - `response_type` 'phrase' | 'silence' | 'dtmf' | 'audio', required — Enum for scripted response types.
    - `response_value` string, nullable — The response text (required for 'phrase' and 'dtmf', optional for 'silence', unused for 'audio')
    - `scripted_response_audio_snippet_url` string, nullable — Skywatch bucket path of an uploaded audio file. AUDIO rows only — the agent downloads and plays this verbatim.
    - `occurrence_mode` 'always' | 'first_n', required — Enum for scripted response occurrence modes.
    - `occurrence_n` integer, nullable — Number of times to apply (required if occurrence_mode is 'first_n', must be > 0)
    - `silence_duration` integer, nullable — Duration in seconds for silence period (only used when response_type is 'silence', must be > 0 if provided)
  - `role_description` string, nullable — Description of the role for the digital human
  - `speaks_first_config` SpeaksFirstConfig — Configuration for whether the digital human speaks first and how. Stored as JSONB in Supabase (speaks_first_config).
    - `speaks_first` boolean, required — Whether the digital human speaks first in the call
    - `mode` 'custom' | 'ai_generated', nullable — When speaks_first is true: 'custom' (user-provided message) or 'ai_generated' (no message)
    - `message` string, nullable — When mode is 'custom', the message the digital human says first
  - `original_transcript` string, nullable — Original transcript text. If changed from the current value, utterances are re-extracted and the intent is regenerated.
  - `formatted_transcript` object[], nullable — Pre-computed structured transcript as [{role, utterance}]. When provided alongside original_transcript, skips the LLM formatting call.
  - `enriched_playback` object[], nullable — Optional enriched playback stored as JSONB: a list of turn objects
  - `num_runs` integer, nullable — Number of times this digital human is run per simulation run (run count).
  - `livekit_metadata` object, nullable — LiveKit-specific configuration and metadata for this digital human. If provided, completely replaces existing metadata.
  - `always_on_mode` boolean, nullable — Whether always-on mode is enabled for this digital human
  - `always_on_active` boolean, nullable — When true, this DH actively receives calls on phone_number; when false, number is assigned but inactive
  - `test_name` string, nullable — User-facing label for this digital human
  - `journey_steps` JourneyStep[], nullable — Ordered journey steps. If provided, completely replaces existing journey steps.
    - `step` integer, required
    - `intent` string
    - `success_criteria` string
    - `modality` 'voice' | 'sms'
    - `direction` 'inbound' | 'outbound', nullable
    - `wait_seconds` integer, nullable
    - `response_window_seconds` integer, nullable
    - `unresponsive` boolean
  - `override_conflict` boolean, nullable — When true, allows activation to replace an existing always-on active DH using the same phone number.

## Response `200`

Successful Response

- SrcModelsDigitalHumansDigitalHumanResponseDigitalHumanResponse — Response model for digital human operations with clear separation of digital human data and simulation context.
  - `digital_human` DigitalHumanResponseData, required — Response model for digital human data.
    - `id` integer, nullable — Unique identifier for the digital human
    - `bluejay_as_code_id` string, uuid, nullable — Stable code-addressable identifier
    - `intent` string, required — Description of the digital human
    - `success_criteria` string, required — Success criteria for the digital human
    - `tag` string, nullable — Tag for categorizing the digital human
    - `tags` string[], nullable — All tags associated with the digital human
    - `name` string, nullable — Name of the digital human
    - `language` 'en' | 'es' | 'pt' | 'ja' | 'tr' | 'hi' | 'ar' | 'he' | 'ru' | 'zh' | 'ml' | 'fr' | 'yue' | 'vi' | 'de' | 'ko' | 'ur' | 'te' | 'ta' | 'mal' | 'kn' | 'mr' | 'gu' | 'ad' — Enum for supported language types.
    - `accent` 'multilingual' | 'american' | 'american2' | 'mature' | 'southern' | 'italian' | 'indian' | 'british' | 'australian' | 'scottish' | 'irish' | 'welsh' | 'mexican' | 'spanish' | 'portuguese' | 'french' | 'turkish' | 'japanese' | 'hindi' | 'arabic' | 'egyptian' | 'levantine' | 'hebrew' | 'russian' | 'chinese' | 'german' | 'korean' | 'urdu' | 'telugu' | 'tamil' | 'malayalam' | 'kannada' | 'marathi' | 'gujarati' | 'autodetect' — Enum for accent options.
    - `gender` 'male' | 'female' — Enum for gender options.
    - `custom_voice_id` string, nullable — ElevenLabs voice_id of a cloned voice used for TTS, if assigned
    - `background_noise` string, nullable — Type of background noise
    - `custom_background_noise_url` string, nullable — Bucket-relative path of the uploaded custom background noise audio when background_noise is 'custom'
    - `voice_speed` string, nullable — Speed of the digital human's voice
    - `audio_quality` string, nullable — Audio quality of the digital human's voice
    - `fluency` string, nullable — Fluency level of the digital human's speech
    - `verbosity` string, nullable — Verbosity level of the digital human's responses
    - `phone_number` string, nullable — Phone number for the digital human
    - `extension` string, nullable — Extension dialed as DTMF after connecting when this DH calls an inbound agent
    - `outbound_text_number` string, nullable — Outbound text number
    - `follow_up_sms_success_criteria` string, nullable — Criteria the captured follow-up SMS is graded against
    - `websocket_url` string, nullable — WebSocket URL for real-time communication
    - `background_noise_volume` number, nullable — Volume of background noise
    - `expected_tool_calls` ExpectedToolCall[], nullable — Expected tool calls
      - `name` string, required — Name of the expected tool call
      - `parameters` object, nullable — Expected parameters passed to the tool call
      - `output` unknown
    - `allow_end_call_tool` boolean, nullable — Allow the digital human to end the tool call
    - `allow_silence_tool` boolean, nullable — Allow the digital human to use the silence tool
    - `allow_dtmf_tool` boolean, nullable — Allow the digital human to use the DTMF tool
    - `default_dtmf_or_voiced` string, nullable
    - `silence_tool_instructions` string, nullable — Tool instructions; "default" or custom text
    - `endpointing_delay` number, nullable — Delay for endpointing
    - `creativity` number, nullable — Temperature setting
    - `hangup_phrases` string[], nullable — Phrases that trigger hangup
    - `hangup_instructions` string, nullable — Freeform instructions for how/when to hang up
    - `silence_timeout` integer, nullable — Silence timeout in seconds
    - `role_description` string, nullable — Description of the role for the digital human
    - `created_at` string, date-time, nullable — When this digital human was created
    - `traits` TraitOutput[], nullable — List of traits associated with this digital human
      - `trait_name` string, required — Name of the trait
      - `trait_data_type` 'BOOLEAN' | 'STRING' | 'DATE' | 'NUMBER', required — Enum for trait data types.
      - `value` unknown, required
      - `is_sip_header` boolean — Whether this trait is a SIP header
    - `interruptions` object, nullable — Interruption configuration for the digital human
    - `scripted_responses` ScriptedResponse[], nullable — List of scripted responses for the digital human
      - `match_type` 'exact' | 'context', required — Enum for scripted response match types.
      - `match_phrase` string, required — The phrase to match against
      - `response_type` 'phrase' | 'silence' | 'dtmf' | 'audio', required — Enum for scripted response types.
      - `response_value` string, nullable — The response text (required for 'phrase' and 'dtmf', optional for 'silence', unused for 'audio')
      - `scripted_response_audio_snippet_url` string, nullable — Skywatch bucket path of an uploaded audio file. AUDIO rows only — the agent downloads and plays this verbatim.
      - `occurrence_mode` 'always' | 'first_n', required — Enum for scripted response occurrence modes.
      - `occurrence_n` integer, nullable — Number of times to apply (required if occurrence_mode is 'first_n', must be > 0)
      - `silence_duration` integer, nullable — Duration in seconds for silence period (only used when response_type is 'silence', must be > 0 if provided)
    - `speaks_first_config` SpeaksFirstConfig — Configuration for whether the digital human speaks first and how. Stored as JSONB in Supabase (speaks_first_config).
      - `speaks_first` boolean, required — Whether the digital human speaks first in the call
      - `mode` 'custom' | 'ai_generated', nullable — When speaks_first is true: 'custom' (user-provided message) or 'ai_generated' (no message)
      - `message` string, nullable — When mode is 'custom', the message the digital human says first
    - `original_transcript` string, nullable — The original transcript text attached to this digital human
    - `formatted_transcript` object[], nullable — Structured transcript as [{"role": "USER"|"AGENT", "utterance": "..."}]
    - `enriched_playback` object[], nullable — Optional enriched playback stored as JSONB: a list of turn objects
    - `workflow_v2_id` string, uuid, nullable — Source workflow_v2 UUID — set when this DH is generated from a workflow
    - `workflow_path_index` integer, nullable — 0-based path index within enumerate_workflow_v2_paths output
    - `tested_path` string[], nullable — Ordered names of the workflow path steps this DH was generated from (Generate-From-Workflow only).
    - `livekit_metadata` object, nullable — LiveKit-specific configuration and metadata for this digital human
    - `test_name` string, nullable — User-facing label for this digital human
    - `journey_steps` JourneyStep[], nullable — Ordered journey steps for a multi-step (Customer Journey) digital human
      - `step` integer, required
      - `intent` string
      - `success_criteria` string
      - `modality` 'voice' | 'sms'
      - `direction` 'inbound' | 'outbound', nullable
      - `wait_seconds` integer, nullable
      - `response_window_seconds` integer, nullable
      - `unresponsive` boolean
  - `simulation_ids` integer[], nullable — List of simulation IDs associated with this digital human
  - `simulation_id` integer, nullable — ID of the associated simulation. Use simulation_ids instead.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/getbluejay/apis/bluejay-api.md) · [All operations](https://skmtc.net/getbluejay/apis/bluejay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getbluejay/bluejay-api/versions/f48cef80963f/schema)