Create a voice, web or WhatsApp agent in Ringg AI

For a template, Ringg writes the first prompt from the company and call details you enter; the API creates single-prompt voice agents only. Not sure which type you need? See Build each type.

Before you start

A Ringg workspace

An API key

Optional: only for the API path below.

In the dashboard

Sidebar → Assistants → Create agent. The video shows the whole flow, from the Agents page to the editor.

Creating a single-prompt agent in the dashboard

Pick a channel

On the Agents page, click Create agent. In the Create Assistant dialog, choose a tab: Outbound, Inbound, Webcall or WhatsApp (which one?). The templates below change with the tab. A WhatsApp agent also needs a connected WhatsApp Business number; follow Create a WhatsApp agent for that path.

Pick a starting point

The left rail has Blank Template (selected by default), Select industry templates (Logistics, Healthcare, Financial, Education, HR & Recruitment, eCommerce) and Plugins → Zapier.With Blank Template selected, the dialog shows two groups:

Create from scratch: a general single-prompt template for the chosen channel, and Multi Prompt (“Create assistant from scratch for complex workflows.”), which is not offered on the WhatsApp tab.
Choose from templates: ready-made templates for the channel. Some have a Play Demo button that plays a sample call.

Pick an industry to see only its templates, or Zapier for the Zapier ones. Click a card to continue.

Create Assistant dialog on the Outbound tab with Blank Template selected: Outbound assistant and Multi Prompt under Create from scratch, and industry templates such as EMI payment reminder below — The Create Assistant dialog on the Outbound tab

Fill in Agent basics (single-prompt)

Agent basics: Agent Name (required), Primary Language (required; starts on the template’s language, or en-IN) and Secondary Language (optional; only languages that pair with the primary are listed, after None). A name like EMI reminder - Hindi tells your team the use case and language at a glance in the agent list and Logs.
Set up voice: pick a voice from the grid. Selecting a voice plays its preview. Filter by provider tab (All, then each provider) or click See more for the full list. The grid shows only voices for the selected languages; you can change languages and voice later (Voice and language).

Agent basics with Agent Name EMI reminder, Primary Language English (India), Secondary Language Hindi, and the voice Ananya selected in the voice grid — Step 1: agent basics and voice

Click Next. It checks the fields in order and stops with “Agent name is required”, “Please select a language” or “Please select a voice”; a voice must be selected, not only previewed.

Fill in the call context

The second step holds what the template needs to write your prompt:

Call context: the template’s own fields, such as company details and the purpose of the call. Fields marked * are required. Type @ in a field to insert a variable, or to create one (Write the prompt).
Custom variables: values that change per call (Variables). Variables that come with the template cannot be removed. Names are lowercased and spaces become _ as you type.
Knowledge Base: attach one or more knowledge bases. Don’t have one yet? Create a knowledge base.
Inbound Calling (Outbound only): Enabled lets this outbound agent also answer calls (an Outbound-Inbound agent). Default Disabled.
Select Phone Number (Inbound only) or Select WhatsApp Number (WhatsApp only): pick the Telephony provider, then the Number the agent answers on. Optional: you can attach it later. Don’t have one yet? Buy or import a number, or connect WhatsApp.

Call context step with Company details and Purpose of the call filled in for Acme Lending, and an empty Additional instructions field — Step 2: call context

Click Create Assistant. Back returns to the first step without losing your entries. “Please fill in all required fields” means a Call context field is empty; the page scrolls to it and outlines it in red.

Land in the editor

A progress screen shows while Ringg writes the prompt (“This usually takes under a minute”).

You see Assistant created and the agent opens in the single-prompt editor at /assistants/<agent_id>, with its name and Test assistant in the top bar. On the Agents page it is at the top of Edited last week, labelled with its channel and direction, for example Voice • Outbound.

Multi-prompt agents

Clicking Multi Prompt skips the form: Ringg creates an agent named Untitled Workflow and opens the canvas. Rename the agent from its name in the top bar, then build the flow: Multi-prompt agents.

With the API

Send POST /public/agent with your API key in X-API-KEY (authentication). It creates a single-prompt agent and returns its ID. Get a voice_id from List Voices first. The API cannot create Webcall, WhatsApp or multi-prompt agents; use the dashboard for those.

curl -X POST "https://prod-api.ringg.ai/ca/api/v0/public/agent" \
  -H "X-API-KEY: $RINGG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Payment reminder",
    "agent_type": "outbound",
    "primary_language": "en-IN",
    "secondary_language": "hi-IN",
    "voice_id": "857e1b18-0adb-4b3e-b150-ce7896a16bf1",
    "intro_message": "Hello, this is Asha from Acme Finance. Is this a good time to talk?",
    "introduction_and_objective": "You are Asha, a polite collections assistant for Acme Finance. Remind the customer of their upcoming EMI and confirm a payment date.",
    "task": "Confirm identity, state the EMI amount and due date, ask when they will pay, and note the date.",
    "response_guidelines": "Be brief and respectful. Never threaten. If the customer disputes the amount, offer a callback from the team.",
    "custom_variables": ["callee_name", "mobile_number", "emi_amount", "due_date"]
  }'

