Create an agent

Display name of the agent. Leading and trailing whitespace is trimmed.

Instructions governing every call. Describe the role, facts the agent may use and when to hand off; do not include secrets. Whitespace is trimmed.

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 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.

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.

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.

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.

When the agent should transfer to the human destination. An empty string restores the default condition.

Whether to record calls. Defaults to true at creation and adds a short recording notice to the greeting. You remain responsible for appropriate disclosure.

One sentence defining a successful call for post-call evaluation on engine agents. An empty string clears it; PATCH also accepts null.

Additional reference text for the agent, separate from its instructions. An empty string clears it; PATCH also accepts null.

Whether to email the account owner a summary after each engine call. Defaults to true at creation.

Creation only: true requests the volai engine, false starts on ElevenLabs, and omission uses the deployment default, subject to engine availability, enablement and configured languages. cs or sk alone does not guarantee the engine. An explicit false that overrides the language's engine default returns the elevenlabs_by_explicit_choice warning. transferTo may subsequently attempt an engine switch. REST creation returns only id; read GET /v1/agents/{id} to verify provider and voiceId.

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.

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.

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).

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.

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.

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.

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.