Make your first AI phone call with the Ringg AI API

It takes five requests, and they are the path every Ringg build follows: an agent, a number, a call, then the result in Logs.

Before you start

A Ringg workspace

Balance

Calls draw down your workspace balance.

A caller number of your own

Buy or import one. Ringg’s test numbers do not work from the API.

You also need a phone you can answer. No number of your own, or no code? Open an agent in the dashboard, click Test assistant and call your phone from a Ringg test number instead: Test an agent. All requests go to https://prod-api.ringg.ai/ca/api/v0 and send your key in the X-API-KEY header. The examples read it from the RINGG_API_KEY environment variable; JavaScript uses fetch (Node.js 18 or later), Python uses requests.

Get an API key and check it

In the dashboard, go to Settings → API key and click Generate API Key. Copy the key from the dialog: it is shown only once. If the workspace already has a key, ask whoever holds it; Regenerate API Key revokes the old key at once. See API key.

export RINGG_API_KEY="your-api-key"

Check the key with Get Workspace Info, a read-only request.

curl "https://prod-api.ringg.ai/ca/api/v0/workspace" \
  -H "X-API-KEY: $RINGG_API_KEY"

const res = await fetch("https://prod-api.ringg.ai/ca/api/v0/workspace", {
  headers: { "X-API-KEY": process.env.RINGG_API_KEY },
});
console.log(res.status, await res.json());

import os
import requests

res = requests.get(
    "https://prod-api.ringg.ai/ca/api/v0/workspace",
    headers={"X-API-KEY": os.environ["RINGG_API_KEY"]},
)
print(res.status_code, res.json())

Response (200)

{
  "workspace_info": {
    "id": "00000000-0000-4000-8000-000000000112",
    "name": "Acme Finance's Workspace",
    "created_at": "2024-12-16T13:03:29.947147+00:00",
    "credits": 3025,
    "locked_credits": 0
  }
}

A 200 with your workspace’s name means the key works. Check that credits is above zero before you place a call.

Likeliest error: 401 with "message": "Invalid credentials". The key is missing, mistyped or was regenerated. Copy it again, or regenerate it on the API key page.

Get an outbound agent

The call needs the ID of an outbound or outbound-inbound agent. Use one you have, or create one.In the dashboard: open Assistants in the sidebar. For an existing agent, open it and click the copy button beside its name in the top bar; the ID is also in the URL, /assistants/<agent_id>. To create one, click Create agent, choose the Outbound tab and a template, then follow Create an agent.With the API: list your agents with Get Assistants and pick one whose agent_type is outbound or outbound_inbound:

curl "https://prod-api.ringg.ai/ca/api/v0/agent/all" \
  -H "X-API-KEY: $RINGG_API_KEY"

Or create one with Create Agent. First get a voice_id that speaks your language from Get Assistant Voices (GET /agent/voices?language=en-IN).

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": "Quickstart agent",
    "agent_type": "outbound",
    "primary_language": "en-IN",
    "voice_id": "00000000-0000-4000-8000-00000000010e",
    "intro_message": "Hi, this is Asha from Acme Finance. Do you have a minute?",
    "introduction_and_objective": "You are Asha, a friendly assistant for Acme Finance. This is a test call to show how Ringg works.",
    "task": "Greet the caller by name, ask how their day is going, answer one question, then say goodbye.",
    "response_guidelines": "Keep replies short and warm. Never ask for personal or payment details."
  }'

const res = 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: "Quickstart agent",
    agent_type: "outbound",
    primary_language: "en-IN",
    voice_id: "00000000-0000-4000-8000-00000000010e",
    intro_message: "Hi, this is Asha from Acme Finance. Do you have a minute?",
    introduction_and_objective:
      "You are Asha, a friendly assistant for Acme Finance. This is a test call to show how Ringg works.",
    task: "Greet the caller by name, ask how their day is going, answer one question, then say goodbye.",
    response_guidelines: "Keep replies short and warm. Never ask for personal or payment details.",
  }),
});
console.log(res.status, await res.json());

import os
import requests

res = requests.post(
    "https://prod-api.ringg.ai/ca/api/v0/public/agent",
    headers={"X-API-KEY": os.environ["RINGG_API_KEY"]},
    json={
        "agent_name": "Quickstart agent",
        "agent_type": "outbound",
        "primary_language": "en-IN",
        "voice_id": "00000000-0000-4000-8000-00000000010e",
        "intro_message": "Hi, this is Asha from Acme Finance. Do you have a minute?",
        "introduction_and_objective": "You are Asha, a friendly assistant for Acme Finance. This is a test call to show how Ringg works.",
        "task": "Greet the caller by name, ask how their day is going, answer one question, then say goodbye.",
        "response_guidelines": "Keep replies short and warm. Never ask for personal or payment details.",
    },
)
print(res.status_code, res.json())

Response (200)

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000104",
    "version": "v1",
    "version_id": "00000000-0000-4000-8000-000000000105",
    "created_at": "2024-12-16T13:03:29.947147+00:00"
  },
  "message": "Agent created successfully"
}

