Skip to main content
POST
Create Agent
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.

​
Prompt sections

The prompt fields become the agent’s prompt sections, in this order: 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.
Get voice_id from List 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, 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.

Authorizations

​
X-API-KEY
string
header
required

Headers

​
X-API-KEY
string
required

(Required) Your Ringg AI API key.

Example:

"rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Body

application/json
​
agent_name
string
required

(Required) Name of the agent

Maximum string length: 100
Example:

"My Sales Agent"

​
introduction_and_objective
string
required

(Required) Introduction and objective of the agent

Maximum string length: 2000
Example:

"You are a customer support agent for Acme Corp."

​
response_guidelines
string
required

(Required) Guidelines for how the agent should respond

Maximum string length: 3000
Example:

"Be polite, helpful, and concise. Always confirm understanding."

​
task
string
required

(Required) The task the agent should perform

Maximum string length: 1500
Example:

"Help customers with their orders and answer product questions."

​
primary_language
enum<string>
required

(Required) Primary language locale for the agent

Available options:
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
Example:

"en-IN"

​
voice_id
string<uuid>
required

(Required) Voice ID (UUID). Get available voices from the List Voices endpoint.

Example:

"00000000-0000-4000-8000-00000000010e"

​
intro_message
string
required

(Required) Introduction message the agent will speak when the call starts

Maximum string length: 500
Example:

"Hello, this is Sarah from Acme Corp. How can I assist you today?"

​
faq
string

(Optional) FAQ content for the agent

Maximum string length: 5000
Example:

"Q: What are your hours? A: We are open 9am-6pm IST."

​
sample_conversations
string

(Optional) Example conversations for the agent. Use \n for newlines between turns.

Maximum string length: 5000
Example:

"User: Hi\nAgent: Hello! How can I help you today?"

​
secondary_language
enum<string>

(Optional) Secondary language locale for the agent

Available options:
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
Example:

"hi-IN"

​
agent_type
enum<string>
default:outbound

(Required) Type of agent. Defaults to outbound.

Available options:
inbound,
outbound,
outbound_inbound
Example:

"outbound"

​
custom_variables
string[]

(Optional) Custom variables for the agent. For outbound agents, callee_name and mobile_number are always included automatically.

Example:
​
call_config
object

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

Example:

Response

Agent created successfully. Returns the agent id and the version_id of the version that was created.

​
success
boolean
Example:

true

​
data
object
​
message
string
Example:

"Agent created successfully"