Create Call Agent
Create a new agent for a workspace.
An agent holds the voice, speech-to-text and language model a call flow speaks with. Create the agent first, then pass its _id as agent when you create a call flow.
Phone numbers are not attached here. Once the agent belongs to a call flow, attach a number with Assign Phone Number to Agent.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
Request Body
namestringrequiredName of the agent being created.
ttsModelobjectrequiredText-to-Speech (TTS) configuration for the agent. provider and voiceId are both required.
fallbackTtsModelobjectOptional second voice, used if the primary TTS provider fails during a call. Same fields as ttsModel.
sttProviderobjectSpeech-to-text provider, as { "id": "...", "name": "...", "description": "..." }. id is one of deepgram-nova-2, deepgram-nova-3, deepgram-nova-3-medical, deepgram-flux, deepgram-flux-multi, speechmatics, speechmatics-medical, whisper, gladia, xai, google-chirp-3, elevenlabs-scribe, assemblyai-universal-pro, gemini-transcribe-live.
fallbackSttProviderobjectOptional speech-to-text provider to fall back to. Same shape as sttProvider.
llmModelstringdefault: platform-llmLanguage model the agent uses to generate responses.
Defaults to platform-llm, the managed platform model. It is tuned for voice agents and kept current without any change to your configuration, and it is what agents created in the dashboard start on.
To pin a specific model instead, pass its id, for example gpt-4.1 or gemini-2.5-flash. The models on offer change over time, so call List Available Models for the current set rather than hardcoding one. A model that isn't on offer, or the retired trillet-llm, fails with 400.
fallbackLlmModelstringOptional model to fall back to if the primary model fails. Checked the same way as llmModel.
smartCallbackbooleandefault: falseEnable smart callback functionality for the agent.
maxAttemptsForSmartCallbacknumberdefault: 5Maximum number of callback attempts when smart callback is enabled.
gapBetweenEachAttemptForSmartCallbackarrayArray of time intervals between each callback attempt. Each item contains days and hours. Defaults to five gaps of one day. An item outside the ranges below is reset to { "days": 1, "hours": 0 }.
typestringdefault: voicevoice or chat.
settingsobjectVoice and model tuning. Stored exactly as sent: the API applies no defaults, and if you leave it out it stays unset. The dashboard starts new agents on { "speed": 0, "volume": 1, "temperature": 0.3 }.
phoneNumberIds and variables are ignored on create. Attach numbers with Assign Phone Number to Agent.
Response
200 with the saved agent.
_idstringUnique identifier for the newly created agent. Pass it as agent when you create a call flow to link the two. The agent then shows up inside that call flow and on the Phone Numbers page. An agent serves one call flow, so create a new agent for each flow.
workspaceIdstringWorkspace ID associated with the agent.
userIdstringUser ID of the agent creator.
namestringName of the agent.
ttsModelobjectText-to-Speech configuration for the agent, as sent (provider, voiceId, name, language, rimeModel, elevenLabsModel and any BYO key fields).
fallbackTtsModelobject | nullFallback voice, or null.
sttProviderobject | nullSpeech-to-text provider, or null.
llmModelstringLanguage model used by the agent. platform-llm if you didn't send one.
fallbackLlmModelstring | nullFallback language model, or null.
smartCallbackbooleanWhether smart callback is enabled for the agent.
maxAttemptsForSmartCallbacknumberMaximum number of callback attempts.
gapBetweenEachAttemptForSmartCallbackarrayArray of time intervals between callback attempts.
typestringvoice or chat.
phoneNumberIdsarrayAlways empty on a new agent.
activeSessionsarrayArray of active sessions for the agent.
settingsobjectSettings as sent, or absent if you didn't send any.
statusstringready for a new agent.
createdAtstringTimestamp when the agent was created.
updatedAtstringTimestamp when the agent was last updated.
Errors
| Status | Body | When |
|---|---|---|
400 | {"error": "Workspace ID is required"} | No x-workspace-id |
400 | {"message", "code": "TTS_MODEL_INVALID"} | ttsModel is missing, or has no provider or voiceId |
400 | {"message", "code": "LLM_MODEL_INVALID"} | llmModel or fallbackLlmModel isn't an available model, or is the retired trillet-llm |
500 | {"error": "..."} | Unexpected server error |
{
"name": "Customer Support Agent",
"ttsModel": {
"provider": "rime",
"voiceId": "mistv3_wildflower",
"name": "Wildflower",
"rimeModel": "mistv3",
"language": "en"
},
"llmModel": "platform-llm",
"smartCallback": true,
"maxAttemptsForSmartCallback": 3,
"gapBetweenEachAttemptForSmartCallback": [
{ "days": 1, "hours": 2 },
{ "days": 2, "hours": 0 },
{ "days": 3, "hours": 6 }
],
"settings": {
"speed": 0,
"volume": 1,
"temperature": 0.3
}
}{
"_id": "d5d5d5d5d5d5d5d5d5d5d5d5",
"workspaceId": "d1d1d1d1d1d1d1d1d1d1d1d1",
"userId": "a0a0a0a0a0a0a0a0a0a0a0a0",
"name": "Customer Support Agent",
"ttsModel": {
"provider": "rime",
"voiceId": "mistv3_wildflower",
"name": "Wildflower",
"language": "en",
"rimeModel": "mistv3",
"elevenLabsModel": null,
"elevenLabsApiKeySecret": null,
"cartesiaApiKeySecret": null
},
"fallbackTtsModel": null,
"sttProvider": null,
"llmModel": "platform-llm",
"fallbackLlmModel": null,
"smartCallback": true,
"maxAttemptsForSmartCallback": 3,
"gapBetweenEachAttemptForSmartCallback": [
{ "days": 1, "hours": 2 },
{ "days": 2, "hours": 0 },
{ "days": 3, "hours": 6 }
],
"type": "voice",
"settings": { "speed": 0, "volume": 1, "temperature": 0.3 },
"fallbackSettings": null,
"status": "ready",
"phoneNumberIds": [],
"activeSessions": [],
"createdAt": "2026-10-29T10:00:00.000Z",
"updatedAt": "2026-10-29T10:00:00.000Z"
}Last updated on