data.id is your agent_id. Outbound agents always get the variables callee_name and mobile_number. An agent created by API gets a calling window of 09:00 to 21:00 in Asia/Kolkata unless you set call_config.call_time; a call placed outside the window waits until it opens (calling window).Likeliest error: 400 with code VOICE_LANGUAGE_MISMATCH, for example “Voice does not support language ‘en-US’”. Pick a voice_id whose languages include your primary_language.

Choose a caller number

The caller number is the number your phone will show. List your workspace’s numbers with Get Workspace Numbers:

curl "https://prod-api.ringg.ai/ca/api/v0/workspace/numbers" \
  -H "X-API-KEY: $RINGG_API_KEY"

const res = await fetch("https://prod-api.ringg.ai/ca/api/v0/workspace/numbers", {
  headers: { "X-API-KEY": process.env.RINGG_API_KEY },
});
const { workspace_numbers } = await res.json();
console.log(workspace_numbers.filter((n) => !n.is_test_number));

import os
import requests

res = requests.get(
    "https://prod-api.ringg.ai/ca/api/v0/workspace/numbers",
    headers={"X-API-KEY": os.environ["RINGG_API_KEY"]},
)
print([n for n in res.json()["workspace_numbers"] if not n["is_test_number"]])

Response (200, one item, some fields left out)

{
  "workspace_numbers": [
    {
      "id": "00000000-0000-4000-8000-000000000109",
      "number": "+919876540001",
      "agent": null,
      "is_test_number": false,
      "is_spam": false,
      "provider": "plivo",
      "display_name": "Sales Line",
      "number_pool_id": null
    }
  ]
}

Pick a number with "is_test_number": false and "is_spam": false and copy its id: that is your from_number_id. In the dashboard, the same list is on Numbers, with a copy button for each ID.Likeliest problem: the list holds only Ringg’s shared test numbers ("is_test_number": true), which the dashboard’s test call can use and the API cannot. Buy or import a number first, or run this test from the dashboard instead.

Place the call to your own phone

Send Initiate Individual Call with your agent_id, your from_number_id, and your own number, with country code, as mobile_number. custom_args_values fills the agent’s variables, such as @{{callee_name}} in the prompt.

curl -X POST "https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual" \
  -H "X-API-KEY: $RINGG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Priya Sharma",
    "mobile_number": "+919876543210",
    "agent_id": "00000000-0000-4000-8000-000000000104",
    "from_number_id": "00000000-0000-4000-8000-000000000109",
    "custom_args_values": {
      "callee_name": "Priya"
    }
  }'

const res = await fetch("https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.RINGG_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Priya Sharma",
    mobile_number: "+919876543210",
    agent_id: "00000000-0000-4000-8000-000000000104",
    from_number_id: "00000000-0000-4000-8000-000000000109",
    custom_args_values: { callee_name: "Priya" },
  }),
});
const call = await res.json();
console.log(res.status, call.data?.call_id);

import os
import requests

res = requests.post(
    "https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual",
    headers={"X-API-KEY": os.environ["RINGG_API_KEY"]},
    json={
        "name": "Priya Sharma",
        "mobile_number": "+919876543210",
        "agent_id": "00000000-0000-4000-8000-000000000104",
        "from_number_id": "00000000-0000-4000-8000-000000000109",
        "custom_args_values": {"callee_name": "Priya"},
    },
)
print(res.status_code, res.json()["data"]["call_id"])

Response (200)

{
  "status": "success",
  "data": {
    "call_id": "00000000-0000-4000-8000-00000000010b",
    "call_direction": "outbound",
    "call_status": "ongoing",
    "initiated_at": "2025-11-24T07:33:49.629642",
    "agent_id": "00000000-0000-4000-8000-000000000104",
    "custom_args_values": {
      "callee_name": "Priya",
      "mobile_number": "+919876543210"
    }
  },
  "message": "Call initiated successfully"
}

Save data.call_id. call_status starts as registered (queued) or ongoing. A call that stays registered is waiting for the agent’s calling window to open, or is held by a call limit.

Your phone rings and shows the caller number you picked. Answer it: the agent speaks its first message. Talk to it, then hang up.

Likeliest errors:

422 with "message": "Provide either from_number_id or from_number, not both". Send name, mobile_number and agent_id, plus one of from_number_id or from_number.
400 with "message": "Default numbers are for testing only. Please provide a real phone number.". The caller number is a Ringg test number; pick another one.
402 with "message": "Your current balance is insufficient to initiate this call!". Add balance (Billing).

Read the result

After you hang up, fetch the call with Get Call Details. Add send_analysis=true to include the analysis.

curl "https://prod-api.ringg.ai/ca/api/v0/calling/call-details?id=00000000-0000-4000-8000-00000000010b&send_analysis=true" \
  -H "X-API-KEY: $RINGG_API_KEY"

