> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent 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
> Create a single-prompt voice agent from a prompt, language, voice and first message, with optional call settings such as calling window and voicemail.
# Create Agent
export const RelatedTopics = ({items}) =>
;
Use it when your product sets up agents for its own customers from a template; for a one-off agent, the [dashboard](/documentation/build-agents/agents/create-an-agent) 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`.
## Prompt sections
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 settings
`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` |
```json theme={null}
{
"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
}
}
```
Get `voice_id` from [List voices](/api-reference/agents/get-assistant-voices).
### Calling window
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`.
### Validation rules
The request fails, rather than the agent's later calls, when:
* a time is not zero-padded 24-hour (`09:00` works, `9:00` and `9:00 AM` do not);
* `idle_timeout_warning` is not less than `idle_timeout_end`;
* `background_audio_config.volume` is outside `0.0`–`1.0` (send `0.5`, not `50`).
## Notes
* To change call settings after creation, use `edit_call_config` on [Edit agent settings](/api-reference/agents/edit-assistant), or [Call settings](/documentation/build-agents/customize-agent-behaviour/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](/api-reference/calling/individual-calls/initiate-individual-call).
## OpenAPI
````yaml post /public/agent
openapi: 3.0.0
info:
title: Ringg AI API Documentation
description: >-
The Ringg AI REST API. Base URL https://prod-api.ringg.ai/ca/api/v0; send
your workspace API key in the X-API-KEY header from server-side code only.
Requests and responses are JSON.
version: 2.0.0
contact:
name: Ringg AI support
email: admin@ringg.ai
url: https://docs.ringg.ai
servers:
- url: https://prod-api.ringg.ai/ca/api/v0
security: []
tags:
- name: workspace
description: Endpoints for managing your workspace.
- name: agent
description: Endpoints for managing agents.
- name: calling
description: Endpoints for making and managing calls.
- name: campaign
description: Endpoints for managing campaigns.
- name: analytics
description: Endpoints for accessing call analytics and performance metrics.
- name: termination
description: Endpoints for terminating active calls using different methods.
- name: knowledgebase
description: Endpoints for managing knowledge bases.
paths:
/public/agent:
post:
tags:
- agent
summary: Create Agent
description: >-
Creates a new AI agent with the specified configuration. The agent will
be created with a single prompt-based flow.
operationId: createAgent
parameters:
- name: X-API-KEY
in: header
description: (Required) Your Ringg AI API key.
required: true
schema:
type: string
example: rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
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
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.
response_guidelines:
type: string
maxLength: 3000
description: (Required) Guidelines for how the agent should respond
example: >-
Be polite, helpful, and concise. Always confirm
understanding.
task:
type: string
maxLength: 1500
description: (Required) The task the agent should perform
example: >-
Help customers with their orders and answer product
questions.
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.'
sample_conversations:
type: string
maxLength: 5000
description: >-
(Optional) Example conversations for the agent. Use \n for
newlines between turns.
example: |-
User: Hi
Agent: Hello! How can I help you today?
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
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
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
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?
agent_type:
type: string
enum:
- inbound
- outbound
- outbound_inbound
default: outbound
description: (Required) Type of agent. Defaults to outbound.
example: outbound
custom_variables:
type: array
items:
type: 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
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'
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'
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
example:
call_start_time: '10:00'
call_end_time: '18:30'
timezone: America/New_York
max_call_length:
type: integer
minimum: 10
maximum: 3600
description: 'Hard cap on call duration in seconds (default: 240).'
default: 240
example: 600
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
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
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
noise_suppression_level:
type: integer
minimum: 0
maximum: 100
description: 'Suppression strength, 0-100 (default: 80).'
default: 80
example: 95
example:
filter_noise: true
noise_suppression_level: 95
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
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
retry:
type: boolean
description: >-
Re-queue the call for a later attempt after hitting
voicemail (default: true).
default: true
example: true
static_message:
type: string
nullable: true
description: >-
Spoken verbatim when action is static_message.
Ignored otherwise.
example: Sorry we missed you, please call us back.
example:
detect: true
action: end
retry: true
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
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
mixing:
type: boolean
description: >-
Mix the track under the agent's speech (default:
true).
default: true
example: true
loop:
type: boolean
description: 'Repeat the track for the whole call (default: true).'
default: true
example: true
example:
audio_id: office_ambience
volume: 0.35
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
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
responses:
'200':
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
data:
type: object
properties:
id:
type: string
description: The unique ID of the created agent
example: 00000000-0000-4000-8000-000000000104
version:
type: string
description: The version slug of the agent
example: v1
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
created_at:
type: string
format: date-time
example: '2024-12-16T13:03:29.947147+00:00'
message:
type: string
example: Agent created successfully
'400':
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'
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
'401':
description: Unauthorized - Invalid or missing API key.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Invalid credentials
'422':
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
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.