Create Agent

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: <x-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": "02ad256b-092b-4048-bea0-5af46a452b98",
  "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"
  ]
}
'

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": "02ad256b-092b-4048-bea0-5af46a452b98",
    "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"]
}
headers = {
    "X-API-KEY": "<x-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': '<x-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: '02ad256b-092b-4048-bea0-5af46a452b98',
    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']
  })
};

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));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://prod-api.ringg.ai/ca/api/v0/public/agent",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => '02ad256b-092b-4048-bea0-5af46a452b98',
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://prod-api.ringg.ai/ca/api/v0/public/agent"

	payload := strings.NewReader("{\n  \"agent_name\": \"My Sales Agent\",\n  \"introduction_and_objective\": \"You are a customer support agent for Acme Corp.\",\n  \"response_guidelines\": \"Be polite, helpful, and concise. Always confirm understanding.\",\n  \"task\": \"Help customers with their orders and answer product questions.\",\n  \"primary_language\": \"en-IN\",\n  \"voice_id\": \"02ad256b-092b-4048-bea0-5af46a452b98\",\n  \"intro_message\": \"Hello, this is Sarah from Acme Corp. How can I assist you today?\",\n  \"faq\": \"Q: What are your hours? A: We are open 9am-6pm IST.\",\n  \"sample_conversations\": \"User: Hi\\nAgent: Hello! How can I help you today?\",\n  \"secondary_language\": \"hi-IN\",\n  \"agent_type\": \"outbound\",\n  \"custom_variables\": [\n    \"callee_name\",\n    \"mobile_number\",\n    \"company\",\n    \"lead_source\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://prod-api.ringg.ai/ca/api/v0/public/agent")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_name\": \"My Sales Agent\",\n  \"introduction_and_objective\": \"You are a customer support agent for Acme Corp.\",\n  \"response_guidelines\": \"Be polite, helpful, and concise. Always confirm understanding.\",\n  \"task\": \"Help customers with their orders and answer product questions.\",\n  \"primary_language\": \"en-IN\",\n  \"voice_id\": \"02ad256b-092b-4048-bea0-5af46a452b98\",\n  \"intro_message\": \"Hello, this is Sarah from Acme Corp. How can I assist you today?\",\n  \"faq\": \"Q: What are your hours? A: We are open 9am-6pm IST.\",\n  \"sample_conversations\": \"User: Hi\\nAgent: Hello! How can I help you today?\",\n  \"secondary_language\": \"hi-IN\",\n  \"agent_type\": \"outbound\",\n  \"custom_variables\": [\n    \"callee_name\",\n    \"mobile_number\",\n    \"company\",\n    \"lead_source\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.ringg.ai/ca/api/v0/public/agent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_name\": \"My Sales Agent\",\n  \"introduction_and_objective\": \"You are a customer support agent for Acme Corp.\",\n  \"response_guidelines\": \"Be polite, helpful, and concise. Always confirm understanding.\",\n  \"task\": \"Help customers with their orders and answer product questions.\",\n  \"primary_language\": \"en-IN\",\n  \"voice_id\": \"02ad256b-092b-4048-bea0-5af46a452b98\",\n  \"intro_message\": \"Hello, this is Sarah from Acme Corp. How can I assist you today?\",\n  \"faq\": \"Q: What are your hours? A: We are open 9am-6pm IST.\",\n  \"sample_conversations\": \"User: Hi\\nAgent: Hello! How can I help you today?\",\n  \"secondary_language\": \"hi-IN\",\n  \"agent_type\": \"outbound\",\n  \"custom_variables\": [\n    \"callee_name\",\n    \"mobile_number\",\n    \"company\",\n    \"lead_source\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "id": "edd618d3-f473-4ac1-b5fa-f1a3981666ff",
    "version": "v1",
    "created_at": "2024-12-16T13:03:29.947147+00:00"
  },
  "message": "Agent created successfully"
}

{
  "success": false,
  "error": {
    "code": "VOICE_LANGUAGE_MISMATCH",
    "message": "Voice does not support language 'en-US'"
  }
}

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.

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:

[
  "callee_name",
  "mobile_number",
  "company",
  "lead_source"
]

Response

Agent created successfully.

success

boolean

Example:

true

data

object

Show child attributes

message

string

Example:

"Agent created successfully"

