---
title: "Update an agent - changes go live immediately"
method: PATCH
path: "/v1/agents/{id}"
---

# Update an agent - changes go live immediately

`PATCH /v1/agents/{id}`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/agents/{id}`
- Auth: HTTP bearer

Updates an existing agent - the same fields as on creation, all of them optional. Send only what needs to change. Two of them, though, are always sent IN FULL, because they replace the existing list: toolIdsanddataFields. An empty array therefore turns the feature off (`"toolIds": []` removes all of the agent's tools), whereas a missing key means "leave it as is". Handoff is turned off with an empty string: `"transferTo": ""`.

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string: Display name of the agent. Leading and trailing whitespace is trimmed.
  - `systemPrompt` string: Instructions governing every call. Describe the role, facts the agent may use and when to hand off; do not include secrets. Whitespace is trimmed.
  - `firstMessage` string: Opening line spoken to the caller. Omit at creation to use the default greeting. Include a short AI disclosure; recording adds a notice automatically. A long greeting saves with a warning.
  - `language` 'cs' | 'sk' | 'en' | 'de' | 'pl': Language spoken by the agent: Czech, Slovak, English, German or Polish. Defaults to cs at creation, where it does not by itself select a voice provider. On PATCH, a change from en, de or pl to cs or sk moves an ElevenLabs agent to the volai engine with that language's default voice; read provider in the response.
  - `voiceId` string: Voice id from GET /v1/voices, compatible with the agent's provider. Omit when the provider is uncertain, read back the agent, then choose its voice. An empty string restores the provider's default voice.
  - `numberE164` string, nullable: Owned phone number to attach, in E.164 format. Omit at creation for an agent without a number. On PATCH, null detaches the number; omission leaves it unchanged.
  - `toolIds` string[]: Complete list of owned webhook tool ids from GET /v1/tools. Replaces the previous list on PATCH; [] removes all tools.
  - `transferTo` string: Human handoff destination in E.164 format. Must not point back to your own volai number. An empty string disables handoff. Setting a destination attempts an engine switch; read back provider to verify it succeeded.
  - `transferCondition` string: When the agent should transfer to the human destination. An empty string restores the default condition.
  - `dataFields` object[]: Complete list of structured facts to extract from a call. Replaces the previous list on PATCH; [] disables extraction.
    - `key` string, required: Unique key in the call's data object: lowercase letter first, then lowercase letters, digits or underscores.
    - `type` 'string' | 'number' | 'boolean', required: JSON value type to extract. enumValues applies only to string fields.
    - `description` string, required: Explain what the agent should capture and how to recognize it in the caller's words.
    - `enumValues` string[]: Allowed values for a string field. Omit or send [] for unrestricted text.
  - `recordCalls` boolean: Whether to record calls. Defaults to true at creation and adds a short recording notice to the greeting. You remain responsible for appropriate disclosure.
  - `goal` string, nullable: One sentence defining a successful call for post-call evaluation on engine agents. An empty string clears it; PATCH also accepts null.
  - `knowledge` string, nullable: Additional reference text for the agent, separate from its instructions. An empty string clears it; PATCH also accepts null.
  - `notifyEmail` boolean: Whether to email the account owner a summary after each engine call. Defaults to true at creation.
  - `voicemail` object, nullable: Outbound voicemail detection for engine agents. Creation requires the initial provider selection to be engine, before any transfer-triggered switch. On PATCH, null clears this configuration.
    - `enabled` boolean, required: Enable detection of a voicemail greeting during outbound calls.
    - `action` 'mark' | 'hangup' | 'message', required: mark records the detection and continues, hangup ends the call, message speaks the configured message and ends the call. message requires a nonblank message even when enabled is false.
    - `message` string: Text spoken into voicemail when action is message. Required and nonblank for that action; any supplied message must fit the length limit.
  - `silencePromptSecs` union: Seconds of caller silence before the agent asks once whether the caller is still there, accepted for either provider though only heard once the agent runs on the volai engine. null turns it off; omission uses the default of 10 at creation, or leaves it unchanged on PATCH.
    - integer: Seconds of caller silence before the agent asks once whether the caller is still there, accepted for either provider though only heard once the agent runs on the volai engine. null turns it off; omission uses the default of 10 at creation, or leaves it unchanged on PATCH.
    - integer: Seconds of caller silence before the agent asks once whether the caller is still there, accepted for either provider though only heard once the agent runs on the volai engine. null turns it off; omission uses the default of 10 at creation, or leaves it unchanged on PATCH.
  - `firstMessageProtectSecs` number, nullable: Seconds of the first line protected from short reactions by the person who answered, outbound calls only, accepted for either provider though only heard once the agent runs on the volai engine. While the line plays, a reaction such as "Hello?" does not interrupt it. A reply without an interrupting word (for example stop, no, wait) is dropped in that window: it does not interrupt the line, is not in the transcript and the agent does not react to it; an interrupting word still interrupts it. The interrupting words follow the agent's language: an English agent is interrupted by stop, no, wait or hold. null or 0 turns it off. No default is applied: omission stores nothing at creation, or leaves the current setting unchanged on PATCH.
  - `silencePromptText` string, nullable: Your own sentence for the silence reminder, spoken word for word instead of the default reminder for the agent's language, accepted for either provider though only heard once the agent runs on the volai engine. Surrounding whitespace is trimmed; null or an empty string restores the default text. No default is applied: omission stores nothing at creation, or leaves the current text unchanged on PATCH.
  - `sttLanguageHintsStrict` boolean, nullable: Strict language lock for speech recognition on the volai engine (Soniox language_hints_strict): the transcript strongly prefers the agent's language, so a short reply such as "Ano" is not written as a foreign word or in another script. Best effort, not a guarantee. Meant only for agents on the engine with language cs and outbound calls; do not turn it on for sk (Czech callers would get Slovak spelling). Stored for either provider, read only by the engine; ElevenLabs ignores it. On PATCH, true turns it on, false or null turns it off and omission leaves it unchanged. At creation, omission stores nothing (off).
  - `turnDigitTailFloorMs` integer, nullable: Silence floor in milliseconds for a reply that ends with a group of 3 to 8 digits (a caller dictating a number group by group), on the volai engine: the engine waits at least this long after the caller stops before closing the reply, so the agent does not jump into the number. 0 turns it off; otherwise 400 to 2300 (1 to 399 is rejected). Recommended first step for Czech agents that take dictated numbers: 800. Dates, postcodes and years get the floor too. Stored for either provider, used only by the engine. On PATCH, null clears the stored value (the engine default 0 applies) and omission leaves it unchanged. At creation, omission stores nothing.
  - `turnLongSpeechFloorMs` integer, nullable: Silence floor in milliseconds after the caller spoke for longer than turnLongSpeechSecs, on the volai engine: after a long stretch of speech callers take a breath and continue. 0 turns it off; otherwise 400 to 2300 (1 to 399 is rejected), suggested 800. Stored for either provider, used only by the engine. On PATCH, null clears the stored value (the engine default 0 applies) and omission leaves it unchanged. At creation, omission stores nothing.
  - `turnLongSpeechSecs` number, nullable: Speech length in seconds above which turnLongSpeechFloorMs applies, 1 to 30, decimals allowed. Has no effect while turnLongSpeechFloorMs is 0. On PATCH, null clears the stored value (the engine default 5 applies) and omission leaves it unchanged. At creation, omission stores nothing.
  - `inboundVariables` object, nullable: Default values for {{variable}} placeholders on INBOUND calls, for example {"uvod": "How can I help you?"}. Merged into the call's dynamic variables only for names the inbound call does not supply itself; caller_number, called_number, attempt_id and the volai_, trial_ and system__ prefixes are reserved and rejected. Not used on outbound calls, where the variables of POST /v1/calls apply. Works for either provider. Keys are letters, digits or underscores (1 to 40 characters), values are trimmed and up to 200 characters, at most 10 keys. On PATCH the object replaces the stored values entirely; null or {} removes them all; omission leaves them unchanged. At creation, omission stores nothing.
  - `laughter` 'auto' | 'on' | 'off': Whether the agent may laugh during a call: auto follows sensitive-topic detection, on overrides that detection, off always suppresses it. on does not override everything else: the engine still needs a Cartesia voice in Czech and its own switch on. Has no effect on agents hosted on ElevenLabs. Omission stores auto explicitly at creation, or leaves the current setting unchanged on PATCH.
  - `workflow` object, nullable: Call phases that add local instructions, knowledge and tools. Omit at creation for one shared scope; PATCH null removes phases. Publish requires a reachable graph, at most 5 outgoing edges per node, and prompt plus knowledge at most 4000 characters per node.
    - `version` 1, required: Workflow format version, currently always 1.
    - `entry` string, required: Id of the node the call starts in. Must exist among nodes.
    - `nodes` object[], required: Call phases, 2 to 8 nodes.
      - `id` string, required: Machine id of this node: lowercase letters, digits and underscores, starting with a letter, up to 32 characters. Must be unique within the workflow. The words start, start_node, end and end_node are reserved.
      - `label` string, required: Human-readable phase name, 1 to 60 characters.
      - `prompt` string: Prompt addition that only applies while the call is in this node, up to 2000 characters. The agent's base systemPrompt should only hold what is true in every phase.
      - `knowledge` string: Extra knowledge that only applies in this node, up to 4000 characters. prompt and knowledge combined must not exceed 4000 characters for one node.
      - `toolIds` string[]: Ids of account tools (from list_tools) visible only while the call is in this node, at most 10. A tool not assigned to any node stays visible in every node.
      - `enterPhrase` string: Sentence spoken immediately on entering this node, at most once per call, up to 160 characters.
      - `enterBehavior` 'reply' | 'wait': Defaults to "reply". "wait" means the model does not answer in the same turn after speaking enterPhrase and waits for the caller instead; requires enterPhrase.
    - `edges` object[], required: Transitions between phases, 1 to 24 edges, at most 5 leaving any one node.
      - `id` string, required: Machine id of this edge: lowercase letters, digits and underscores, starting with a letter, up to 48 characters. Must be unique within the workflow.
      - `from` string, required: Id of the node this edge leaves.
      - `to` string, required: Id of the node this edge enters. Must differ from from.
      - `condition` string, required: When to take this edge, written about what the CALLER said (never about what the agent or a tool did), 5 to 200 characters. Goes verbatim into the description of the switch_to_{to} tool.
  - `calendar` object, nullable: Calendar availability rules so the agent can check availability and book appointments during a call, effective only once the agent's provider is engine - see calendar_pending_engine_switch in warnings otherwise. Creation only sets it. On PATCH, null clears it; omission leaves it unchanged.
    - `integrationId` string, required: Id of the connected calendar integration this agent books through, from list_integrations.
    - `calendarId` string, required: Id of the specific calendar within that connection, from list_calendars. The agent writes appointments into this calendar, so it must be writable (accessRole owner or writer); a read-only calendar is rejected with calendar_invalid_calendar.
    - `busyCalendarIds` string[]: Other calendars in the same connection whose events also block a slot; nothing is written into them, so read-only calendars are fine. At most 4, without duplicates and without calendarId.
    - `timezone` string, required: IANA timezone the windows and spoken times are interpreted in, for example Europe/Prague.
    - `slotMinutes` union, required: Length of each offered appointment slot in minutes.
      - 15
      - 30
      - 45
      - 60
      - 90
      - 120
    - `minNoticeMinutes` number, required: Minimum notice before the earliest offered slot, in minutes.
    - `horizonDays` number, required: How many days ahead the agent searches for a free slot.
    - `bufferMinutes` number, required: Buffer kept free immediately before and after every busy event, in minutes.
    - `windows` object, required: Availability windows for every weekday. At least one weekday needs a non-empty window.
      - `mon` object[], required: Availability windows on Monday. An empty array means no availability that day.
        - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
        - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
      - `tue` object[], required: Availability windows on Tuesday. An empty array means no availability that day.
        - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
        - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
      - `wed` object[], required: Availability windows on Wednesday. An empty array means no availability that day.
        - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
        - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
      - `thu` object[], required: Availability windows on Thursday. An empty array means no availability that day.
        - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
        - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
      - `fri` object[], required: Availability windows on Friday. An empty array means no availability that day.
        - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
        - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
      - `sat` object[], required: Availability windows on Saturday. An empty array means no availability that day.
        - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
        - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
      - `sun` object[], required: Availability windows on Sunday. An empty array means no availability that day.
        - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
        - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
  - `missedCallSms` object: Send an SMS to the caller when this agent misses the call (unanswered outbound, missed inbound). Omission leaves SMS off at creation, or unchanged on PATCH; send { enabled: false } to turn it off.
    - `enabled` boolean, required: Whether the missed-call SMS is on.
    - `text` string: Custom SMS template using {firma}/{cislo}/{agent}; any other {...} variable is rejected. Omit for the default text in the agent's language.

## Response `200`

Updated agent

- object
  - `agent` object, required
    - `id` string, required
    - `name` string, required
    - `language` string, required
    - `systemPrompt` string, required
    - `firstMessage` string
    - `voiceId` string
    - `provider` 'elevenlabs' | 'engine', required
    - `numberE164` string
    - `createdAt` number, required
    - `status` 'active' | 'deleted', required
    - `toolIds` string[]
    - `transferTo` string
    - `transferCondition` string
    - `dataFields` object[]
      - `key` string, required
      - `type` 'string' | 'number' | 'boolean', required
      - `description` string, required
      - `enumValues` string[]
    - `recordCalls` boolean
    - `goal` string, nullable, required
    - `knowledge` string, nullable, required
    - `notifyEmail` boolean, required
    - `voicemail` object
      - `enabled` boolean, required
      - `action` 'mark' | 'hangup' | 'message', required
      - `message` string
    - `silencePromptSecs` integer, nullable, required
    - `laughter` 'auto' | 'on' | 'off', required
    - `firstMessageProtectSecs` number, nullable, required: Seconds of the first line protected from short reactions by the person who answered (outbound calls on the volai engine), 0 to 20. A reply without an interrupting word (for example stop, no, wait) is dropped in that window: it does not interrupt the line, is not in the transcript and the agent does not react to it; an interrupting word still interrupts it. The interrupting words follow the agent's language: an English agent is interrupted by stop, no, wait or hold. null means not set, so the engine plays the first line as before.
    - `silencePromptText` string, nullable, required: Your own sentence for the silence reminder, spoken word for word instead of the default reminder for the agent's language. null means the default text is used. Heard only once the agent runs on the volai engine.
    - `sttLanguageHintsStrict` boolean, required: Strict language lock for speech recognition on the volai engine (Soniox language_hints_strict): the transcript strongly prefers the agent's language, so a short reply is not written as a foreign word or in another script. Best effort; meant for cs agents with outbound calls, never for sk. false when not set. Read only by the engine, ElevenLabs ignores it.
    - `turnDigitTailFloorMs` integer, nullable, required: Silence floor in milliseconds the volai engine keeps after a reply that ends with a group of 3 to 8 digits (a caller dictating a number), 0 (off) or 400 to 2300; the recommended first step for Czech agents that take dictated numbers is 800. null means not set, so the engine default (0, off) applies. Used only by the engine.
    - `turnLongSpeechFloorMs` integer, nullable, required: Silence floor in milliseconds the volai engine keeps after the caller spoke for longer than turnLongSpeechSecs, 0 (off) or 400 to 2300. null means not set, so the engine default (0, off) applies. Used only by the engine.
    - `turnLongSpeechSecs` number, nullable, required: Speech length in seconds above which turnLongSpeechFloorMs applies, 1 to 30. null means not set, so the engine default (5) applies. Has no effect while turnLongSpeechFloorMs is off.
    - `inboundVariables` object: Default values for {{variable}} placeholders on inbound calls, merged into the call's dynamic variables only for names the inbound call does not supply itself (caller_number, called_number, attempt_id, volai_*, trial_*, system__*). Absent when the agent has none. Not used on outbound calls. Works for either provider.
    - `workflow` object: Call split into phases (nodes). Absent means the agent runs as a single phase, as before. See the "Call phases (workflow)" section for the full shape, limits and an example.
      - `version` 1, required: Workflow format version, currently always 1.
      - `entry` string, required: Id of the node the call starts in. Must exist among nodes.
      - `nodes` object[], required: Call phases, 2 to 8 nodes.
        - `id` string, required: Machine id of this node: lowercase letters, digits and underscores, starting with a letter, up to 32 characters. Must be unique within the workflow. The words start, start_node, end and end_node are reserved.
        - `label` string, required: Human-readable phase name, 1 to 60 characters.
        - `prompt` string: Prompt addition that only applies while the call is in this node, up to 2000 characters. The agent's base systemPrompt should only hold what is true in every phase.
        - `knowledge` string: Extra knowledge that only applies in this node, up to 4000 characters. prompt and knowledge combined must not exceed 4000 characters for one node.
        - `toolIds` string[]: Ids of account tools (from list_tools) visible only while the call is in this node, at most 10. A tool not assigned to any node stays visible in every node.
        - `enterPhrase` string: Sentence spoken immediately on entering this node, at most once per call, up to 160 characters.
        - `enterBehavior` 'reply' | 'wait': Defaults to "reply". "wait" means the model does not answer in the same turn after speaking enterPhrase and waits for the caller instead; requires enterPhrase.
      - `edges` object[], required: Transitions between phases, 1 to 24 edges, at most 5 leaving any one node.
        - `id` string, required: Machine id of this edge: lowercase letters, digits and underscores, starting with a letter, up to 48 characters. Must be unique within the workflow.
        - `from` string, required: Id of the node this edge leaves.
        - `to` string, required: Id of the node this edge enters. Must differ from from.
        - `condition` string, required: When to take this edge, written about what the CALLER said (never about what the agent or a tool did), 5 to 200 characters. Goes verbatim into the description of the switch_to_{to} tool.
    - `calendar` object: Calendar availability rules for check_availability/book_appointment on volai's own voice engine. Absent means the agent does not book appointments. Effective only once provider is engine - see calendar_pending_engine_switch in warnings.
      - `integrationId` string, required: Id of the connected calendar integration this agent books through, from list_integrations.
      - `calendarId` string, required: Id of the specific calendar within that connection, from list_calendars. The agent writes appointments into this calendar, so it must be writable (accessRole owner or writer); a read-only calendar is rejected with calendar_invalid_calendar.
      - `busyCalendarIds` string[]: Other calendars in the same connection whose events also block a slot; nothing is written into them, so read-only calendars are fine. At most 4, without duplicates and without calendarId.
      - `timezone` string, required: IANA timezone the windows and spoken times are interpreted in, for example Europe/Prague.
      - `slotMinutes` union, required: Length of each offered appointment slot in minutes.
        - 15
        - 30
        - 45
        - 60
        - 90
        - 120
      - `minNoticeMinutes` number, required: Minimum notice before the earliest offered slot, in minutes.
      - `horizonDays` number, required: How many days ahead the agent searches for a free slot.
      - `bufferMinutes` number, required: Buffer kept free immediately before and after every busy event, in minutes.
      - `windows` object, required: Availability windows for every weekday. At least one weekday needs a non-empty window.
        - `mon` object[], required: Availability windows on Monday. An empty array means no availability that day.
          - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
          - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
        - `tue` object[], required: Availability windows on Tuesday. An empty array means no availability that day.
          - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
          - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
        - `wed` object[], required: Availability windows on Wednesday. An empty array means no availability that day.
          - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
          - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
        - `thu` object[], required: Availability windows on Thursday. An empty array means no availability that day.
          - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
          - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
        - `fri` object[], required: Availability windows on Friday. An empty array means no availability that day.
          - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
          - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
        - `sat` object[], required: Availability windows on Saturday. An empty array means no availability that day.
          - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
          - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
        - `sun` object[], required: Availability windows on Sunday. An empty array means no availability that day.
          - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone.
          - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone.
    - `missedCallSms` object, required: Send an SMS to the caller when this agent misses the call (unanswered outbound, missed inbound). enabled: false when off. text is a custom template (up to 320 characters); absent uses the default text in the agent's language.
      - `enabled` boolean, required
      - `text` string
    - `suspended` boolean, required: Whether the volai operator has manually suspended this agent. A suspended agent can't receive or make calls or send missed-call SMS; its settings stay editable. A suspension of the whole account is reported as the `account_suspended` error on every request instead.
  - `warnings` object[]
    - `code` 'first_message_no_ai_disclosure' | 'first_message_too_long' | 'dead_end' | 'short_condition' | 'entry_phrase_never_spoken' | 'empty_node' | 'base_prompt_long' | 'missing_enter_phrase' | 'condition_about_agent' | 'workflow_not_synced_to_provider' | 'workflow_node_tool_not_synced' | 'workflow_node_tool_missing' | 'calendar_pending_engine_switch' | 'prompt_variables_unavailable_inbound' | 'first_message_empty' | 'agent_misuse_suspected', required
    - `message` object, required
      - `cs` string, required
      - `en` string, required
    - `nodeId` string: Id of the workflow node this warning is about, when it belongs to one specific node rather than the agent as a whole.
    - `edgeId` string: Id of the workflow edge this warning is about, when it belongs to one specific edge rather than the agent as a whole.

## Other responses

- `400`: Error codes: invalid_name (request), invalid_system_prompt (request), invalid_language (request), tool_limit (account), invalid_data_fields (request), invalid_goal (request), invalid_knowledge (request), transfer_loop (request), blocked_destination (request), invalid_voicemail_message (request), voicemail_requires_engine (request), invalid_workflow (request), calendar_invalid_calendar (request), calendar_invalid_timezone (request), calendar_invalid_windows (request), calendar_no_windows (request), calendar_invalid_rules (request), validation (request).
- `401`: Error codes: unauthorized (request).
- `403`: Error codes: account_suspended (account).
- `404`: Error codes: calendar_integration_not_found (account), tool_not_found (account), agent_not_found (account).
- `409`: Error codes: in_progress (busy).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `502`: Error codes: engine_unavailable (service), engine_readback_mismatch (service).
- `503`: Error codes: engine_not_configured (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)