Agents

Create a new agent

View as Markdown

You can create a new agent by passing the name of the agent in the request body. You can use update-workflow endpoint next to assign custom workflow to the agent.

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.

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. Models waves, waves_lightning_large, waves_lightning_v2, and waves_lightning_v3_1 validate voiceId against the Waves API. All other models accept any voiceId. Cloned voices are regular voiceIds — use them with any 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.

telephonyProductIdlist of stringsOptional

IDs of telephony products (phone numbers) to associate with the agent for inbound/outbound calls.

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

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.
allowInboundCallbooleanOptionalDefaults to true
Whether the agent accepts inbound calls.
enableStyleGuidebooleanOptionalDefaults to true
Whether style guide enforcement is applied to agent responses.
speechFormattingbooleanOptional
Whether speech formatting is applied to the agent's responses.

Response

Agent created successfully
statusboolean
datastring
The ID of the created agent

Errors

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