curl -X POST https://api.ringyo.ai/v1/agents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Sales Assistant",
"system_prompt": "You are Sarah, a friendly sales assistant for Acme Corp. Your goal is to qualify leads and schedule demos. Be professional but warm. Ask about their current challenges and how Acme can help.",
"voice_id": "sarah-professional",
"first_message": "Hi! This is Sarah from Acme Corp. I'\''m reaching out to see if we can help with your business needs. Do you have a moment to chat?",
"language": "en-US",
"model": "gpt-4o"
}'
const response = await fetch('https://api.ringyo.ai/v1/agents', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Sales Assistant',
system_prompt: `You are Sarah, a friendly sales assistant for Acme Corp.
Your goal is to qualify leads and schedule demos. Be professional but warm.`,
voice_id: 'sarah-professional',
first_message: "Hi! This is Sarah from Acme Corp...",
language: 'en-US',
model: 'gpt-4o'
})
});
const agent = await response.json();
import requests
response = requests.post(
'https://api.ringyo.ai/v1/agents',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'name': 'Sales Assistant',
'system_prompt': 'You are Sarah, a friendly sales assistant...',
'voice_id': 'sarah-professional',
'first_message': 'Hi! This is Sarah from Acme Corp...',
'language': 'en-US',
'model': 'gpt-4o'
}
)
agent = response.json()
{
"id": "agent_abc123",
"name": "Sales Assistant",
"system_prompt": "You are Sarah, a friendly sales assistant...",
"voice_id": "sarah-professional",
"first_message": "Hi! This is Sarah from Acme Corp...",
"language": "en-US",
"model": "gpt-4o",
"temperature": 0.7,
"max_tokens": 150,
"interruption_threshold": 0.5,
"end_call_phrases": [],
"status": "active",
"metadata": {},
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
{
"error": {
"code": "invalid_voice_id",
"message": "The specified voice_id does not exist"
}
}
{
"error": {
"code": "agent_limit_reached",
"message": "You have reached the maximum number of agents for your plan"
}
}
Agents
Create Agent
Create a new AI voice agent
POST
/
v1
/
agents
curl -X POST https://api.ringyo.ai/v1/agents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Sales Assistant",
"system_prompt": "You are Sarah, a friendly sales assistant for Acme Corp. Your goal is to qualify leads and schedule demos. Be professional but warm. Ask about their current challenges and how Acme can help.",
"voice_id": "sarah-professional",
"first_message": "Hi! This is Sarah from Acme Corp. I'\''m reaching out to see if we can help with your business needs. Do you have a moment to chat?",
"language": "en-US",
"model": "gpt-4o"
}'
const response = await fetch('https://api.ringyo.ai/v1/agents', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Sales Assistant',
system_prompt: `You are Sarah, a friendly sales assistant for Acme Corp.
Your goal is to qualify leads and schedule demos. Be professional but warm.`,
voice_id: 'sarah-professional',
first_message: "Hi! This is Sarah from Acme Corp...",
language: 'en-US',
model: 'gpt-4o'
})
});
const agent = await response.json();
import requests
response = requests.post(
'https://api.ringyo.ai/v1/agents',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'name': 'Sales Assistant',
'system_prompt': 'You are Sarah, a friendly sales assistant...',
'voice_id': 'sarah-professional',
'first_message': 'Hi! This is Sarah from Acme Corp...',
'language': 'en-US',
'model': 'gpt-4o'
}
)
agent = response.json()
{
"id": "agent_abc123",
"name": "Sales Assistant",
"system_prompt": "You are Sarah, a friendly sales assistant...",
"voice_id": "sarah-professional",
"first_message": "Hi! This is Sarah from Acme Corp...",
"language": "en-US",
"model": "gpt-4o",
"temperature": 0.7,
"max_tokens": 150,
"interruption_threshold": 0.5,
"end_call_phrases": [],
"status": "active",
"metadata": {},
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
{
"error": {
"code": "invalid_voice_id",
"message": "The specified voice_id does not exist"
}
}
{
"error": {
"code": "agent_limit_reached",
"message": "You have reached the maximum number of agents for your plan"
}
}
Request
Create a new AI voice agent with custom personality, voice, and behavior settings.Headers
string
required
Bearer token for authentication. Format:
Bearer YOUR_API_KEYstring
required
Must be
application/jsonBody Parameters
string
required
A friendly name for the agent (e.g., “Sales Assistant”)
string
required
The instructions defining the agent’s personality, goals, and behavior
string
required
The voice to use for the agent. See available voices.
string
The greeting message the agent says when the call connects
string
default:"en-US"
Primary language for the agent (e.g.,
en-US, es-ES, fr-FR)string
default:"gpt-4o"
The LLM to use:
gpt-4o, gpt-4o-mini, claude-3-sonnetnumber
default:"0.7"
Creativity level (0.0-1.0). Lower = more focused, higher = more creative.
integer
default:"150"
Maximum tokens per response (affects verbosity)
number
default:"0.5"
How easily the user can interrupt (0.0-1.0). Higher = easier to interrupt.
array
Phrases that will end the call (e.g.,
["goodbye", "that's all"])object
Custom key-value pairs for your reference
Response
string
Unique identifier for the agent
string
The agent’s name
string
The voice ID
string
Agent status:
active, inactivestring
ISO 8601 timestamp
curl -X POST https://api.ringyo.ai/v1/agents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Sales Assistant",
"system_prompt": "You are Sarah, a friendly sales assistant for Acme Corp. Your goal is to qualify leads and schedule demos. Be professional but warm. Ask about their current challenges and how Acme can help.",
"voice_id": "sarah-professional",
"first_message": "Hi! This is Sarah from Acme Corp. I'\''m reaching out to see if we can help with your business needs. Do you have a moment to chat?",
"language": "en-US",
"model": "gpt-4o"
}'
const response = await fetch('https://api.ringyo.ai/v1/agents', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Sales Assistant',
system_prompt: `You are Sarah, a friendly sales assistant for Acme Corp.
Your goal is to qualify leads and schedule demos. Be professional but warm.`,
voice_id: 'sarah-professional',
first_message: "Hi! This is Sarah from Acme Corp...",
language: 'en-US',
model: 'gpt-4o'
})
});
const agent = await response.json();
import requests
response = requests.post(
'https://api.ringyo.ai/v1/agents',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'name': 'Sales Assistant',
'system_prompt': 'You are Sarah, a friendly sales assistant...',
'voice_id': 'sarah-professional',
'first_message': 'Hi! This is Sarah from Acme Corp...',
'language': 'en-US',
'model': 'gpt-4o'
}
)
agent = response.json()
{
"id": "agent_abc123",
"name": "Sales Assistant",
"system_prompt": "You are Sarah, a friendly sales assistant...",
"voice_id": "sarah-professional",
"first_message": "Hi! This is Sarah from Acme Corp...",
"language": "en-US",
"model": "gpt-4o",
"temperature": 0.7,
"max_tokens": 150,
"interruption_threshold": 0.5,
"end_call_phrases": [],
"status": "active",
"metadata": {},
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
{
"error": {
"code": "invalid_voice_id",
"message": "The specified voice_id does not exist"
}
}
{
"error": {
"code": "agent_limit_reached",
"message": "You have reached the maximum number of agents for your plan"
}
}
Error Codes
| Code | Description |
|---|---|
invalid_voice_id | The specified voice does not exist |
agent_limit_reached | Your plan’s agent limit has been reached |
invalid_system_prompt | System prompt is too long or contains invalid content |
invalid_language | The specified language is not supported |