Create Knowledge BaseCreates a new non-deterministic knowledge base. Rate limit: 10 requests per hour per workspace. File size limit: 2 MB per file, 5 MB total. Maximum 10 files and 20 URLs per request.

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: <x-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": "02ad256b-092b-4048-bea0-5af46a452b98",
  "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"
  ]
}
'

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": "02ad256b-092b-4048-bea0-5af46a452b98",
    "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"]
}
headers = {
    "X-API-KEY": "<x-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': '<x-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: '02ad256b-092b-4048-bea0-5af46a452b98',
    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']
  })
};

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));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://prod-api.ringg.ai/ca/api/v0/public/agent",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => '02ad256b-092b-4048-bea0-5af46a452b98',
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://prod-api.ringg.ai/ca/api/v0/public/agent"

	payload := strings.NewReader("{\n  \"agent_name\": \"My Sales Agent\",\n  \"introduction_and_objective\": \"You are a customer support agent for Acme Corp.\",\n  \"response_guidelines\": \"Be polite, helpful, and concise. Always confirm understanding.\",\n  \"task\": \"Help customers with their orders and answer product questions.\",\n  \"primary_language\": \"en-IN\",\n  \"voice_id\": \"02ad256b-092b-4048-bea0-5af46a452b98\",\n  \"intro_message\": \"Hello, this is Sarah from Acme Corp. How can I assist you today?\",\n  \"faq\": \"Q: What are your hours? A: We are open 9am-6pm IST.\",\n  \"sample_conversations\": \"User: Hi\\nAgent: Hello! How can I help you today?\",\n  \"secondary_language\": \"hi-IN\",\n  \"agent_type\": \"outbound\",\n  \"custom_variables\": [\n    \"callee_name\",\n    \"mobile_number\",\n    \"company\",\n    \"lead_source\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://prod-api.ringg.ai/ca/api/v0/public/agent")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_name\": \"My Sales Agent\",\n  \"introduction_and_objective\": \"You are a customer support agent for Acme Corp.\",\n  \"response_guidelines\": \"Be polite, helpful, and concise. Always confirm understanding.\",\n  \"task\": \"Help customers with their orders and answer product questions.\",\n  \"primary_language\": \"en-IN\",\n  \"voice_id\": \"02ad256b-092b-4048-bea0-5af46a452b98\",\n  \"intro_message\": \"Hello, this is Sarah from Acme Corp. How can I assist you today?\",\n  \"faq\": \"Q: What are your hours? A: We are open 9am-6pm IST.\",\n  \"sample_conversations\": \"User: Hi\\nAgent: Hello! How can I help you today?\",\n  \"secondary_language\": \"hi-IN\",\n  \"agent_type\": \"outbound\",\n  \"custom_variables\": [\n    \"callee_name\",\n    \"mobile_number\",\n    \"company\",\n    \"lead_source\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.ringg.ai/ca/api/v0/public/agent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_name\": \"My Sales Agent\",\n  \"introduction_and_objective\": \"You are a customer support agent for Acme Corp.\",\n  \"response_guidelines\": \"Be polite, helpful, and concise. Always confirm understanding.\",\n  \"task\": \"Help customers with their orders and answer product questions.\",\n  \"primary_language\": \"en-IN\",\n  \"voice_id\": \"02ad256b-092b-4048-bea0-5af46a452b98\",\n  \"intro_message\": \"Hello, this is Sarah from Acme Corp. How can I assist you today?\",\n  \"faq\": \"Q: What are your hours? A: We are open 9am-6pm IST.\",\n  \"sample_conversations\": \"User: Hi\\nAgent: Hello! How can I help you today?\",\n  \"secondary_language\": \"hi-IN\",\n  \"agent_type\": \"outbound\",\n  \"custom_variables\": [\n    \"callee_name\",\n    \"mobile_number\",\n    \"company\",\n    \"lead_source\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "id": "edd618d3-f473-4ac1-b5fa-f1a3981666ff",
    "version": "v1",
    "created_at": "2024-12-16T13:03:29.947147+00:00"
  },
  "message": "Agent created successfully"
}

{
  "success": false,
  "error": {
    "code": "VOICE_LANGUAGE_MISMATCH",
    "message": "Voice does not support language 'en-US'"
  }
}

Get Started

API Reference

Webhooks Setup

Telephony Integration

When to use

Integration notes

After creation

Headers

Body

Response

​When to use

​Integration notes

​After creation

Headers

Body

Response

When to use

Integration notes

After creation