> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> To search or read these docs, connect the Ringg docs MCP server at https://docs.ringg.ai/mcp (no key needed; tools search_ringg_ai and query_docs_filesystem_ringg_ai) instead of browsing pages one by one. Setup for each client: https://docs.ringg.ai/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants.md
> The dashboard labels agents "Assistants"; these docs say "agent". Both mean the same object, identified by agent_id.
> API base URL: https://prod-api.ringg.ai/ca/api/v0. Send the workspace API key in the X-API-KEY header, from server-side code only.
> Placing a call dials a real phone number and spends credits. Confirm the number with the user before calling.
> To act on a Ringg workspace (place calls, edit agents, read transcripts), use the separate Ringg workspace MCP server at https://mcp.ringg.ai/mcp: https://docs.ringg.ai/resources/mcp-server/workspace-mcp-server/overview.md
# Test an agent
> Test a Ringg AI agent before going live: place a phone call to a verified number, run a web call or live chat in the browser, then review the call in Logs.
Test after every prompt or settings change, and always before you attach a live number or start a campaign. Repeat the loop until the agent behaves: edit, save or publish, test, check the call in [Logs](/documentation/monitor/logs).
In the dashboard: **Sidebar → Assistants →** open an agent **→ Test assistant**.
This chapter is the loop between a change and going live: test here, ship the change with [drafts and versions](/documentation/build-agents/test-and-improve/drafts-and-versions) (A/B test it on live traffic if you want), and run through [go-live checklist](/documentation/build-agents/customize-agent-behaviour/voice-and-language#before-a-voice-agent-goes-live) before an agent that makes or answers phone calls goes live. After it, [Workflows](/documentation/build-agents/workflows/overview) chains several conversations per contact, and the **Deploy** tab starts with [phone numbers](/documentation/inventory/phone-numbers/overview).
## Before you start
Saved or published with the change you want to hear.
## Ways to open a test
| From | Click | What opens |
| - | - | - |
| The agent editor | **Test assistant** (top bar) | The test dialog |
| The **Agents** list | The row's options menu **→ Test** | The editor, with the test dialog open |
| A call in [Logs](/documentation/monitor/logs) | The call's menu **→ Test this agent** | The editor, with the test dialog open on the same channel and pre-filled with that call's number and variables |
**Test assistant** is hidden while you have unsaved changes. In a single-prompt agent the top bar shows **Discard** and **Save** instead; in a multi-prompt agent it shows **Discard** and **Publish**. Save or publish first, then test.
## Test options
The dialog is titled **Test** followed by the agent name, with the line "Run a live test before you go to production." It has three tabs.
| Tab | What happens | What you need |
| - | - | - |
| **Phone call** | Ringg calls a real phone from a number you pick | A caller number and a callee number you control ([verification](#test-numbers-and-verification)) |
| **Web call** | You talk to the agent in the browser | A microphone and browser permission to use it |
| **Live chat** | You type to the agent and it replies in text | Nothing extra |
Each tab shows one field per [custom variable](/documentation/build-agents/customize-agent-behaviour/custom-variables), so you can test with realistic values (for example `callee_name` = Priya, `due_date` = 15 October). Variables are optional. On a web call or live chat with no variables, the tab says "Nothing to fill in".
In a [multi-prompt agent](/documentation/build-agents/agents/multi-prompt-agents/test-and-convert#test-a-multi-prompt-agent), **Test assistant** is a menu of the same three modes; web call and live chat run in a side panel next to the canvas.
## In the dashboard
The video opens the test dialog, looks at the three tabs, and places a phone call with variables filled in.
Under **Choose a number**, pick the number the agent calls from. The list is grouped into **Test numbers**, **Your numbers** and **In use** (already attached to an agent; listed but not selectable). When a Ringg test number is available, it is picked by default ([test number rules](#test-numbers-and-verification)). To call from your own number, [buy or import one](/documentation/inventory/phone-numbers/buy-or-import-a-number) first.
In **Callee number**, enter a phone you can answer, in international format (`+91 98765 43210`). The field's hint reads "Use a number you control for testing. Don't use customer numbers." Numbers you have verified before are in the field's dropdown under **Verified numbers**.
If you picked a test number for the wrong region, the dialog says "To call India, use the IN test number or one of your purchased numbers." (or the outside-India version) and **Start** stays disabled.
Enter values for the agent's [variables](/documentation/build-agents/customize-agent-behaviour/custom-variables). `mobile_number` is filled from **Callee number**.
**Smart formatter** "Cleans up the callee name before the call." Its settings: **Extract first name** (on by default; skips prefixes like Mr, Mrs, Dr, Shri) and **Transliteration** (off by default; converts the name to a target language; enter **Source** and **Target** codes such as `en` and `hi`). Campaigns offer the same option ([Transliteration](/documentation/deploy/campaigns/calling-list#transliteration)).
If the callee number is not yet verified, Ringg sends a 6-digit code to that number on WhatsApp. The **Verify number** screen opens: enter the code and the call is placed straight away. **Resend** sends a new code; the pencil next to the number lets you change it. Workspaces that have completed KYC skip this screen.
The dialog shows the call's status, the number being called and the agent's caller number. **Call details** lists the variables sent. The status refreshes until the call ends. **Redial** places the call again; there is no hang-up button, so end the call from your phone.
Your phone rings, the agent speaks its first message, and the call appears in [Logs](/documentation/monitor/logs) when it ends.
A test call is dialled at once: it ignores the calling window and call limits, and it is never retried. It costs credits like any other call, so it needs enough balance to start. Test calls are rate-limited; if you place many in a row, wait a minute and try again.
For a **Web call** or **Live chat**, fill in variables and click **Start**. During a web call, the button at the bottom mutes and unmutes your microphone. Closing the dialog asks "End this call?" (or "End this chat?"); the form keeps what you typed.
### WhatsApp agents
A WhatsApp agent's dialog has no tabs. It says "Scan to start a WhatsApp chat" and shows a QR code for the agent's WhatsApp number, with **Open in WhatsApp**. If no number is attached, it says "No number attached" and "Attach a WhatsApp number, then reopen Test assistant." See [attach a WhatsApp number](/documentation/build-agents/agents/whatsapp-agents/create-an-agent#attach-a-whatsapp-number) and [test from your phone](/documentation/build-agents/agents/whatsapp-agents/create-an-agent#test-from-your-phone).
## With the API
Place one call with [Initiate Individual Call](/api-reference/endpoint/calling/initiate-individual-call), sending your [API key](/documentation/manage-account/api-key) in `X-API-KEY`. The dialog's **cURL** button copies the request for the test you set up.
```bash cURL theme={null}
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": "b1972188-038e-4605-916c-3926e9d7bde4",
"from_number_id": "",
"custom_args_values": {
"callee_name": "Priya",
"due_date": "15 October"
}
}'
```
```javascript JavaScript theme={null}
const response = 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: "b1972188-038e-4605-916c-3926e9d7bde4",
from_number_id: "",
custom_args_values: {
callee_name: "Priya",
due_date: "15 October",
},
}),
});
console.log(await response.json());
```
```python Python theme={null}
import os
import requests
response = 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": "b1972188-038e-4605-916c-3926e9d7bde4",
"from_number_id": "",
"custom_args_values": {
"callee_name": "Priya",
"due_date": "15 October",
},
},
)
print(response.json())
```
* `name`, `mobile_number` and `agent_id` are required, plus exactly one of `from_number_id` or `from_number` ([choose the caller ID](/documentation/inventory/phone-numbers/inbound-agent-number#outbound-choose-the-caller-id)). Find the `agent_id` in the editor ([Find the agent ID](/documentation/build-agents/agents/agent-types#find-the-agent-id)).
* Get `from_number_id` from [Get Workspace Numbers](/api-reference/endpoint/numbers/get-workspace-numbers).
* `version_id` is optional. Without it the call uses the agent's active version, or follows the traffic split while an A/B test runs. Pass it to test a specific [version](/documentation/build-agents/test-and-improve/drafts-and-versions).
* A call placed with an API key is a live call, not a test call: it follows the calling window, call limits and retries, and it can't use a Ringg test number.
The response includes `data.call_id` and `data.call_status` (for example `registered` or `ongoing`). Use the `call_id` with [Get Call Details](/api-reference/endpoint/history/get-call-details) to read the transcript and analysis.
## Test numbers and verification
| Rule | Detail |
| - | - |
| Ringg test numbers are region-bound | The +91 test number calls only Indian numbers; the other test numbers call only outside India ([test numbers](/documentation/inventory/phone-numbers/overview#test-numbers)). Your own numbers can call anywhere. |
| Default caller number | A test number that matches your workspace's currency (INR picks the +91 number) |
| Callee verification | Each callee number is verified once, with a 6-digit WhatsApp code, then remembered for the workspace |
| Skip verification | Workspaces that have completed KYC, and enterprise workspaces, skip it. **Complete KYC** in the dialog opens **Company details** ([Company details (KYC)](/documentation/manage-account/members#company-details-kyc)) and brings you back to the test after you save. |
## Check the result in Logs
Open [Logs](/documentation/monitor/logs) in the sidebar, or use **History** in the agent's row menu to see only that agent's calls. Click the test call to open its details ([the call panel](/documentation/monitor/logs#the-call-panel)):
| Tab | What to check |
| - | - |
| **Call details** | The recording, call latency (when the first utterance began), the **Custom variables** the call received, and any call transfer |
| **Advanced analysis** | Shown when the agent has [Advanced Analysis](/documentation/build-agents/customize-agent-behaviour/advanced-analysis) set up: did it extract the right values? |
| **Transcript** | The full conversation, turn by turn |
| **Evals** | Shown when [evals](/documentation/monitor/evals) ran on the call |
Analysis runs after the call ends, so for a short while you may see "General analysis is currently under process!". Logs doesn't mark a call as a test: its **Origin** shows **API**.
A quick checklist for every test:
* The [first message](/documentation/build-agents/customize-agent-behaviour/agent-prompt#what-the-prompt-section-holds) plays, and variables are spoken with the values you entered.
* The agent follows the script and answers questions from its [knowledge base](/documentation/build-agents/customize-agent-behaviour/attach-a-knowledge-base).
* [Tools](/documentation/build-agents/customize-agent-behaviour/tools/overview) fire when expected, and transfers reach the right number.
* The agent switches language when you do, if it has a [secondary language](/documentation/build-agents/customize-agent-behaviour/voice-and-language#languages).
* The call ends cleanly, and the [analysis fields](/documentation/build-agents/customize-agent-behaviour/advanced-analysis#where-results-appear) are filled in.
## Troubleshooting
The code goes to the callee number on WhatsApp, so that number must use WhatsApp. Click **Resend**, or use the pencil next to the number to change it.
Only to call outside the test number's region, or to place calls from the API or a campaign.
## Next steps
Put an inbound agent live on a phone number.
Call a list of contacts once your tests pass.
Filter, search and inspect every call.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
### WhatsApp agents
A WhatsApp agent's dialog has no tabs. It says "Scan to start a WhatsApp chat" and shows a QR code for the agent's WhatsApp number, with **Open in WhatsApp**. If no number is attached, it says "No number attached" and "Attach a WhatsApp number, then reopen Test assistant." See [attach a WhatsApp number](/documentation/build-agents/agents/whatsapp-agents/create-an-agent#attach-a-whatsapp-number) and [test from your phone](/documentation/build-agents/agents/whatsapp-agents/create-an-agent#test-from-your-phone).
## With the API
Place one call with [Initiate Individual Call](/api-reference/endpoint/calling/initiate-individual-call), sending your [API key](/documentation/manage-account/api-key) in `X-API-KEY`. The dialog's **cURL** button copies the request for the test you set up.