const callId = "00000000-0000-4000-8000-00000000010b";
const res = await fetch(
  `https://prod-api.ringg.ai/ca/api/v0/calling/call-details?id=${callId}&send_analysis=true`,
  { headers: { "X-API-KEY": process.env.RINGG_API_KEY } },
);
const { data } = await res.json();
console.log(data.call_status, JSON.parse(data.transcription_url ?? "[]"));

import json
import os
import requests

res = requests.get(
    "https://prod-api.ringg.ai/ca/api/v0/calling/call-details",
    headers={"X-API-KEY": os.environ["RINGG_API_KEY"]},
    params={"id": "00000000-0000-4000-8000-00000000010b", "send_analysis": "true"},
)
data = res.json()["data"]
print(data["call_status"], json.loads(data["transcription_url"] or "[]"))

Response (200)

{
  "status": "success",
  "data": {
    "id": "00000000-0000-4000-8000-00000000010b",
    "call_direction": "outbound",
    "call_status": "completed",
    "call_sub_status": "ACCEPTED",
    "from_number": "+919876540001",
    "to_number": "+919876543210",
    "callee_name": "Priya Sharma",
    "agent_id": "00000000-0000-4000-8000-000000000104",
    "initiation_time": "2025-11-24T07:33:49Z",
    "recording_url": "https://example.com/recordings/call-123.mp3",
    "transcription_url": "[{\"bot\": \"Hi, this is Asha from Acme Finance. Do you have a minute?\"}, {\"user\": \"Sure, go ahead.\"}]",
    "platform_analysis": {
      "summary": "Caller agreed to talk and asked one question.",
      "key_points": ["Caller agreed to talk"],
      "action_items": []
    }
  }
}

Field	What it holds
`call_status`	`registered`, `ongoing`, `retry`, `completed`, `failed`, `error`, `cancelled` or `forwarded`
`call_sub_status`	The detail behind the status, for example `USER_DID_NOT_JOIN` or `MAX_CALL_DURATION`
`transcription_url`	The conversation as a JSON-encoded string: parse it to get one object per turn (`bot` or `user`)
`recording_url`	The recording. The link may expire; fetch the call again for a fresh link, and download the file if you need to keep it.
`platform_analysis`, `client_analysis`	Ringg’s analysis (summary, key points, action items, classification) and your Advanced Analysis fields

Analysis runs after the call ends. Until it is ready, platform_analysis and client_analysis are left out of the response, so fetch again.The same call is at the top of Logs in the dashboard. Click it for Call details, the transcript and, if set up, Advanced analysis. To find it later, filter Logs by Call ID.

call_status is completed and the parsed transcription_url shows what you and the agent said.

Likeliest error: 404 with "message": "Call not found". Check that you passed data.call_id from step 4 as id, with the same workspace’s key.

Hand it to a coding agent

The same five requests make a good first script. Paste this into Claude, Cursor or ChatGPT with your details filled in:

Write a script that places a Ringg AI call and prints the transcript.

Open in Cursor

Get results pushed to you

Polling Get Call Details is fine for a test. In production, subscribe the agent to events with Event Subscription (webhooks) and Ringg posts to your server as the call progresses. All Processing Done (all_processing_completed) carries the transcript, recording and analysis in one request. Endpoint requirements are in webhook setup.

Before you go live

Keep the API key in a secret manager on your server. See Security.
Store agent_id, from_number_id and each returned call_id; the call_id joins API responses, webhook events and Logs.
Send every mobile_number with its country code, for example +919876543210.
Send a custom_args_values key for every variable the prompt uses.
Set the calling window for your market in the agent’s call settings, and retries per call in call_config.call_retry_config or per campaign.
Dedupe webhook events on call_id plus event_type, and return 2xx quickly. See Idempotency key.

Troubleshooting

The call stays registered and my phone never rings

The call is queued because the agent’s calling window is closed. Check Call start time, Call end time and Timezone in the agent’s call settings, or send your own call_config.call_time with the call.

The call ended as failed or error

Read call_sub_status in Get Call Details; the full list of values is in Get Call Details. Also check that the caller number is not a test number and is not flagged as spam on Numbers.

The agent does not use my name

The prompt uses a variable you did not send, or sent under a different key. Add it to custom_args_values, for example "callee_name": "Priya". See Variables.

Next steps

API reference

Agents, calls, campaigns, numbers and results from your backend.

Improve the agent's prompt

Write the script, FAQs and rules your agent follows.

Run a campaign by API

Upload a list and start calls in two requests.

Introduction

Agents

Inventory

Calling

Monitoring

Account

API quickstart

Before you start

A Ringg workspace

Balance

A caller number of your own

Hand it to a coding agent

Get results pushed to you

Before you go live

Troubleshooting

Next steps

API reference

Improve the agent's prompt

Run a campaign by API

​Before you start

A Ringg workspace

Balance

A caller number of your own

​Hand it to a coding agent

​Get results pushed to you

​Before you go live

​Troubleshooting

​Next steps

API reference

Improve the agent's prompt

Run a campaign by API

Before you start

Hand it to a coding agent

Get results pushed to you

Before you go live

Troubleshooting

Next steps