curl --request POST \ --url https://prod-api.ringg.ai/ca/api/v0/public/agent \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: <api-key>' \ --data '{ "agent_name": "My Sales Agent", "introduction_and_objective": "You are a customer support agent for Acme Corp.", "response_guidelines": "Be polite, helpful, and concise. Always confirm understanding.", "task": "Help customers with their orders and answer product questions.", "primary_language": "en-IN", "voice_id": "00000000-0000-4000-8000-00000000010e", "intro_message": "Hello, this is Sarah from Acme Corp. How can I assist you today?", "faq": "Q: What are your hours? A: We are open 9am-6pm IST.", "sample_conversations": "User: Hi\nAgent: Hello! How can I help you today?", "secondary_language": "hi-IN", "agent_type": "outbound", "custom_variables": [ "callee_name", "mobile_number", "company", "lead_source" ], "call_config": { "call_time": { "call_start_time": "10:00", "call_end_time": "18:30", "timezone": "America/New_York" }, "max_call_length": 600, "idle_timeout_warning": 8, "idle_timeout_end": 20, "noise_filter_config": { "filter_noise": true, "noise_suppression_level": 95 }, "voicemail": { "detect": true, "action": "end", "retry": true }, "background_audio_config": { "audio_id": "office_ambience", "volume": 0.35 }, "mute_during_intro": false }}'
import requests
url = "https://prod-api.ringg.ai/ca/api/v0/public/agent"
payload = {
"agent_name": "My Sales Agent",
"introduction_and_objective": "You are a customer support agent for Acme Corp.",
"response_guidelines": "Be polite, helpful, and concise. Always confirm understanding.",
"task": "Help customers with their orders and answer product questions.",
"primary_language": "en-IN",
"voice_id": "00000000-0000-4000-8000-00000000010e",
"intro_message": "Hello, this is Sarah from Acme Corp. How can I assist you today?",
"faq": "Q: What are your hours? A: We are open 9am-6pm IST.",
"sample_conversations": "User: Hi
Agent: Hello! How can I help you today?",
"secondary_language": "hi-IN",
"agent_type": "outbound",
"custom_variables": ["callee_name", "mobile_number", "company", "lead_source"],
"call_config": {
"call_time": {
"call_start_time": "10:00",
"call_end_time": "18:30",
"timezone": "America/New_York"
},
"max_call_length": 600,
"idle_timeout_warning": 8,
"idle_timeout_end": 20,
"noise_filter_config": {
"filter_noise": True,
"noise_suppression_level": 95
},
"voicemail": {
"detect": True,
"action": "end",
"retry": True
},
"background_audio_config": {
"audio_id": "office_ambience",
"volume": 0.35
},
"mute_during_intro": False
}
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_name: 'My Sales Agent',
introduction_and_objective: 'You are a customer support agent for Acme Corp.',
response_guidelines: 'Be polite, helpful, and concise. Always confirm understanding.',
task: 'Help customers with their orders and answer product questions.',
primary_language: 'en-IN',
voice_id: '00000000-0000-4000-8000-00000000010e',
intro_message: 'Hello, this is Sarah from Acme Corp. How can I assist you today?',
faq: 'Q: What are your hours? A: We are open 9am-6pm IST.',
sample_conversations: 'User: Hi\nAgent: Hello! How can I help you today?',
secondary_language: 'hi-IN',
agent_type: 'outbound',
custom_variables: ['callee_name', 'mobile_number', 'company', 'lead_source'],
call_config: {
call_time: {call_start_time: '10:00', call_end_time: '18:30', timezone: 'America/New_York'},
max_call_length: 600,
idle_timeout_warning: 8,
idle_timeout_end: 20,
noise_filter_config: {filter_noise: true, noise_suppression_level: 95},
voicemail: {detect: true, action: 'end', retry: true},
background_audio_config: {audio_id: 'office_ambience', volume: 0.35},
mute_during_intro: false
}
})
};
fetch('https://prod-api.ringg.ai/ca/api/v0/public/agent', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
{
"message": "Voice does not support language 'en-US'",
"code": "VOICE_LANGUAGE_MISMATCH"
}
{
"message": "Invalid credentials"
}
{
"message": "<string>"
}
Create Agent
Create a single-prompt voice agent from a prompt, language, voice and first message, with optional call settings such as calling window and voicemail.
POST
/
public
/
agent
Create Agent
curl --request POST \ --url https://prod-api.ringg.ai/ca/api/v0/public/agent \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: <api-key>' \ --data '{ "agent_name": "My Sales Agent", "introduction_and_objective": "You are a customer support agent for Acme Corp.", "response_guidelines": "Be polite, helpful, and concise. Always confirm understanding.", "task": "Help customers with their orders and answer product questions.", "primary_language": "en-IN", "voice_id": "00000000-0000-4000-8000-00000000010e", "intro_message": "Hello, this is Sarah from Acme Corp. How can I assist you today?", "faq": "Q: What are your hours? A: We are open 9am-6pm IST.", "sample_conversations": "User: Hi\nAgent: Hello! How can I help you today?", "secondary_language": "hi-IN", "agent_type": "outbound", "custom_variables": [ "callee_name", "mobile_number", "company", "lead_source" ], "call_config": { "call_time": { "call_start_time": "10:00", "call_end_time": "18:30", "timezone": "America/New_York" }, "max_call_length": 600, "idle_timeout_warning": 8, "idle_timeout_end": 20, "noise_filter_config": { "filter_noise": true, "noise_suppression_level": 95 }, "voicemail": { "detect": true, "action": "end", "retry": true }, "background_audio_config": { "audio_id": "office_ambience", "volume": 0.35 }, "mute_during_intro": false }}'
import requests
url = "https://prod-api.ringg.ai/ca/api/v0/public/agent"
payload = {
"agent_name": "My Sales Agent",
"introduction_and_objective": "You are a customer support agent for Acme Corp.",
"response_guidelines": "Be polite, helpful, and concise. Always confirm understanding.",
"task": "Help customers with their orders and answer product questions.",
"primary_language": "en-IN",
"voice_id": "00000000-0000-4000-8000-00000000010e",
"intro_message": "Hello, this is Sarah from Acme Corp. How can I assist you today?",
"faq": "Q: What are your hours? A: We are open 9am-6pm IST.",
"sample_conversations": "User: Hi
Agent: Hello! How can I help you today?",
"secondary_language": "hi-IN",
"agent_type": "outbound",
"custom_variables": ["callee_name", "mobile_number", "company", "lead_source"],
"call_config": {
"call_time": {
"call_start_time": "10:00",
"call_end_time": "18:30",
"timezone": "America/New_York"
},
"max_call_length": 600,
"idle_timeout_warning": 8,
"idle_timeout_end": 20,
"noise_filter_config": {
"filter_noise": True,
"noise_suppression_level": 95
},
"voicemail": {
"detect": True,
"action": "end",
"retry": True
},
"background_audio_config": {
"audio_id": "office_ambience",
"volume": 0.35
},
"mute_during_intro": False
}
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_name: 'My Sales Agent',
introduction_and_objective: 'You are a customer support agent for Acme Corp.',
response_guidelines: 'Be polite, helpful, and concise. Always confirm understanding.',
task: 'Help customers with their orders and answer product questions.',
primary_language: 'en-IN',
voice_id: '00000000-0000-4000-8000-00000000010e',
intro_message: 'Hello, this is Sarah from Acme Corp. How can I assist you today?',
faq: 'Q: What are your hours? A: We are open 9am-6pm IST.',
sample_conversations: 'User: Hi\nAgent: Hello! How can I help you today?',
secondary_language: 'hi-IN',
agent_type: 'outbound',
custom_variables: ['callee_name', 'mobile_number', 'company', 'lead_source'],
call_config: {
call_time: {call_start_time: '10:00', call_end_time: '18:30', timezone: 'America/New_York'},
max_call_length: 600,
idle_timeout_warning: 8,
idle_timeout_end: 20,
noise_filter_config: {filter_noise: true, noise_suppression_level: 95},
voicemail: {detect: true, action: 'end', retry: true},
background_audio_config: {audio_id: 'office_ambience', volume: 0.35},
mute_during_intro: false
}
})
};
fetch('https://prod-api.ringg.ai/ca/api/v0/public/agent', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
{
"message": "Voice does not support language 'en-US'",
"code": "VOICE_LANGUAGE_MISMATCH"
}
{
"message": "Invalid credentials"
}
{
"message": "<string>"
}
Use it when your product sets up agents for its own customers from a template; for a one-off agent, the dashboard is quicker and also builds multi-prompt agents.The response returns the new agent’s ID as data.id. Store it: calls and campaigns need it as agent_id.
The prompt fields become the agent’s prompt sections, in this order:
Field
Section in the dashboard
introduction_and_objective
Objective
response_guidelines
Response Guidelines
task
Conversation Script; sample_conversations is added at its end
faq
FAQs (empty when faq is left out)
intro_message becomes the agent’s first message.primary_language and secondary_language accept en-US, en-GB, en-AU, en-IN, hi-IN, ta-IN, te-IN, bn-IN, mr-IN, kn-IN, ms-MY, zh-CN, od-IN, pa-IN and my-MM. The voice must support the language, or the request returns 400 with code VOICE_LANGUAGE_MISMATCH.
call_config sets how the agent’s calls behave. Every key is optional; leave one out to keep its default.
Field
What it controls
Default
call_time
Daily calling window: call_start_time and call_end_time (HH:MM, 24-hour) in timezone
09:00–21:00, Asia/Kolkata
max_call_length
Hard cap on call length, in seconds (10–3600)
240
idle_timeout_warning
Seconds of caller silence (0–600) before the agent asks if they are still there; 0 turns the check-in off
5
idle_timeout_end
Seconds of caller silence (1–600) before the call ends; must be greater than idle_timeout_warning
10
noise_filter_config
Noise cancellation on the caller’s audio: filter_noise on/off, noise_suppression_level 0–100
off, 80
voicemail
detect voicemail, then action: end, summarise, or static_message (speaks the static_message text); retry re-queues the call
detect on, end, retry on
background_audio_config
Ambient track under the agent’s voice: audio_id (only office_ambience) and volume from 0.0 to 1.0
off
mute_during_intro
true: the caller cannot interrupt the first message
true
{ "agent_name": "EMI reminder", "introduction_and_objective": "You are Asha, calling Acme Lending customers about an upcoming EMI.", "response_guidelines": "Be polite and brief. Confirm the due date before ending the call.", "task": "Remind the customer of the EMI due date and amount, and note if they want a callback.", "primary_language": "en-IN", "voice_id": "your-voice-id", "intro_message": "Hello, this is Asha from Acme Lending.", "call_config": { "call_time": { "call_start_time": "10:00", "call_end_time": "18:30", "timezone": "Asia/Kolkata" }, "max_call_length": 300, "idle_timeout_warning": 8, "idle_timeout_end": 20, "voicemail": { "detect": true, "action": "end", "retry": true }, "mute_during_intro": false }}
Outbound calls placed outside the window wait for the next opening, and so do retries. A campaign or an individual call can set its own window instead. The window may cross midnight: 22:00 to 06:00 is valid.timezone accepts any IANA zone, such as America/New_York, Europe/London, Asia/Dubai, Australia/Sydney or UTC.
Use the Region/City form. IST, PST and CST are rejected. EST, MST, HST and GMT are accepted but never change for daylight saving, so an agent on EST calls an hour late for most of the year compared with America/New_York.
To change call settings after creation, use edit_call_config on Edit agent settings, or Call settings in the dashboard. PATCH /public/agent/{agent_id} (Update Agent) changes the prompt fields, language, voice, first message, type and variables, but not call_config.
Before running a campaign, check the new agent with one individual call.
(Optional) Call behaviour for the agent. Every field is optional — omit the block, or any key in it, to accept the default. These are the same keys the settings are stored under, so what you send here is what the agent runs with.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Ringg AI","description":"Build AI agents that make and answer phone calls, talk on your website and chat on WhatsApp, then run them from the Ringg AI dashboard or REST API.","colors":{"primary":"#0A0A0B","light":"#FFFFFF","dark":"#0A0A0B"},"logo":{"light":"https://mintcdn.com/ringgai-0da73d20/ZLVFI55VhZ4gmYrF/logo/light.svg?fit=max\u0026auto=format\u0026n=ZLVFI55VhZ4gmYrF\u0026q=85\u0026s=053f22dbaf5140cd8e5dadb1d4d057cd","dark":"https://mintcdn.com/ringgai-0da73d20/ZLVFI55VhZ4gmYrF/logo/dark.svg?fit=max\u0026auto=format\u0026n=ZLVFI55VhZ4gmYrF\u0026q=85\u0026s=cf9075384ec572e1a19b939d5a8674af","href":"https://www.ringg.ai"},"favicon":"https://mintcdn.com/ringgai-0da73d20/ZLVFI55VhZ4gmYrF/favicon.svg?fit=max\u0026auto=format\u0026n=ZLVFI55VhZ4gmYrF\u0026q=85\u0026s=e612fcf76df43d6468baa340dc3fde50","api":{"playground":{"display":"interactive"},"examples":{"languages":["curl","python","javascript"]},"mdx":{"auth":{"method":"key","name":"X-API-KEY"},"server":"https://prod-api.ringg.ai/ca/api/v0"}},"appearance":{"default":"dark"},"background":{"decoration":"grid"},"navbar":{"links":[{"href":"/resources/learn/all-lessons","label":"Learn"},{"href":"mailto:admin@ringg.ai","label":"Contact us"}],"primary":{"type":"button","label":"Dashboard","href":"https://www.ringg.ai/dashboard"}},"footer":{"socials":{"x":"https://x.com/ringg_ai","linkedin":"https://www.linkedin.com/company/ringg","youtube":"https://www.youtube.com/@RinggAI","instagram":"https://www.instagram.com/ringg_ai","discord":"https://discord.gg/YuEnb8Vsca"},"links":[{"header":"For AI agents","items":[{"label":"llms.txt","href":"https://docs.ringg.ai/llms.txt"},{"label":"skill.md","href":"https://docs.ringg.ai/skill.md"},{"label":"OpenAPI spec","href":"https://docs.ringg.ai/api-reference/openapi.json"},{"label":"MCP server","href":"/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants"}]}]},"search":{"prompt":"Search the docs"},"seo":{"metatags":{"canonical":"https://docs.ringg.ai","og:site_name":"Ringg AI Docs","twitter:site":"@ringg_ai"},"organization":{"id":"https://www.ringg.ai/#organization","legalName":"Stoic AI Private Limited","url":"https://www.ringg.ai","logo":"https://assets.ringg.ai/images/logo/logo.svg","sameAs":["https://x.com/ringg_ai","https://www.linkedin.com/company/ringg","https://www.youtube.com/@RinggAI","https://www.instagram.com/ringg_ai","https://discord.gg/YuEnb8Vsca"]}},"icons":{"library":"lucide"},"styling":{"eyebrows":"breadcrumbs","latex":false},"errors":{"404":{"redirect":false,"title":"This page doesn't exist","description":"It may have moved in the docs rebuild. The suggestions below usually have it; otherwise start from [the introduction](/get-started/ringg-ai) or search above."}},"contextual":{"options":["copy","view","chatgpt","claude","mcp","download-spec"],"display":"header"},"markdown":{"instructions":["To search or read these docs, connect the Ringg docs MCP server at https://docs.ringg.ai/mcp (no key needed; tools search_ringg_ai and query_docs_filesystem_ringg_ai) instead of browsing pages one by one. Setup for each client: https://docs.ringg.ai/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants.md","The dashboard labels agents \"Assistants\"; these docs say \"agent\". Both mean the same object, identified by agent_id.","API base URL: https://prod-api.ringg.ai/ca/api/v0. Send the workspace API key in the X-API-KEY header, from server-side code only.","Placing a call dials a real phone number and spends credits. Confirm the number with the user before calling.","To act on a Ringg workspace (place calls, edit agents, read transcripts), use the separate Ringg workspace MCP server at https://mcp.ringg.ai/mcp: https://docs.ringg.ai/resources/mcp-server/workspace-mcp-server/overview.md"]},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"ringgai-0da73d20","hasAudioNarration":false,"actualSubdomain":"ringgai-0da73d20","customDomains":["docs.ringg.ai"],"gitSource":{"type":"github","owner":"stonkr","repo":"ringg-api-docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"feedback":{"thumbs":true,"agentFeedback":true,"edits":true,"issues":true},"entitlements":{},"buildId":"6adb52e21a579503f2299e23","clientVersion":"0.0.4102","searchFilterCounts":[{"language":"default","tag":"Documentation","count":90},{"language":"default","tag":"API reference","count":52},{"language":"default","tag":"Build agents","count":37},{"language":"default","tag":"Resources","count":34},{"language":"default","tag":"Learn","count":27},{"language":"default","tag":"Inventory","count":23},{"language":"default","tag":"Deploy","count":22},{"language":"default","tag":"Customize agent behaviour","count":19},{"language":"default","tag":"Agents","count":17},{"language":"default","tag":"Calling","count":15}],"searchSettings":{"showContentSnippets":true,"maxResults":8}},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"privacy":{"consentBanner":{"enabled":false}},"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":"img.nav-logo{height:1.375rem!important;width:auto!important}.figure-card{display:flex;flex-direction:column;margin:0.5rem 0;overflow:hidden;border:1px solid rgb(10 10 11 / 0.08);border-radius:1rem;background:#ffffff;text-decoration:none!important;transition:border-color 150ms}.figure-card:hover{border-color:rgb(10 10 11 / 0.2)}.dark .figure-card{border-color:rgb(255 255 255 / 0.08);background:rgb(var(--background-dark))}.dark .figure-card:hover{border-color:rgb(255 255 255 / 0.2)}.figure-card-panel{display:flex;justify-content:center;height:12rem;margin:0.375rem 0.375rem 0;border-radius:0.75rem;-webkit-mask-image:linear-gradient(to bottom, #000 62%, transparent);mask-image:linear-gradient(to bottom, #000 62%, transparent);background:#f6f6f7 url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='384' height='256' fill='none' stroke='%230a0a0b' stroke-opacity='0.03' stroke-width='1.5'%3E%3Ccircle cx='32' cy='32' r='25'/%3E%3Ccircle cx='96' cy='32' r='25'/%3E%3Crect x='135' y='7' width='50' height='50' rx='8'/%3E%3Ccircle cx='224' cy='32' r='25'/%3E%3Ccircle cx='288' cy='32' r='25'/%3E%3Ccircle cx='352' cy='32' r='25'/%3E%3Ccircle cx='32' cy='96' r='25'/%3E%3Ccircle cx='96' cy='96' r='25'/%3E%3Ccircle cx='160' cy='96' r='25'/%3E%3Ccircle cx='224' cy='96' r='25'/%3E%3Ccircle cx='288' cy='96' r='25'/%3E%3Ccircle cx='352' cy='96' r='25'/%3E%3Ccircle cx='32' cy='160' r='25'/%3E%3Crect x='71' y='135' width='50' height='50' rx='8'/%3E%3Ccircle cx='160' cy='160' r='25'/%3E%3Ccircle cx='224' cy='160' r='25'/%3E%3Crect x='263' y='135' width='50' height='50' rx='8'/%3E%3Crect x='327' y='135' width='50' height='50' rx='8'/%3E%3Crect x='7' y='199' width='50' height='50' rx='8'/%3E%3Ccircle cx='96' cy='224' r='25'/%3E%3Crect x='135' y='199' width='50' height='50' rx='8'/%3E%3Ccircle cx='224' cy='224' r='25'/%3E%3Crect x='263' y='199' width='50' height='50' rx='8'/%3E%3Ccircle cx='352' cy='224' r='25'/%3E%3C/svg%3E\") center / 192px 128px}.dark .figure-card-panel{background:#0f0f11 url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='384' height='256' fill='none' stroke='%23ffffff' stroke-opacity='0.025' stroke-width='1.5'%3E%3Ccircle cx='32' cy='32' r='25'/%3E%3Ccircle cx='96' cy='32' r='25'/%3E%3Crect x='135' y='7' width='50' height='50' rx='8'/%3E%3Ccircle cx='224' cy='32' r='25'/%3E%3Ccircle cx='288' cy='32' r='25'/%3E%3Ccircle cx='352' cy='32' r='25'/%3E%3Ccircle cx='32' cy='96' r='25'/%3E%3Ccircle cx='96' cy='96' r='25'/%3E%3Ccircle cx='160' cy='96' r='25'/%3E%3Ccircle cx='224' cy='96' r='25'/%3E%3Ccircle cx='288' cy='96' r='25'/%3E%3Ccircle cx='352' cy='96' r='25'/%3E%3Ccircle cx='32' cy='160' r='25'/%3E%3Crect x='71' y='135' width='50' height='50' rx='8'/%3E%3Ccircle cx='160' cy='160' r='25'/%3E%3Ccircle cx='224' cy='160' r='25'/%3E%3Crect x='263' y='135' width='50' height='50' rx='8'/%3E%3Crect x='327' y='135' width='50' height='50' rx='8'/%3E%3Crect x='7' y='199' width='50' height='50' rx='8'/%3E%3Ccircle cx='96' cy='224' r='25'/%3E%3Crect x='135' y='199' width='50' height='50' rx='8'/%3E%3Ccircle cx='224' cy='224' r='25'/%3E%3Crect x='263' y='199' width='50' height='50' rx='8'/%3E%3Ccircle cx='352' cy='224' r='25'/%3E%3C/svg%3E\") center / 192px 128px}.figure-card-panel{--hairline-plate: #f6f6f7}.dark .figure-card-panel{--hairline-plate: #0f0f11}.figure-card-panel>[data-hairline]{width:13.75rem}.figure-card-text{flex:1;padding:0.25rem 1.25rem 1.25rem}.figure-card-title{font-weight:600;color:rgb(17 24 39)}.dark .figure-card-title{color:rgb(255 255 255)}.figure-card-body{margin-top:0.25rem;font-size:0.9375rem;line-height:1.6;color:rgb(75 85 99)}.dark .figure-card-body{color:rgb(161 161 170)}"}],"page":{"pagePath":"api-reference/agents/create-agent","slug":"/api-reference/agents/create-agent","pageMetadata":{"openapi":"post /public/agent","description":"Create a single-prompt voice agent from a prompt, language, voice and first message, with optional call settings such as calling window and voicemail.","related":[{"List agents":"/api-reference/agents/get-assistants"}],"title":"Create Agent","href":"/api-reference/agents/create-agent"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Create a single-prompt voice agent from a prompt, language, voice and first message, with optional call settings such as calling window and voicemail.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];const RelatedTopics=({items})=>{const _components={a:`a`,..._provideComponents()},{Icon}=_components;if(!Icon)_missingMdxReference(`Icon`,true);return _jsxs(`div`,{className:`not-prose mint-mt-12`,children:[_jsx(`div`,{className:`mint-text-sm mint-font-medium mint-text-gray-500 dark:mint-text-zinc-400 mint-mb-3`,children:`Related topics`}),_jsx(`div`,{className:`mint-flex mint-flex-col mint-gap-2.5`,children:items.map(([title,href])=>_jsxs(_components.a,{href,className:`mint-flex mint-items-center mint-gap-2.5 mint-text-sm mint-text-gray-700 hover:mint-text-gray-950 dark:mint-text-zinc-300 dark:hover:mint-text-white`,children:[_jsx(Icon,{icon:`file-text`,size:16,color:`currentColor`}),title]},href))})]})};function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Table,Warning,_MdxComponentBoundary}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);if(!_MdxComponentBoundary)_missingMdxReference(`_MdxComponentBoundary`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Use it when your product sets up agents for its own customers from a template; for a one-off agent, the `,_jsx(_components.a,{href:`/documentation/build-agents/agents/create-an-agent`,children:`dashboard`}),` is quicker and also builds multi-prompt agents.`]}),`\n`,_jsxs(_components.p,{children:[`The response returns the new agent’s ID as `,_jsx(_components.code,{children:`data.id`}),`. Store it: calls and campaigns need it as `,_jsx(_components.code,{children:`agent_id`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`prompt-sections`,children:`Prompt sections`}),`\n`,_jsx(_components.p,{children:`The prompt fields become the agent’s prompt sections, in this order:`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Field`}),_jsx(_components.th,{children:`Section in the dashboard`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`introduction_and_objective`})}),_jsx(_components.td,{children:`Objective`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`response_guidelines`})}),_jsx(_components.td,{children:`Response Guidelines`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`task`})}),_jsxs(_components.td,{children:[`Conversation Script; `,_jsx(_components.code,{children:`sample_conversations`}),` is added at its end`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`faq`})}),_jsxs(_components.td,{children:[`FAQs (empty when `,_jsx(_components.code,{children:`faq`}),` is left out)`]})]})]})]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`intro_message`}),` becomes the agent’s first message.`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`primary_language`}),` and `,_jsx(_components.code,{children:`secondary_language`}),` accept `,_jsx(_components.code,{children:`en-US`}),`, `,_jsx(_components.code,{children:`en-GB`}),`, `,_jsx(_components.code,{children:`en-AU`}),`, `,_jsx(_components.code,{children:`en-IN`}),`, `,_jsx(_components.code,{children:`hi-IN`}),`, `,_jsx(_components.code,{children:`ta-IN`}),`, `,_jsx(_components.code,{children:`te-IN`}),`, `,_jsx(_components.code,{children:`bn-IN`}),`, `,_jsx(_components.code,{children:`mr-IN`}),`, `,_jsx(_components.code,{children:`kn-IN`}),`, `,_jsx(_components.code,{children:`ms-MY`}),`, `,_jsx(_components.code,{children:`zh-CN`}),`, `,_jsx(_components.code,{children:`od-IN`}),`, `,_jsx(_components.code,{children:`pa-IN`}),` and `,_jsx(_components.code,{children:`my-MM`}),`. The voice must support the language, or the request returns `,_jsx(_components.code,{children:`400`}),` with code `,_jsx(_components.code,{children:`VOICE_LANGUAGE_MISMATCH`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`call-settings`,children:`Call settings`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`call_config`}),` sets how the agent’s calls behave. Every key is optional; leave one out to keep its default.`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Field`}),_jsx(_components.th,{children:`What it controls`}),_jsx(_components.th,{children:`Default`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`call_time`})}),_jsxs(_components.td,{children:[`Daily calling window: `,_jsx(_components.code,{children:`call_start_time`}),` and `,_jsx(_components.code,{children:`call_end_time`}),` (`,_jsx(_components.code,{children:`HH:MM`}),`, 24-hour) in `,_jsx(_components.code,{children:`timezone`})]}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`09:00`}),`–`,_jsx(_components.code,{children:`21:00`}),`, `,_jsx(_components.code,{children:`Asia/Kolkata`})]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`max_call_length`})}),_jsx(_components.td,{children:`Hard cap on call length, in seconds (10–3600)`}),_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`240`})})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`idle_timeout_warning`})}),_jsxs(_components.td,{children:[`Seconds of caller silence (0–600) before the agent asks if they are still there; `,_jsx(_components.code,{children:`0`}),` turns the check-in off`]}),_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`5`})})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`idle_timeout_end`})}),_jsxs(_components.td,{children:[`Seconds of caller silence (1–600) before the call ends; must be greater than `,_jsx(_components.code,{children:`idle_timeout_warning`})]}),_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`10`})})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`noise_filter_config`})}),_jsxs(_components.td,{children:[`Noise cancellation on the caller’s audio: `,_jsx(_components.code,{children:`filter_noise`}),` on/off, `,_jsx(_components.code,{children:`noise_suppression_level`}),` 0–100`]}),_jsxs(_components.td,{children:[`off, `,_jsx(_components.code,{children:`80`})]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`voicemail`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`detect`}),` voicemail, then `,_jsx(_components.code,{children:`action`}),`: `,_jsx(_components.code,{children:`end`}),`, `,_jsx(_components.code,{children:`summarise`}),`, or `,_jsx(_components.code,{children:`static_message`}),` (speaks the `,_jsx(_components.code,{children:`static_message`}),` text); `,_jsx(_components.code,{children:`retry`}),` re-queues the call`]}),_jsxs(_components.td,{children:[`detect on, `,_jsx(_components.code,{children:`end`}),`, retry on`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`background_audio_config`})}),_jsxs(_components.td,{children:[`Ambient track under the agent’s voice: `,_jsx(_components.code,{children:`audio_id`}),` (only `,_jsx(_components.code,{children:`office_ambience`}),`) and `,_jsx(_components.code,{children:`volume`}),` from `,_jsx(_components.code,{children:`0.0`}),` to `,_jsx(_components.code,{children:`1.0`})]}),_jsx(_components.td,{children:`off`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`mute_during_intro`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`true`}),`: the caller cannot interrupt the first message`]}),_jsx(_components.td,{children:_jsx(_components.code,{children:`true`})})]})]})]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`17`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`17`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"agent_name\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"EMI reminder\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"introduction_and_objective\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"You are Asha, calling Acme Lending customers about an upcoming EMI.\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"response_guidelines\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Be polite and brief. Confirm the due date before ending the call.\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"task\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Remind the customer of the EMI due date and amount, and note if they want a callback.\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"primary_language\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"en-IN\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"voice_id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"your-voice-id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"intro_message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Hello, this is Asha from Acme Lending.\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"call_config\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"call_time\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: { `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"call_start_time\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"10:00\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"call_end_time\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"18:30\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"timezone\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Asia/Kolkata\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"max_call_length\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`300`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"idle_timeout_warning\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`8`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"idle_timeout_end\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`20`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"voicemail\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: { `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"detect\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`true`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"action\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"end\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"retry\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`true`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"mute_during_intro\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`false`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Get `,_jsx(_components.code,{children:`voice_id`}),` from `,_jsx(_components.a,{href:`/api-reference/agents/get-assistant-voices`,children:`List voices`}),`.`]}),`\n`,_jsx(Heading,{level:`3`,id:`calling-window`,children:`Calling window`}),`\n`,_jsxs(_components.p,{children:[`Outbound calls placed outside the window wait for the next opening, and so do retries. A campaign or an individual call can set its own window instead. The window may cross midnight: `,_jsx(_components.code,{children:`22:00`}),` to `,_jsx(_components.code,{children:`06:00`}),` is valid.`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`timezone`}),` accepts any IANA zone, such as `,_jsx(_components.code,{children:`America/New_York`}),`, `,_jsx(_components.code,{children:`Europe/London`}),`, `,_jsx(_components.code,{children:`Asia/Dubai`}),`, `,_jsx(_components.code,{children:`Australia/Sydney`}),` or `,_jsx(_components.code,{children:`UTC`}),`.`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`Use the `,_jsx(_components.code,{children:`Region/City`}),` form. `,_jsx(_components.code,{children:`IST`}),`, `,_jsx(_components.code,{children:`PST`}),` and `,_jsx(_components.code,{children:`CST`}),` are rejected. `,_jsx(_components.code,{children:`EST`}),`, `,_jsx(_components.code,{children:`MST`}),`, `,_jsx(_components.code,{children:`HST`}),` and `,_jsx(_components.code,{children:`GMT`}),` are accepted but never change for daylight saving, so an agent on `,_jsx(_components.code,{children:`EST`}),` calls an hour late for most of the year compared with `,_jsx(_components.code,{children:`America/New_York`}),`.`]})}),`\n`,_jsx(Heading,{level:`3`,id:`validation-rules`,children:`Validation rules`}),`\n`,_jsx(_components.p,{children:`The request fails, rather than the agent’s later calls, when:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`a time is not zero-padded 24-hour (`,_jsx(_components.code,{children:`09:00`}),` works, `,_jsx(_components.code,{children:`9:00`}),` and `,_jsx(_components.code,{children:`9:00 AM`}),` do not);`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`idle_timeout_warning`}),` is not less than `,_jsx(_components.code,{children:`idle_timeout_end`}),`;`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`background_audio_config.volume`}),` is outside `,_jsx(_components.code,{children:`0.0`}),`–`,_jsx(_components.code,{children:`1.0`}),` (send `,_jsx(_components.code,{children:`0.5`}),`, not `,_jsx(_components.code,{children:`50`}),`).`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`notes`,children:`Notes`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`To change call settings after creation, use `,_jsx(_components.code,{children:`edit_call_config`}),` on `,_jsx(_components.a,{href:`/api-reference/agents/edit-assistant`,children:`Edit agent settings`}),`, or `,_jsx(_components.a,{href:`/documentation/build-agents/customize-agent-behaviour/call-settings`,children:`Call settings`}),` in the dashboard. `,_jsx(_components.code,{children:`PATCH /public/agent/{agent_id}`}),` (Update Agent) changes the prompt fields, language, voice, first message, type and variables, but not `,_jsx(_components.code,{children:`call_config`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Before running a campaign, check the new agent with one `,_jsx(_components.a,{href:`/api-reference/calling/individual-calls/initiate-individual-call`,children:`individual call`}),`.`]}),`\n`]}),`\n`,_jsx(_MdxComponentBoundary,{name:`RelatedTopics`,children:_jsx(RelatedTopics,{items:[[`List agents`,`/api-reference/agents/get-assistants`]]})})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{RelatedTopics,default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"openapi":"post /public/agent","description":"Create a single-prompt voice agent from a prompt, language, voice and first message, with optional call settings such as calling window and voicemail.","related":[{"List agents":"/api-reference/agents/get-assistants"}],"title":"Create Agent","href":"/api-reference/agents/create-agent"}}},"mdxSourceWithNoJs":null,"noJsSplices":[[149,855,")=>null;function _cr"]]},"mdxExtracts":{"tableOfContents":[{"title":"Prompt sections","slug":"prompt-sections","depth":2,"children":[]},{"title":"Call settings","slug":"call-settings","depth":2,"children":[{"title":"Calling window","slug":"calling-window","depth":3,"children":[]},{"title":"Validation rules","slug":"validation-rules","depth":3,"children":[]}]},{"title":"Notes","slug":"notes","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/ringgai-0da73d20/45c33e65ef05fabf/hairline.js"],"dynamicCss":".mint-mb-3 {\n margin-bottom: 0.75rem\n}\n.mint-mt-12 {\n margin-top: 3rem\n}\n.mint-flex {\n display: flex\n}\n.mint-flex-col {\n flex-direction: column\n}\n.mint-items-center {\n align-items: center\n}\n.mint-gap-2\\.5 {\n gap: 0.625rem\n}\n.mint-text-sm {\n font-size: 0.875rem;\n line-height: 1.25rem\n}\n.mint-font-medium {\n font-weight: 500\n}\n.mint-text-gray-500 {\n --tw-text-opacity: 1;\n color: rgb(107 114 128 / var(--tw-text-opacity, 1))\n}\n.mint-text-gray-700 {\n --tw-text-opacity: 1;\n color: rgb(55 65 81 / var(--tw-text-opacity, 1))\n}\n.hover\\:mint-text-gray-950:hover {\n --tw-text-opacity: 1;\n color: rgb(3 7 18 / var(--tw-text-opacity, 1))\n}\n.dark\\:mint-text-zinc-300:is(.dark *) {\n --tw-text-opacity: 1;\n color: rgb(212 212 216 / var(--tw-text-opacity, 1))\n}\n.dark\\:mint-text-zinc-400:is(.dark *) {\n --tw-text-opacity: 1;\n color: rgb(161 161 170 / var(--tw-text-opacity, 1))\n}\n.dark\\:hover\\:mint-text-white:hover:is(.dark *) {\n --tw-text-opacity: 1;\n color: rgb(255 255 255 / var(--tw-text-opacity, 1))\n}","openApiReferenceData":{"operation":{"tags":["agent"],"summary":"Create Agent","x-mint":{"metadata":{"title":"Create Agent | Ringg AI","og:title":"Create Agent | Ringg AI"}},"description":"Create a single-prompt voice agent from a prompt, language, voice and first message, with optional call settings such as calling window and voicemail.","operationId":"createAgent","requestBody":"d514e61c-8769-47f7-b761-db3630f42ed7","responses":{"200":"afe7b1f2-4607-4759-b76d-034998097019","400":"2f1b2091-98de-4b7c-9d19-9a9a9b6a2a40","401":"2b9d3339-8fd8-41b6-8331-1f56317dd168","422":"be11201b-74c4-402a-81e5-55ffd9fbf823"},"method":"post","type":"path","servers":["4e60091d-90fb-4aa4-8774-bd7b6fd296da"],"security":["8d4782e7-e89d-48a8-81fa-302bad6331cd"],"path":"/public/agent","baseUrlOptions":["https://prod-api.ringg.ai/ca/api/v0"],"title":"Create Agent","codeSamples":[],"requestExampleLanguages":["bash","python","javascript"],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_name","introduction_and_objective","response_guidelines","task","primary_language","voice_id","intro_message"],"properties":{"agent_name":{"type":"string","maxLength":100,"description":"(Required) Name of the agent","example":"My Sales Agent","isRequired":true,"uniqueKey":"agent_name","typeLabel":"string"},"introduction_and_objective":{"type":"string","maxLength":2000,"description":"(Required) Introduction and objective of the agent","example":"You are a customer support agent for Acme Corp.","isRequired":true,"uniqueKey":"introduction_and_objective","typeLabel":"string"},"response_guidelines":{"type":"string","maxLength":3000,"description":"(Required) Guidelines for how the agent should respond","example":"Be polite, helpful, and concise. Always confirm understanding.","isRequired":true,"uniqueKey":"response_guidelines","typeLabel":"string"},"task":{"type":"string","maxLength":1500,"description":"(Required) The task the agent should perform","example":"Help customers with their orders and answer product questions.","isRequired":true,"uniqueKey":"task","typeLabel":"string"},"primary_language":{"type":"string","enum":["en-US","en-GB","en-AU","en-IN","hi-IN","ta-IN","te-IN","bn-IN","mr-IN","kn-IN","ms-MY","zh-CN","od-IN","pa-IN","my-MM"],"description":"(Required) Primary language locale for the agent","example":"en-IN","isRequired":true,"uniqueKey":"primary_language","typeLabel":"enum\u003cstring>"},"voice_id":{"type":"string","format":"uuid","description":"(Required) Voice ID (UUID). Get available voices from the List Voices endpoint.","example":"00000000-0000-4000-8000-00000000010e","isRequired":true,"uniqueKey":"voice_id","typeLabel":"string\u003cuuid>"},"intro_message":{"type":"string","maxLength":500,"description":"(Required) Introduction message the agent will speak when the call starts","example":"Hello, this is Sarah from Acme Corp. How can I assist you today?","isRequired":true,"uniqueKey":"intro_message","typeLabel":"string"},"faq":{"type":"string","maxLength":5000,"description":"(Optional) FAQ content for the agent","example":"Q: What are your hours? A: We are open 9am-6pm IST.","uniqueKey":"faq","typeLabel":"string"},"sample_conversations":{"type":"string","maxLength":5000,"description":"(Optional) Example conversations for the agent. Use \\n for newlines between turns.","example":"User: Hi\nAgent: Hello! How can I help you today?","uniqueKey":"sample_conversations","typeLabel":"string"},"secondary_language":{"type":"string","enum":["en-US","en-GB","en-AU","en-IN","hi-IN","ta-IN","te-IN","bn-IN","mr-IN","kn-IN","ms-MY","zh-CN","od-IN","pa-IN","my-MM"],"description":"(Optional) Secondary language locale for the agent","example":"hi-IN","uniqueKey":"secondary_language","typeLabel":"enum\u003cstring>"},"agent_type":{"type":"string","enum":["inbound","outbound","outbound_inbound"],"default":"outbound","description":"(Required) Type of agent. Defaults to outbound.","example":"outbound","uniqueKey":"agent_type","typeLabel":"enum\u003cstring>"},"custom_variables":{"type":"array","items":{"type":"string","uniqueKey":"custom_variables.items.[INDEX]","typeLabel":"string"},"description":"(Optional) Custom variables for the agent. For outbound agents, callee_name and mobile_number are always included automatically.","example":["callee_name","mobile_number","company","lead_source"],"uniqueKey":"custom_variables","typeLabel":"string[]"},"call_config":{"type":"object","description":"(Optional) Call behaviour for the agent. Every field is optional — omit the block, or any key in it, to accept the default. These are the same keys the settings are stored under, so what you send here is what the agent runs with.","properties":{"call_time":{"type":"object","description":"Daily window the agent may place calls in. Outside it an outbound call is not dialled immediately, and retries are pushed to the next opening. Applies to the agent's own calls; a campaign or an individual call can override it.","properties":{"call_start_time":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","description":"Earliest local time the agent may dial, 'HH:MM' 24-hour (default: 09:00).","default":"09:00","example":"10:00","uniqueKey":"call_config.call_time.call_start_time","typeLabel":"string"},"call_end_time":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","description":"Latest local time the agent may dial, 'HH:MM' 24-hour. The window may cross midnight (e.g. 22:00-06:00) (default: 21:00).","default":"21:00","example":"18:30","uniqueKey":"call_config.call_time.call_end_time","typeLabel":"string"},"timezone":{"type":"string","description":"IANA timezone the window is expressed in. **Any IANA zone is supported**, not just India - e.g. America/New_York, Europe/London, Asia/Dubai, Asia/Riyadh, Australia/Sydney, UTC. Always use the full Region/City form: 'IST'/'PST' are rejected outright, while 'EST'/'MST'/'GMT' are accepted but are fixed-offset zones that never observe daylight saving (an agent on 'EST' runs an hour behind New York for most of the year) (default: Asia/Kolkata).","default":"Asia/Kolkata","example":"America/New_York","uniqueKey":"call_config.call_time.timezone","typeLabel":"string"}},"example":{"call_start_time":"10:00","call_end_time":"18:30","timezone":"America/New_York"},"uniqueKey":"call_config.call_time","typeLabel":"object"},"max_call_length":{"type":"integer","minimum":10,"maximum":3600,"description":"Hard cap on call duration in seconds (default: 240).","default":240,"example":600,"uniqueKey":"call_config.max_call_length","typeLabel":"integer"},"idle_timeout_warning":{"type":"integer","minimum":0,"maximum":600,"description":"Seconds of caller silence before the agent checks in (“Are you still there?”). Must be less than idle_timeout_end; use 0 to disable the check-in (default: 5).","default":5,"example":8,"uniqueKey":"call_config.idle_timeout_warning","typeLabel":"integer"},"idle_timeout_end":{"type":"integer","minimum":1,"maximum":600,"description":"Seconds of caller silence before the call is dropped. Must be greater than idle_timeout_warning (default: 10).","default":10,"example":20,"uniqueKey":"call_config.idle_timeout_end","typeLabel":"integer"},"noise_filter_config":{"type":"object","description":"Background-noise cancellation applied to the caller's audio.","properties":{"filter_noise":{"type":"boolean","description":"Turn noise cancellation on (default: false).","default":false,"example":true,"uniqueKey":"call_config.noise_filter_config.filter_noise","typeLabel":"boolean"},"noise_suppression_level":{"type":"integer","minimum":0,"maximum":100,"description":"Suppression strength, 0-100 (default: 80).","default":80,"example":95,"uniqueKey":"call_config.noise_filter_config.noise_suppression_level","typeLabel":"integer"}},"example":{"filter_noise":true,"noise_suppression_level":95},"uniqueKey":"call_config.noise_filter_config","typeLabel":"object"},"voicemail":{"type":"object","description":"Voicemail / answering-machine handling.","properties":{"detect":{"type":"boolean","description":"Detect that the call reached a voicemail (default: true).","default":true,"example":true,"uniqueKey":"call_config.voicemail.detect","typeLabel":"boolean"},"action":{"type":"string","enum":["end","summarise","static_message"],"description":"What the agent does once it detects a voicemail: hang up, leave a generated summary, or speak static_message (default: end).","default":"end","example":"end","uniqueKey":"call_config.voicemail.action","typeLabel":"enum\u003cstring>"},"retry":{"type":"boolean","description":"Re-queue the call for a later attempt after hitting voicemail (default: true).","default":true,"example":true,"uniqueKey":"call_config.voicemail.retry","typeLabel":"boolean"},"static_message":{"oneOf":[{"type":"string","description":"Spoken verbatim when action is static_message. Ignored otherwise.","example":"Sorry we missed you, please call us back.","uniqueKey":"call_config.voicemail.static_message.oneOf.0","typeLabel":"string"},{"type":"null","description":"Spoken verbatim when action is static_message. Ignored otherwise.","example":"Sorry we missed you, please call us back.","uniqueKey":"call_config.voicemail.static_message.oneOf.1","typeLabel":"null"}],"uniqueKey":"call_config.voicemail.static_message","typeLabel":"string | null"}},"example":{"detect":true,"action":"end","retry":true},"uniqueKey":"call_config.voicemail","typeLabel":"object"},"background_audio_config":{"type":"object","description":"Ambient audio mixed under the agent's speech. Omit the whole object to keep background audio off.","properties":{"audio_id":{"type":"string","enum":["office_ambience"],"description":"(Required within this object) Track to play. office_ambience is the only track available.","example":"office_ambience","uniqueKey":"call_config.background_audio_config.audio_id","typeLabel":"enum\u003cstring>"},"volume":{"type":"number","minimum":0,"maximum":1,"description":"Playback level as a fraction between 0.0 and 1.0 — not a percentage (default: 0.5).","default":0.5,"example":0.35,"uniqueKey":"call_config.background_audio_config.volume","typeLabel":"number"},"mixing":{"type":"boolean","description":"Mix the track under the agent's speech (default: true).","default":true,"example":true,"uniqueKey":"call_config.background_audio_config.mixing","typeLabel":"boolean"},"loop":{"type":"boolean","description":"Repeat the track for the whole call (default: true).","default":true,"example":true,"uniqueKey":"call_config.background_audio_config.loop","typeLabel":"boolean"}},"example":{"audio_id":"office_ambience","volume":0.35},"uniqueKey":"call_config.background_audio_config","typeLabel":"object"},"mute_during_intro":{"type":"boolean","description":"When true the caller cannot interrupt the intro message — the agent finishes speaking it before it starts listening. Set false to make the first message interruptible (default: true).","default":true,"example":false,"uniqueKey":"call_config.mute_during_intro","typeLabel":"boolean"}},"example":{"call_time":{"call_start_time":"10:00","call_end_time":"18:30","timezone":"America/New_York"},"max_call_length":600,"idle_timeout_warning":8,"idle_timeout_end":20,"noise_filter_config":{"filter_noise":true,"noise_suppression_level":95},"voicemail":{"detect":true,"action":"end","retry":true},"background_audio_config":{"audio_id":"office_ambience","volume":0.35},"mute_during_intro":false},"uniqueKey":"call_config","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"agent_name":"My Sales Agent","introduction_and_objective":"You are a customer support agent for Acme Corp.","response_guidelines":"Be polite, helpful, and concise. Always confirm understanding.","task":"Help customers with their orders and answer product questions.","primary_language":"en-IN","voice_id":"00000000-0000-4000-8000-00000000010e","intro_message":"Hello, this is Sarah from Acme Corp. How can I assist you today?","faq":"Q: What are your hours? A: We are open 9am-6pm IST.","sample_conversations":"User: Hi\nAgent: Hello! How can I help you today?","secondary_language":"hi-IN","agent_type":"outbound","custom_variables":["callee_name","mobile_number","company","lead_source"],"call_config":{"call_time":{"call_start_time":"10:00","call_end_time":"18:30","timezone":"America/New_York"},"max_call_length":600,"idle_timeout_warning":8,"idle_timeout_end":20,"noise_filter_config":{"filter_noise":true,"noise_suppression_level":95},"voicemail":{"detect":true,"action":"end","retry":true},"background_audio_config":{"audio_id":"office_ambience","volume":0.35},"mute_during_intro":false}}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"afe7b1f2-4607-4759-b76d-034998097019":{"description":"Agent created successfully. Returns the agent id and the version_id of the version that was created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true,"uniqueKey":"success","typeLabel":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the created agent","example":"00000000-0000-4000-8000-000000000104","uniqueKey":"data.id","typeLabel":"string"},"version":{"type":"string","description":"The version slug of the agent","example":"v1","uniqueKey":"data.version","typeLabel":"string"},"version_id":{"type":"string","description":"ID of the version created for this agent. Pass this to the version-scoped APIs.","example":"00000000-0000-4000-8000-000000000105","uniqueKey":"data.version_id","typeLabel":"string"},"created_at":{"type":"string","format":"date-time","example":"2024-12-16T13:03:29.947147+00:00","uniqueKey":"data.created_at","typeLabel":"string\u003cdate-time>"}},"uniqueKey":"data","typeLabel":"object"},"message":{"type":"string","example":"Agent created successfully","uniqueKey":"message","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000104","version":"v1","version_id":"00000000-0000-4000-8000-000000000105","created_at":"2024-12-16T13:03:29.947147+00:00"},"message":"Agent created successfully"}}},"exampleType":"generated"}},"exampleType":"generated"},"2f1b2091-98de-4b7c-9d19-9a9a9b6a2a40":{"description":"Bad Request - Invalid parameters or voice does not support the selected language.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Voice does not support language 'en-US'","uniqueKey":"message","typeLabel":"string"},"code":{"type":"string","enum":["AGENT_NOT_FOUND","VERSION_NOT_FOUND","NO_ACTIVE_VERSION","INVALID_VOICE","VOICE_LANGUAGE_MISMATCH","INVALID_CUSTOM_VARIABLES","INTERNAL_ERROR"],"example":"VOICE_LANGUAGE_MISMATCH","uniqueKey":"code","typeLabel":"enum\u003cstring>"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"message":"Voice does not support language 'en-US'","code":"VOICE_LANGUAGE_MISMATCH"}}},"exampleType":"generated"}},"exampleType":"generated"},"2b9d3339-8fd8-41b6-8331-1f56317dd168":{"description":"Unauthorized - Invalid or missing API key.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Invalid credentials","uniqueKey":"message","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"message":"Invalid credentials"}}},"exampleType":"generated"}},"exampleType":"generated"},"be11201b-74c4-402a-81e5-55ffd9fbf823":{"description":"Validation Error - A field is missing, too long, or not one of the allowed values.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","uniqueKey":"message","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"message":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"8d4782e7-e89d-48a8-81fa-302bad6331cd":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","scopes":[],"schemeName":"ApiKeyAuth"}}},"servers":{"4e60091d-90fb-4aa4-8774-bd7b6fd296da":{"url":"https://prod-api.ringg.ai/ca/api/v0"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"X-API-KEY","scopes":[],"schemeName":"ApiKeyAuth"},"schema":{"title":"X-API-KEY","type":"string","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"ApiKeyAuth","name":"X-API-KEY"}],"title":"ApiKeyAuth"}]},"originalFileLocation":"api-reference/openapi.json"},"subdomain":"ringgai-0da73d20","siteName":"Ringg AI","title":"Create Agent - Ringg AI","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-13T11:53:26.759Z","originalFileLocation":"api-reference/agents/create-agent.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Create a single-prompt voice agent from a prompt, language, voice and first message, with optional call settings such as calling window and voicemail.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Ringg AI\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/ringgai-0da73d20/p7P0VdTXwvUPgoLE/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/ringgai-0da73d20/p7P0VdTXwvUPgoLE/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/ringgai-0da73d20/p7P0VdTXwvUPgoLE/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/ringgai-0da73d20/p7P0VdTXwvUPgoLE/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/ringgai-0da73d20/p7P0VdTXwvUPgoLE/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/ringgai-0da73d20/p7P0VdTXwvUPgoLE/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/ringgai-0da73d20/p7P0VdTXwvUPgoLE/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/ringgai-0da73d20/p7P0VdTXwvUPgoLE/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/ringgai-0da73d20/p7P0VdTXwvUPgoLE/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create Agent - Ringg AI\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create a single-prompt voice agent from a prompt, language, voice and first message, with optional call settings such as calling window and voicemail.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Ringg AI Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.ringg.ai/api-reference/agents/create-agent\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://ringgai-0da73d20.mintlify.site/_mintlify/api/og/v2?division=Agents\u0026amp;title=Create+Agent\u0026amp;description=Create+a+single-prompt+voice+agent+from+a+prompt%2C+language%2C+voice+and+first+message%2C+with+optional+call+settings+such+as+calling+window+and+voicemail.\u0026amp;theme=737b8671029ef070100737b1\u0026amp;signature=b3fce56d14166fa1b2b517fbb1ca7920fdaac36c59dab5829877a75e004946af\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create Agent - Ringg AI\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create a single-prompt voice agent from a prompt, language, voice and first message, with optional call settings such as calling window and voicemail.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://ringgai-0da73d20.mintlify.site/_mintlify/api/og/v2?division=Agents\u0026amp;title=Create+Agent\u0026amp;description=Create+a+single-prompt+voice+agent+from+a+prompt%2C+language%2C+voice+and+first+message%2C+with+optional+call+settings+such+as+calling+window+and+voicemail.\u0026amp;theme=737b8671029ef070100737b1\u0026amp;signature=b3fce56d14166fa1b2b517fbb1ca7920fdaac36c59dab5829877a75e004946af\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/ringgai-0da73d20/p7P0VdTXwvUPgoLE/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Ringg AI\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0A0A0B\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.ringg.ai/api-reference/agents/create-agent\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/agents/create-agent.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://www.ringg.ai/#organization\",\"name\":\"Ringg AI\",\"legalName\":\"Stoic AI Private Limited\",\"url\":\"https://www.ringg.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://assets.ringg.ai/images/logo/logo.svg\"},\"sameAs\":[\"https://x.com/ringg_ai\",\"https://www.linkedin.com/company/ringg\",\"https://www.youtube.com/@RinggAI\",\"https://www.instagram.com/ringg_ai\",\"https://discord.gg/YuEnb8Vsca\"]},{\"@type\":\"WebSite\",\"@id\":\"https://docs.ringg.ai#website\",\"name\":\"Ringg AI\",\"url\":\"https://docs.ringg.ai\",\"publisher\":{\"@id\":\"https://www.ringg.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.ringg.ai/api-reference/agents/create-agent#webpage\",\"url\":\"https://docs.ringg.ai/api-reference/agents/create-agent\",\"name\":\"Create Agent\",\"description\":\"Create a single-prompt voice agent from a prompt, language, voice and first message, with optional call settings such as calling window and voicemail.\",\"dateModified\":\"2026-10-13T11:53:26.759Z\",\"isPartOf\":{\"@id\":\"https://docs.ringg.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.ringg.ai/api-reference/agents/create-agent#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.ringg.ai/api-reference/agents/create-agent#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Agents\",\"item\":\"https://docs.ringg.ai/api-reference/agents/get-assistants\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create Agent\",\"item\":\"https://docs.ringg.ai/api-reference/agents/create-agent\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.ringg.ai/api-reference/agents/create-agent#apireference\",\"headline\":\"Create Agent\",\"name\":\"Create Agent\",\"description\":\"Create a single-prompt voice agent from a prompt, language, voice and first message, with optional call settings such as calling window and voicemail.\",\"url\":\"https://docs.ringg.ai/api-reference/agents/create-agent\",\"mainEntityOfPage\":{\"@id\":\"https://docs.ringg.ai/api-reference/agents/create-agent#webpage\"},\"dateModified\":\"2026-10-13T11:53:26.759Z\",\"publisher\":{\"@id\":\"https://www.ringg.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.ringg.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Ringg AI\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Ringg AI\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/agents/create-agent.md","siteName":"Ringg AI","nav":{"global":null,"tabs":[{"tab":"Get started","pages":[{"title":"Get started","href":"/get-started/introduction"}]},{"tab":"Documentation","pages":[{"title":"Documentation","href":"/documentation/introduction"}]},{"tab":"Analytics platform","pages":[{"title":"Analytics platform","href":"/analytics-platform/introduction"}]},{"tab":"API reference","groups":[{"group":"Introduction","icon":"book-open","pages":[{"title":"API quickstart","sidebarTitle":"Quickstart","href":"/api-reference/introduction/quickstart"},{"title":"Authentication","href":"/api-reference/introduction/authentication"},{"title":"API Overview","href":"/api-reference/introduction/api-overview"}]},{"group":"Agents","icon":"bot","pages":[{"openapi":"get /agent/all","title":"List Agents","href":"/api-reference/agents/get-assistants"},{"openapi":"get /agent/{agent_id}","description":"Get one agent's configuration by its agent_id to confirm the agent exists in this workspace and check its name, type and settings before you call with it.","title":"Get Agent","href":"/api-reference/agents/get-assistant-by-id"},{"openapi":"post /public/agent","title":"Create Agent","href":"/api-reference/agents/create-agent"},{"openapi":"patch /agent/v1","description":"Change one setting on an existing agent per request, such as its prompt, voice, knowledge base, inbound number or webhook subscriptions, by operation name.","title":"Edit Agent Settings","href":"/api-reference/agents/edit-assistant"},{"openapi":"get /agent/voices","title":"List Voices","href":"/api-reference/agents/get-assistant-voices"}]},{"group":"Inventory","icon":"package","pages":[{"group":"Knowledge bases","expanded":true,"pages":[{"openapi":"post /external/kb","title":"Create Knowledge Base","href":"/api-reference/inventory/knowledge-bases/create-knowledge-base"},{"openapi":"get /external/kb/all","title":"Get All Knowledge Bases","href":"/api-reference/inventory/knowledge-bases/get-all-knowledge-bases"},{"openapi":"get /external/kb/{kb_id}","title":"Get Knowledge Base by ID","href":"/api-reference/inventory/knowledge-bases/get-knowledge-base-by-id"},{"openapi":"patch /external/kb","title":"Edit Knowledge Base","href":"/api-reference/inventory/knowledge-bases/edit-knowledge-base"},{"openapi":"delete /external/kb/{kb_id}","title":"Delete Knowledge Base","href":"/api-reference/inventory/knowledge-bases/delete-knowledge-base"}]},{"group":"Numbers","expanded":true,"pages":[{"openapi":"get /workspace/numbers","title":"Get Workspace Numbers","href":"/api-reference/inventory/numbers/get-workspace-numbers"}]}]},{"group":"Calling","icon":"phone","pages":[{"group":"Individual calls","expanded":true,"pages":[{"openapi":"post /calling/outbound/individual","title":"Initiate Individual Call","href":"/api-reference/calling/individual-calls/initiate-individual-call"},{"openapi":"post /calling/v2/outbound/individual","title":"Initiate Individual Call (Number Pool)","href":"/api-reference/calling/individual-calls/initiate-individual-call-v2"},{"title":"Terminate Calls by Call IDs","sidebarTitle":"Stop calls by ID","api":"PATCH /campaign/terminate","href":"/api-reference/calling/individual-calls/stop-calls-by-id"},{"title":"Terminate Calls by Numbers","sidebarTitle":"Stop calls to numbers","api":"PATCH /campaign/terminate","href":"/api-reference/calling/individual-calls/stop-calls-to-numbers"},{"title":"Terminate All Calls by Agent ID","sidebarTitle":"Stop an agent's calls","api":"PATCH /campaign/terminate","href":"/api-reference/calling/individual-calls/stop-agent-calls"}]},{"group":"Campaigns","expanded":true,"pages":[{"openapi":"post /campaign/save","title":"Upload Campaign Contact List","href":"/api-reference/calling/campaigns/upload-campaign-contact-list"},{"openapi":"post /campaign/start","title":"Start Campaign","href":"/api-reference/calling/campaigns/start-campaign"},{"openapi":"post /campaign/v2/start","title":"Start Campaign (Number Pool)","href":"/api-reference/calling/campaigns/start-campaign-v2"},{"openapi":"get /campaign/all","title":"Get All Campaigns","href":"/api-reference/calling/campaigns/get-all-campaigns"},{"title":"Terminate Calls by Campaign ID","sidebarTitle":"Stop a campaign","api":"PATCH /campaign/terminate","href":"/api-reference/calling/campaigns/stop-campaign"},{"title":"Terminate Calls by Campaign Numbers","sidebarTitle":"Stop numbers in a campaign","api":"PATCH /campaign/terminate","href":"/api-reference/calling/campaigns/stop-campaign-numbers"}]},{"group":"Large campaigns","tag":"BETA","expanded":true,"pages":[{"title":"Upload large campaign CSV (Beta)","openapi":"post /campaign/upload-csv","href":"/api-reference/calling/large-campaigns/upload-large-campaign-csv"},{"title":"Get large campaign upload status (Beta)","openapi":"get /campaign/upload-status/{bulk_list_id}","href":"/api-reference/calling/large-campaigns/get-large-campaign-upload-status"},{"title":"Check large campaign balance (Beta)","openapi":"post /campaign/check-balance/{bulk_list_id}","href":"/api-reference/calling/large-campaigns/check-large-campaign-balance"},{"title":"Make large campaign calls async (Beta)","openapi":"post /campaign/make-call-async","href":"/api-reference/calling/large-campaigns/make-large-campaign-calls-async"}]}]},{"group":"Monitoring","icon":"chart-column","pages":[{"group":"Call history","expanded":true,"pages":[{"openapi":"get /calling/history","title":"Get Call History","href":"/api-reference/monitoring/call-history/get-call-history"},{"openapi":"get /calling/call-details","title":"Get Call Details","href":"/api-reference/monitoring/call-history/get-call-details"},{"openapi":"post /calling/history/download","title":"Download Call History","href":"/api-reference/monitoring/call-history/download-call-history"}]},{"group":"Analytics","tag":"NEW","expanded":true,"pages":[{"openapi":"get /analytics/v4/volume-graph","title":"Get Volume Analytics","href":"/api-reference/monitoring/analytics/get-volume-analytics"},{"openapi":"get /analytics/v4/connectivity","title":"Get Connectivity Analytics","href":"/api-reference/monitoring/analytics/get-connectivity-analytics"},{"openapi":"get /analytics/v4/agent-performance","title":"Get Agent Performance","href":"/api-reference/monitoring/analytics/get-agent-performance"},{"openapi":"get /analytics/v4/latency-trend","title":"Get Latency Trend","href":"/api-reference/monitoring/analytics/get-latency-trend"},{"openapi":"get /analytics/v4/concurrency-trend","title":"Get Concurrency Trend","href":"/api-reference/monitoring/analytics/get-concurrency-trend"},{"openapi":"get /analytics/v4/cohort/dimensions","title":"Get Cohort Dimensions","href":"/api-reference/monitoring/analytics/get-cohort-dimensions"},{"openapi":"get /analytics/v4/cohort/values","title":"Get Cohort Values","href":"/api-reference/monitoring/analytics/get-cohort-values"},{"openapi":"get /analytics/v4/cohort/breakdown","title":"Get Cohort Breakdown","href":"/api-reference/monitoring/analytics/get-cohort-breakdown"},{"openapi":"get /analytics/v4/campaigns","title":"Get Active Campaigns","href":"/api-reference/monitoring/analytics/get-active-campaigns"},{"openapi":"get /analytics/v4/data-freshness","title":"Get Data Freshness","href":"/api-reference/monitoring/analytics/get-data-freshness"},{"openapi":"get /analytics/v4/chat-analytics","title":"Get Chat Analytics","href":"/api-reference/monitoring/analytics/get-chat-analytics"}]}]},{"group":"Account","icon":"settings","pages":[{"openapi":"get /workspace","title":"Get Workspace Info","href":"/api-reference/account/get-workspace-info"},{"openapi":"get /workspace/users","title":"List Workspace Users","href":"/api-reference/account/list-workspace-users"},{"openapi":"get /workspace/all","title":"Get All User Workspaces","href":"/api-reference/account/get-all-user-workspaces"},{"group":"Ringg Spaces","expanded":true,"pages":[{"openapi":"post /workspace/sub","title":"Create Ringg Space","href":"/api-reference/account/ringg-spaces/create-sub-workspace"},{"openapi":"get /workspace/sub","title":"Get Ringg Spaces","href":"/api-reference/account/ringg-spaces/get-sub-workspaces"},{"openapi":"get /workspace/sub/members","title":"List Family Members","href":"/api-reference/account/ringg-spaces/list-family-members"},{"openapi":"patch /workspace/sub/{sub_workspace_id}/concurrency","title":"Allocate Concurrency to a Ringg Space","href":"/api-reference/account/ringg-spaces/allocate-concurrency"},{"openapi":"patch /workspace/sub/credit-limits","title":"Reallocate Credit Limits","href":"/api-reference/account/ringg-spaces/reallocate-credit-limits"},{"openapi":"patch /workspace/sub/credit-balances","title":"Reallocate Credit Balances","href":"/api-reference/account/ringg-spaces/reallocate-credit-balances"}]}]}]},{"tab":"Resources","menu":[{"item":"MCP server","description":"Let Claude, ChatGPT or Cursor work in your workspace, or search these docs","pages":[{"title":"MCP server","href":"/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants"}]},{"item":"Learn","description":"Lessons that build a payment-reminder system end to end","pages":[{"title":"Learn","href":"/resources/learn/all-lessons"}]},{"item":"Security","description":"How Ringg protects your data, and what to do on your side","pages":[{"title":"Security","href":"/resources/security/security"}]},{"item":"Changelog","description":"New features, API changes and new guides","pages":[{"title":"Changelog","href":"/resources/changelog/changelog"}]}],"pages":[{"title":"Resources","href":"/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants"}]}]},"basePath":"","title":"Create Agent - Ringg AI","buildId":"dpl_596ePT575z4qnAFksq1biRW97aLY","deploymentId":"dpl_596ePT575z4qnAFksq1biRW97aLY","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-C9Wu0MeN.js","utils-jWgu-6Qf.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-DBD8f9qn.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-BGuX1ui5.js","snippetPresets-Evy63nQB.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-BQHO1lnV.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-B6C8m-t_.js","shallow-BG4cT0fH.js","getApiPlaygroundDisplay-CgEPrE-D.js","CodeSnippet-CU8JyZ9N.js","CodeSnippets-BnxHU32T.js","Page-D6S0Yh6q.js","getPastedJson-CwiYOonh.js","icon-DYDpWmDf.js","MethodPill-C-J-l7_c.js","DuplicateIcon-B6ARwg9w.js","createIcon-Dsv4MtDq.js","DynamicMarkdown-CtasenyM.js","SectionHeading-YNcgYwjB.js","axios-vUo_bRtp.js","Markdown-CwLx6PAg.js","clsx-C3kuh_dz.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-CmKHfscc.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-U3mI6Ljh.js"]}