Skip to main content
POST
Create Agent
Create a new assistant programmatically. This endpoint is best for productized setup flows where your application creates Ringg assistants from templates or customer-provided configuration.

​
When to use

  • Onboard customers into a pre-defined assistant template.
  • Create one assistant per team, location, or campaign type.
  • Provision assistants from your own admin backend.

​
Call settings

Pass call_config to fix the assistant’s call behaviour at creation time instead of following up in the dashboard. Every field is optional — omit the block, or any key in it, to accept the default.

​
Calling window and timezones

Outside the window an outbound call is not dialled immediately, and retries are pushed to the next opening. The window is per assistant; a campaign or an individual call can override it. Any IANA timezone is supported — this is not India-only. Asia/Kolkata is merely the default when you omit it.
A window may cross midnight — "call_start_time": "22:00" with "call_end_time": "06:00" is a valid overnight window.
Always use the full Region/City form. Abbreviations behave in two different, equally unhelpful ways:
  • IST, PST and CST are rejected — they are not IANA zones.
  • EST, MST, HST and GMT are accepted, and are a trap. They are fixed-offset zones that never observe daylight saving, so an assistant on EST runs an hour behind actual New York time for the ~8 months that America/New_York is on EDT. Use America/New_York, not EST.
Times must be zero-padded 24-hour: send 09:00, not 9:00 or 9:00 AM. Both the window and the timezone are validated when you create the assistant, so a bad value fails the create call rather than every call the assistant later tries to place.
scheduled_at is not accepted inside call_time here. It schedules one specific call, so on an assistant it would pin every call that assistant ever places to the same timestamp. Pass it per call, on the individual call endpoint’s own call_config.call_time.
idle_timeout_warning must be less than idle_timeout_end, otherwise the request is rejected. If the warning fires at or after the hangup, the check-in can never be spoken. Use 0 to disable the check-in and keep only the hangup.
Two easy ones to get backwards:
  • background_audio_config.volume is a fraction between 0.0 and 1.0, not a percentage. 50 is rejected; send 0.5.
  • mute_during_intro reads as the opposite of “interruptible”. true (the default) means the caller cannot cut in over the intro message.
call_config is accepted on create only. To change these settings afterwards, use the dashboard — the edit assistant endpoint does not accept them yet, and they are not returned by get assistant.

​
Integration notes

  • For most teams, creating the assistant in the dashboard first is simpler.
  • Store the returned agent_id; it is required for calls and campaigns.
  • Keep prompts concise and make every variable explicit in custom_args_values or campaign CSV mappings.

​
After creation

Use get assistants to confirm the assistant is visible, then test with one individual call before using campaigns.

Headers

​
X-API-KEY
string
required

(Required) Your Ringg AI API key.

Example:

"7251cb4b-3373-43a4-844c-b27a1d45e0c9"

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-IN,
hi-IN,
ta-IN,
te-IN,
bn-IN,
mr-IN,
kn-IN,
ka-IN
Example:

"en-IN"

​
voice_id
string<uuid>
required

(Required) Internal AgentVoice ID (UUID). Get available voices from the Get Assistant Voices endpoint.

Example:

"02ad256b-092b-4048-bea0-5af46a452b98"

​
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-IN,
hi-IN,
ta-IN,
te-IN,
bn-IN,
mr-IN,
kn-IN,
ka-IN
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"