const response = await fetch("https://prod-api.ringg.ai/ca/api/v0/public/agent", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.RINGG_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_name: "Payment reminder",
    agent_type: "outbound",
    primary_language: "en-IN",
    secondary_language: "hi-IN",
    voice_id: "857e1b18-0adb-4b3e-b150-ce7896a16bf1",
    intro_message: "Hello, this is Asha from Acme Finance. Is this a good time to talk?",
    introduction_and_objective: "You are Asha, a polite collections assistant for Acme Finance. Remind the customer of their upcoming EMI and confirm a payment date.",
    task: "Confirm identity, state the EMI amount and due date, ask when they will pay, and note the date.",
    response_guidelines: "Be brief and respectful. Never threaten. If the customer disputes the amount, offer a callback from the team.",
    custom_variables: ["callee_name", "mobile_number", "emi_amount", "due_date"],
  }),
});
console.log(await response.json());

import os
import requests

response = requests.post(
    "https://prod-api.ringg.ai/ca/api/v0/public/agent",
    headers={"X-API-KEY": os.environ["RINGG_API_KEY"]},
    json={
        "agent_name": "Payment reminder",
        "agent_type": "outbound",
        "primary_language": "en-IN",
        "secondary_language": "hi-IN",
        "voice_id": "857e1b18-0adb-4b3e-b150-ce7896a16bf1",
        "intro_message": "Hello, this is Asha from Acme Finance. Is this a good time to talk?",
        "introduction_and_objective": "You are Asha, a polite collections assistant for Acme Finance. Remind the customer of their upcoming EMI and confirm a payment date.",
        "task": "Confirm identity, state the EMI amount and due date, ask when they will pay, and note the date.",
        "response_guidelines": "Be brief and respectful. Never threaten. If the customer disputes the amount, offer a callback from the team.",
        "custom_variables": ["callee_name", "mobile_number", "emi_amount", "due_date"],
    },
)
print(response.json())

Response (200)

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-0000000000a1",
    "version": "v1",
    "version_id": "3411d748-1dde-4701-88ad-8d1e8fd5cefe",
    "created_at": "2024-12-16T13:03:29.947147+00:00"
  },
  "message": "Agent created successfully"
}

data.id is the agent_id you pass to calling and campaign endpoints. Get Agent returns the new agent, and it is on the Agents page in the dashboard.

Likeliest error: 400 with code VOICE_LANGUAGE_MISMATCH: the voice does not support primary_language. Pick a voice from List Voices whose languages include it. intro_message becomes the agent’s First message. The other text fields become four prompt sections, shown in the editor as Objective, Response Guidelines, Conversation Script (task, with sample_conversations appended) and FAQs; open the agent in the dashboard to review them (Write the prompt). An AI assistant can also create agents for you through the Ringg MCP server.

Request fields

The Create Agent reference lists every field. The essentials:

string

required

Up to 100 characters.

string

required

First thing the agent says; up to 500 characters.

string

required

Up to 2,000 characters.

string

required

Up to 1,500 characters.

string

required

Up to 3,000 characters.

string

required

A locale such as en-IN or hi-IN; see language codes the API accepts.

string

required

From List Voices; must support the language.

string

outbound (default), inbound or outbound_inbound.

string[]

Per-call variables. For outbound agents, callee_name and mobile_number are always added.

string

A second locale the agent can switch to.

string

Questions and answers; up to 5,000 characters.

string

Example conversations; up to 5,000 characters. Use \n between turns.

object

Call behaviour; every key is optional. See Call settings for the keys.

Troubleshooting

"Template not available"

The general template for that channel could not be loaded. Close the dialog and try again, or start from an industry template.

Do I need a number before I create the agent?

No. Outbound agents never store a number: you pick the caller ID per call or campaign. Inbound and WhatsApp agents can be created without one and have it attached later.

Next steps

Write the prompt

Edit the first message and the sections Ringg wrote.

Test the agent

Call yourself, or talk to it in the browser, before going live.

Buy or import a number

The caller ID for outbound calls, or the line an inbound agent answers.

Build agents

Inventory

Deploy

Monitor

Manage account

Ringg Labs

Create an agent

Before you start

A Ringg workspace

An API key

In the dashboard

Multi-prompt agents

With the API

Request fields

Troubleshooting

Next steps

Write the prompt

Test the agent

Buy or import a number

​Before you start

A Ringg workspace

An API key

​In the dashboard

​Multi-prompt agents

​With the API

​Request fields

​Troubleshooting

​Next steps

Write the prompt

Test the agent

Buy or import a number

Before you start

In the dashboard

Multi-prompt agents

With the API

Request fields

Troubleshooting

Next steps