Skip to navigation
Voice Agents APIAgents

Create a new agent

View as Markdown

Create a new agent by passing the agent name in the request body.

New agents have versioning enabled by default. To set the prompt, firstMessage, tools, or any runtime config, fork a draft from the auto-created initial version, edit it, publish, and activate. See the Versioning Lifecycle guide for the full flow.

The legacy PATCH /workflow/{workflowId} endpoint writes directly to the underlying workflow document and bypasses the version lifecycle; edits made that way are not captured as a version and may not propagate to live calls. Use the drafts flow above.

Server-applied defaults. If you omit a field on a minimal POST /agent, the server fills it in. Sending just {"name": "..."} and then reading the agent back with GET /agent/{id} returns the following subset:

{
  "synthesizer": {
    "voiceConfig": {
      "model": "waves_lightning_v3_1_pro",
      "voiceId": "blake",
      "gender": "male"
    },
    "speed": 1,
    "sampleRate": 24000
  },
  "slmModel": "electron",
  "language": { "default": "en", "supported": ["en"] },
  "workflowType": "single_prompt"
}

Any field you send on create overrides that path; the rest stay server-filled.

transcriberType is a read/serve-time default: POST /agent does not accept the field (it is silently dropped). Subsequent reads return pulse when the field is unset. To set a different value, PATCH /agent/{id} on a non-versioned agent or open a branch draft on a versioned agent.

Fetch the agent with GET /agent/{id} after creation to see the effective config before opening a branch draft.

Authentication

AuthorizationBearer

API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth.

Request

This endpoint expects an object.
namestringRequired
descriptionstringOptional
backgroundSoundenumOptionalDefaults to

Ambient background sound during calls. Options: '' (none), 'office', 'cafe', 'call_center', 'static'. Note: this value is currently overridden by the server default on creation; update via PATCH after creation.

Allowed values:
languageobjectOptional

Language configuration for the agent. Cross-field rule: default must be one of the values in supported. Tamil (ta) cannot be combined with other languages in supported.

synthesizerobjectOptional

Synthesizer (TTS) configuration for the agent. For waves, waves_lightning_large, waves_lightning_v2, waves_lightning_v3_1, and waves_lightning_v3_1_pro, voiceId is validated against the Waves voice catalog. The other models accept any voiceId. Cloned voices are regular voiceIds. Use them with a compatible Waves model.

globalKnowledgeBaseIdstringOptional

The global knowledge base ID of the agent. You can create a global knowledge base by using the /knowledgebase endpoint and assign it to the agent. The agent will use this knowledge base for its responses.

slmModelenumOptionalDefaults to electron

The LLM model to use for the agent. Note: gpt-5.2, electron-kogta, and electron-kogta-v2 require org-level access and return 403 if not enabled. workflowType must be single_prompt to use gpt-realtime or gpt-realtime-mini.

defaultVariablesobjectOptional
The default variables to use for the agent. These variables will be used if no variables are provided when initiating a conversation with the agent.
preCallAPIobjectOptional
Configuration for an API call to be made before the call starts. The response variables can be injected into the agent's prompt.
globalPromptstringOptional<=4000 characters

Set global instructions for your agent's personality, role, and behavior throughout conversations. Note: Only used for workflow_graph agents. Maximum 4000 characters.

workflowTypeenumOptional

The type of workflow to create for the agent. Defaults to single_prompt if not specified. Using workflow_graph requires conversational agent access (403 if not enabled).

Allowed values:
firstMessagestringOptional<=500 characters
The first message the agent sends when a conversation starts.
muteUserUntilFirstBotResponsebooleanOptional
When true, the user's audio is muted until the agent has finished its first response.
allowInterruptionsbooleanOptional
Whether the user can interrupt the agent while it is speaking.
waitForUserToSpeakFirstbooleanOptional
When true, the agent waits for the user to speak before sending the first message.
interruptionBackoffTimerdoubleOptional0-10
Seconds the agent waits after being interrupted before resuming speech.
smartTurnConfigobjectOptional

Smart turn-detection configuration. When enabled, the agent uses an additional model to decide whether the user has finished a turn.

voiceDetectionConfigobjectOptional

Voice activity detection (VAD) configuration. Controls how the agent decides when speech is present.

voiceMailDetectionConfigobjectOptional

Voicemail-detection configuration. When the call hits a voicemail tone, the agent plays endText and ends the call.

denoisingConfigobjectOptional

Background-noise denoising configuration for the agent's input audio.

redactionConfigobjectOptional
PII redaction configuration. When enabled, personally identifiable information is redacted from transcripts before storage.
pronunciationDictslist of objectsOptional

Pronunciation overrides — words the TTS engine should pronounce differently from its default.

llmIdleTimeoutConfigobjectOptional
Timeout configuration for the LLM stage of a conversation. Triggers a retry or call termination when the LLM does not respond within the configured window.
sessionTimeoutConfigobjectOptional
Maximum duration of a conversation session. The call ends after this elapsed time even if active.
timezoneobjectOptional
Timezone applied to scheduled actions and timestamps the agent reports to the user.
callDispositionConfigstringOptional
Configuration string for call disposition tracking.
enableStyleGuidebooleanOptionalDefaults to true
Whether style guide enforcement is applied to agent responses.
speechFormattingbooleanOptional
Whether speech formatting is applied to the agent's responses.
telephonyProductIdlist of stringsOptionalDeprecated

Deprecated, and ignored on create: the field is stripped, no bindings are written, and no Deprecation header is set; the request still returns 200. Attach numbers with POST /agent/{agentId}/answers after creating. (On PATCH /agent/{agentId} the field still works during the migration window.) See the Telephony API migration guide.

allowInboundCallbooleanOptionalDefaults to trueDeprecated

Deprecated. false still works as a routing kill switch during the migration window; true undoes a previous false, otherwise no effect. Detach the number via DELETE /agent/{agentId}/answers/{sourceId} instead.

Response

Agent created successfully
statusbooleanOptional
datastringOptional
The ID of the created agent

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
500
Internal Server Error