&limit=20&offset=0
```
Response:
```json theme={null}
{
"success": true,
"message": "Tools fetched successfully",
"data": [ { "id": "...", "name": "book_appointment", "isActive": true } ],
"meta": { "total": 1, "limit": 20, "offset": 0 }
}
```
Get tool
Request:
```
GET https://api.ravan.ai/api/v1/tools/{id}
```
Response:
```json theme={null}
{ "success": true, "message": "Tool fetched successfully", "data": { "id": "...", "name": "book_appointment" } }
```
Create tool
Request (CreateAgentToolRequest):
```json theme={null}
POST https://api.ravan.ai/api/v1/tools
{
"name": "book_appointment",
"description": "Books a calendar slot for the caller",
"type": "function",
"agentId": "",
"definition": {
"parameters": {
"type": "object",
"properties": {
"datetime": { "type": "string" },
"name": { "type": "string" }
},
"required": ["datetime"]
}
},
"enabledFunctions": { "values": ["book", "cancel"] }
}
```
Response:
```json theme={null}
{ "success": true, "message": "Tool created successfully", "data": { "id": "new-uuid", "name": "book_appointment" } }
```
Update tool
Request:
```json theme={null}
PATCH https://api.ravan.ai/api/v1/tools/{id}
{ "name": "book_appointment_v2", "description": "Updated", "definition": { "parameters": {} }, "enabledFunctions": { "values": ["book"] } }
```
Response:
```json theme={null}
{ "success": true, "message": "Tool updated successfully", "data": { "id": "..." } }
```
Delete tool
Request:
```
DELETE https://api.ravan.ai/api/v1/tools/{id}
```
Response: `200 OK` with empty body `{}`
Duplicate tool
Request:
```json theme={null}
POST https://api.ravan.ai/api/v1/tools/{id}/duplicate
{ "agentId": "8f1c2e9a-..." }
```
Response:
```json theme={null}
{ "success": true, "message": "Tool duplicated successfully", "data": { "id": "clone-uuid" } }
```
Toggle tool
Request:
```json theme={null}
PATCH https://api.ravan.ai/api/v1/tools/{id}/toggle
{ "isEnabled": false }
```
Response:
```json theme={null}
{ "success": true, "message": "Tool toggled successfully", "data": { "id": "...", "isActive": false } }
```
Bulk-remove tools from an agent
Request (X-Api-Key protected):
```json theme={null}
DELETE https://api.ravan.ai/api/v1/agents/{agent_id}/tools
{ "ids": ["tool-uuid-1", "tool-uuid-2"] }
```
Response: `200 OK` with empty body `{}`
# Platform Analytics
Source: https://docs.ravan.ai/guides/analytics
Monitor call volume, track success rates, analyze sentiment, and measure agent performance across your entire voice infrastructure.
The **Analytics** page provides a deep dive into the operational health and effectiveness of your voice infrastructure. It allows you to monitor volume, track success rates, identify trends, and analyze AI-powered caller sentiment at a glance.
![Agni Analytics Dashboard showing platform performance insights]()
***
## Performance KPIs
At the top of the Analytics dashboard, six high-level metrics give you an immediate snapshot of your platform's performance based on your selected date range:
The absolute volume of inbound and outbound calls processed. Use this to gauge overall platform utilization.
The aggregate number of voice minutes consumed across all calls.
The percentage of calls where the agent successfully completed its objective. Low success rates may indicate prompt issues or tool misconfiguration.
The average length of your conversations. Shorter isn't always better—the right duration depends entirely on your use case.
The total number of unique AI agents that fielded calls during the selected period.
The overarching sentiment score of your callers (e.g., 26% Positive), determined by AI post-call analysis.
***
## Visualizations & Trends
Agni provides a powerful suite of interactive charts to help you visualize data trends and optimize your agents' performance over time.
A line graph tracking your **Minutes over time**. This chart directly correlates to your platform spend. Look for unexpected spikes or drops in consumption.
A comparative bar chart plotting **Success vs Failed** calls over your selected period. A rising failure rate often signals routing issues, prompt problems, or integration errors.
An AI-powered call sentiment breakdown showing the exact distribution of **Positive, Neutral, and Negative** calls, complete with a secondary graph tracking the **Weekly trend** of these emotions over time.
A horizontal bar chart comparing the **Success rates by agent**. Use this to A/B test system prompts, voices, or tool configurations to identify your most effective deployments.
Plots your **Avg duration by hour of day**. This widget also highlights the **Longest** and **Shortest** calls recorded during the timeframe to help you spot outliers.
Visualizes **Call volume by hour of day**, categorized by **Business hours** and **Off hours**. Use this to plan concurrency needs and evaluate when your customers are most active.
***
## What to Look For
Check your agent's system prompt and tools first. A common cause is tool descriptions that are too vague, causing the AI to trigger actions at the wrong time. Review recent call transcripts in the [All Call History](/guides/calls) page.
This could mean agents are struggling to reach their objective and conversations are dragging. Or, it could mean your agents are handling more complex queries—context matters. Check the call transcripts to understand.
Review the [All Call History](/guides/calls) detail view for recent calls with negative sentiment. Common causes: the agent interrupting the caller too aggressively, providing incorrect information, or failing to resolve the issue.
Check the **Usage Trend** chart for volume anomalies. If calls increased but were unintended, review your dispatch rules and campaign settings. Also, check the **Call Duration** widget for abnormally long-running calls.
***
## Filtering and Exporting Data
In the top right corner of the dashboard, you can control the scope of your analytics:
Use the quick-select pills or the date picker to recalculate your dashboard metrics for a specific timeframe (e.g., Last 30d).
Download your current analytics view to ingest this data into your CRM, billing software, or business intelligence tools for deeper analysis.
**Tip:** Set a weekly cadence to review your analytics. Tracking trends in the **Sentiment Analysis** and **Usage Trend** charts over time is much more valuable than looking at any single day's numbers.
# API keys
Source: https://docs.ravan.ai/guides/api-keys
Understand what API keys are, how Agni uses them, and how developers should handle them securely.
An API key is a secret token that identifies your organization when your app calls the Agni API.\
Think of it like a password for server-to-server access.
***
## What is an API key
* It proves the request is coming from your Agni workspace.
* It controls access to protected API endpoints.
* It should only be used in trusted backend environments.
Never put your API key in frontend code, public Git repositories, or client-side apps.
***
## Where to get your API key
1. Sign in to `https://app.ravan.ai`.
2. Open **Settings**.
3. Go to **Security & Access** > **API Keys**.
4. Click **+ New Key**.
5. Copy it immediately and store it securely.
![Settings page showing the Security and Access API Keys section]()
You can only view a newly generated key once.
***
## How Agni uses your API key
Send your key in the `X-Api-Key` header on every API request.
```bash theme={null}
curl https://api.ravan.ai/api/v1/agents/ \
-H "X-Api-Key: YOUR_API_KEY"
```
If the key is missing, invalid, or revoked, the API returns `401 Unauthorized`.
***
## Developer implementation guide
Use your API key only on the server side, and inject it from environment variables.
```bash theme={null}
# .env
AGNI_API_KEY=your_real_key_here
```
```js theme={null}
const response = await fetch("https://api.ravan.ai/api/v1/agents/", {
method: "GET",
headers: {
"X-Api-Key": process.env.AGNI_API_KEY
}
});
```
***
## Security best practices
* Rotate keys regularly.
* Use separate keys for staging and production.
* Revoke compromised keys immediately.
* Do not share keys in chat, tickets, or screenshots.
* Audit logs when you see unexpected API behavior.
***
## Troubleshooting
If requests fail with `401`:
* Confirm the header name is exactly `X-Api-Key`.
* Check there are no extra spaces in the key value.
* Ensure you are using an active key from the correct workspace.
* Regenerate the key and update your server environment.
# Appointments
Source: https://docs.ravan.ai/guides/appointments
View and manage calendar bookings generated by your voice AI agents. Currently visualizing GoHighLevel integrations.
The **Appointments** page acts as a centralized calendar for your Agni workspace. When your AI agents successfully negotiate a time and book a meeting with a caller, the resulting calendar events are automatically synced and displayed here.
![Agni Appointments Dashboard visualizing GoHighLevel calendar events]()
***
## How Appointment Booking Works
Agni agents can book, reschedule, and cancel appointments autonomously during live calls. Here's how the flow works end-to-end:
Link your **GoHighLevel** or **Cal.com** account in [Workspace Settings](/guides/settings). This gives Agni access to your calendars and availability.
In the [Agent Builder](/guides/agents), open the **Calendars** panel and select which calendar the agent should use for booking.
During a live call, the agent checks your real-time availability, suggests open slots, and confirms with the caller. It handles conflicts, timezone differences, and rescheduling automatically.
Once confirmed, the appointment appears in your connected platform. **GoHighLevel** bookings will also instantly populate your visual Agni Appointments dashboard.
***
## Integration Sources
While your agents can book meetings using both GoHighLevel and Cal.com, the visual calendar inside the Agni dashboard currently displays data synced from **GoHighLevel**.
View, filter, and manage appointments synced from your connected GHL sub-accounts directly within the Agni dashboard.
Agents can successfully book meetings via Cal.com. Manage these specific bookings directly inside your Cal.com account.
**Connection Required:** If you see a "Failed to load appointments" error, you must first authenticate and connect your GHL account in your [Workspace Settings](/guides/settings).
***
## Calendar Controls
To help you manage high volumes of automated bookings, the left sidebar of the dashboard provides several organizational tools:
Switch between **Month**, **Week**, and **Day** views to adjust timeline density based on your booking volume.
Quickly toggle specific event states. Bookings are color-coded for quick scanning: **Confirmed** (Blue), **Cancelled** (Red), and **Rescheduled** (Yellow).
Instantly find specific bookings by typing an individual's name into the **Attendee name...** search bar.
### Manual Actions
Located in the top right corner of the dashboard:
* **+ New Appointment:** While agents handle automation, you can click here to manually reserve a slot directly from the Agni interface.
* **Refresh:** Click to manually force a sync and pull the latest data from your GHL integration.
***
## What the Agent Says During Booking
During a call, the agent handles the full appointment workflow naturally. Here's an example conversation flow:
*"Let me check what times are available this week... I have openings on Tuesday at 10 AM, Wednesday at 2 PM, and Thursday at 9:30 AM. Which works best for you?"*
*"Great, I've booked you for Wednesday at 2 PM. You'll receive a confirmation email shortly. Is there anything else I can help with?"*
*"I'm sorry, that slot was just taken. The next available time on Tuesday is 3:30 PM. Would that work instead?"*
*"No problem, I've moved your appointment from Tuesday at 10 AM to Thursday at 9:30 AM. You'll get an updated confirmation."*
***
## Troubleshooting
Make sure your GHL integration is connected in [Settings](/guides/settings). Click **Refresh** on the appointments page to force a sync. Check that the correct calendar is assigned to your agent.
Verify that a calendar is assigned in the agent's **Calendars** panel. Test with a web call first to confirm the integration works before using live phone calls.
The agent uses the caller's detected timezone. If bookings appear at wrong times, check the timezone settings in your GHL calendar configuration.
***
## API Reference
Manage your calendar integrations and appointments programmatically via the Agni REST API.
Book, reschedule, cancel, and check availability via GHL.
Book, reschedule, cancel, and check availability via Cal.com.
# Authentication
Source: https://docs.ravan.ai/guides/authentication
Create your organization, verify your identity, and get your API key to start building with Agni.
Welcome to Agni. To start building production-grade voice AI agents, you need an active workspace. This guide covers how to register your organization, verify your identity, generate API keys, and manage access.
***
## Create an Account
The creation process registers a new Agni organization and sets up your initial administrator account.
![Agni Create Account Page]()
### Registration Steps
Open the [Agni Web App](https://app.ravan.ai) and click **Create an account**.
You can securely click **Sign up with Google** for single sign-on (which bypasses manual email verification), or proceed with a standard email registration.
If using email, provide your **Organization Name**, **First Name**, **Last Name**, and **Phone Number** with the correct country code. Your organization acts as the top-level container for your agents, phone numbers, and billing. [Know more about organizations](/guides/organizations-and-roles).
Enter a valid work **Email**, a secure **Password** (minimum 8 characters), and select how you heard about Agni, then click **Create account**.
If you registered via email, you will be redirected to the verification screen. Check your inbox for an email from Agni AI.
![Email Verification Screen]()
You can either click the **Verify Account** button directly in the email, or copy the 6-digit code provided and enter it manually into the verification screen.
Verification codes are only valid for 10 minutes. If your code expires or you do not receive the email, click **Didn't receive the code? Resend** on the verification screen.
Once verified, you will be routed directly to your new workspace dashboard.
If your email is already registered to an existing workspace, Agni will prompt you to sign in instead.
***
## Log In
Access your existing Agni workspace to manage agents, configure telephony, and retrieve your API keys.
![Agni Login Page]()
### Sign In Steps
Open the [Agni Login Page](https://app.ravan.ai/login).
Click **Continue with Google** if your account is linked to Google Workspace, or enter your registered **Email** and **Password**.
Click **Sign in** to access your dashboard.
If you lose access to your account, use the **Forgot?** link above the password field to initiate a secure password reset workflow.
***
## Generate an API Key
To interact with Agni programmatically, you need an API key. Here's how to create one:
Click your profile in the bottom-left corner of the dashboard, then select **Settings**.
In the Settings menu, click the **API Keys** tab under **Security & Access**.
Click **+ New Key**. Your API key will be generated and displayed once. Copy it immediately.
Save the key in a secure location (e.g., environment variable, secrets manager). You will not be able to view it again after closing the dialog.
Never expose your API key in client-side code, public repositories, or browser-accessible files. Treat it like a password.
### Using Your API Key
Pass the key in the `X-Api-Key` header with every API request:
```bash theme={null}
curl https://api.ravan.ai/api/v1/agents/ \
-H "X-Api-Key: YOUR_API_KEY"
```
***
## Next Steps
Full REST API documentation with request examples in cURL, Python, and JavaScript.
Build and deploy your first real-time voice AI agent.
Buy a phone number and connect it to your agent.
Configure your organization, invite team members, and connect integrations.
# Billing
Source: https://docs.ravan.ai/guides/billing
Manage your subscription plan, purchase credits, monitor usage costs, and access billing history.
The **Billing** page is where you manage the financial aspects of your Agni workspace. Agni operates on a hybrid model: you must first select a baseline monthly subscription plan, which then unlocks the ability to purchase prepaid credits for your usage.
![Agni Billing Dashboard showing Available Plans and Credits]()
***
## Subscriptions & Plans
Agni offers dynamic subscription tiers based on your selected region. All subscriptions are processed securely via Stripe. Choose the plan that best fits your concurrency and volume needs.
All plans include the emotion engine, 50+ languages, dialect support, API access, email support, priority support, and the analytics dashboard.
**\$97 per month**
Perfect for early-stage startups and pilot programs exploring voice AI.
* Up to **15 concurrent calls**
* **\$0.09** per credit
**\$297 per month**
Ideal for growing teams scaling their real-time voice infrastructure.
* Up to **25 concurrent calls**
* **\$0.07** per credit
**\$497 per month**
Built for high-volume operations requiring maximum throughput.
* Up to **50 concurrent calls**
* **\$0.05** per credit
***
## Credits & Usage
Because real-time voice AI incurs immediate compute and telephony costs, Agni uses a prepaid credit system for call volume. Your agents consume these credits dynamically as they handle live calls.
**Important:** You must have an active subscription plan (Starter, Growth, or Scale) before you can purchase usage credits.
Displays your organization's current, real-time credit balance at the top of the page. Keep an eye on this metric to ensure your agents stay online.
Once subscribed, click this button to top up your account. Adding funds takes only a few seconds and applies to your workspace instantly.
If your credit balance reaches zero, your agents will be temporarily paused and active dispatch rules will fail to connect. Ensure you maintain a positive balance to avoid service interruptions.
***
## Billing History
At the bottom of the page, the **Billing History** table provides a transparent ledger of your past transactions.
Whether you are purchasing prepaid credits or paying for your monthly subscription plan, your official invoices and receipts will automatically populate in this table. You can download them at any time for your accounting and tax records.
***
## Cost Optimization Tips
In your agent's [Call Settings](/guides/agents), set a **Max duration** to prevent runaway calls from consuming excessive credits. 30 minutes is a good hard limit for most use cases.
Turn on **End call after silence** in your agent settings to automatically disconnect calls where the caller has gone silent, avoiding wasted credits.
Check the [Analytics dashboard](/guides/analytics) regularly. Watch for unexpected spikes in call volume or duration that could indicate prompt issues or campaign misconfiguration.
Not every use case needs the most powerful model. For simple routing or FAQ agents, Thunder Emotion Lite performs exceptionally well at a lower computational cost.
# All Call History
Source: https://docs.ravan.ai/guides/calls
Monitor, filter, and review every conversation handled by your Agni agents—including transcripts, recordings, summaries, credit usage, and sentiment analysis.
The **All Call History** page serves as your centralized ledger for all voice interactions across your organization. Whether you are running high-volume outbound campaigns, fielding inbound customer support calls, or testing your web widget, every session is logged here in real time.
![Agni All Call History list view]()
***
## Session metrics
At the top of the dashboard, a quick-glance summary provides the status of your call volume for the selected timeframe:
The cumulative number of all calls across all channels and agents.
Calls that successfully reached their natural conclusion.
Calls that dropped, failed to connect, or encountered system errors.
Live calls currently being handled by your agents.
***
## Call data and channels
Agni consolidates traffic from multiple channels into a single view. You can filter the main table using the quick tabs above the list: **All**, **Web**, **Inbound**, or **Outbound**.
For every session, the table captures granular data:
* **Caller:** The phone number or web session identifier of the user.
* **Status:** The outcome of the call.
* **Channel:** The origin of the call.
* **Duration:** The total length of the conversation.
* **Sentiment:** The overall mood of the interaction.
* **Agent:** The specific AI agent that handled the interaction.
* **Time:** The date and timestamp of when the call occurred.
***
## Call detail view
Click on any row to open the full **Call Detail View**. This view provides a comprehensive breakdown of the conversation. The page displays metadata on the left and the interaction transcript on the right.
![All Call History detailed view showing metadata and transcript]()
### Left panel: Metadata and analysis
The left side of the detailed view gives you the technical and analytical breakdown of the call:
* **Core Metrics:** Instantly view the **Callee** number, total **Duration**, **Channel**, total **Credits** consumed, the overall **Sentiment**, and the **Agent** used.
* **Credit Breakdown:** Click the dropdown arrow next to your total credits to see exactly how your balance was consumed. This splits the cost into **Model Credits** (Agni AI compute), **Twilio Credits** (telephony infrastructure), and **Other Credits**.
![Expanded Credit Breakdown]()
* **Disconnect Reason:** Explains exactly why the call ended (for example, `user hangup` or `max duration reached`).
* **Created:** The exact timestamp the call was initiated.
* **Post Call Analysis:** If configured on your agent, this section displays the AI-generated **Summary** of the conversation along with the final evaluated **Sentiment**.
### Right panel: Transcription and recording
The right side of the view is dedicated to the actual conversation flow:
* **Transcription:** A timestamped, speaker-labeled transcript presented in a chat-bubble format. The AI agent's responses are on the left, and the user's responses are on the right.
* **Recording:** Click the **Recording** button at the top right of the transcription panel to listen to the actual audio of the phone call.
* **Tool Calls:** View active tool invocations inline within the transcription flow. Click any tool card (such as `calcomAppointment`) to expand it. This reveals the full request payload and the response data for troubleshooting.
![Expanded tool call request and response payload]()
* **Error Logs:** View detailed error logs directly when a call fails or goes unanswered. This includes carrier errors from telephony providers like Twilio or errors during the call.
![Call session error logs showing Twilio failure details]()
***
## Search, filter, and export
To manage large volumes of call data, utilize the toolbar located above the main table:
Look up specific calls by phone number or session ID using the search bar.
Narrow down your view by selecting specific timeframes or applying advanced filters.
Click the **Export** button in the top right to download your currently filtered call logs as a CSV file.
# Outbound
Source: https://docs.ravan.ai/guides/campaigns
Run outbound calling at scale from the Campaigns section. Create outbound workflows, manage contact lists, monitor performance, and optimize results.
# Running outbound calls
In the **Campaigns** section, the **Outbound** area lets you automate outbound calls at scale — from lead qualification and appointment reminders to customer follow-ups and surveys. Define your audience, assign an agent, and let Agni handle the rest.
***
![Campaigns dashboard showing all campaigns with status, success rate, and contact counts]()
***
## How Campaigns Work
Give your campaign a name, select the AI agent that will handle calls, and choose your Caller ID.
Select contacts to call, set your call window (timezone, hours, active days), and configure advanced settings like retries and gap between attempts.
After creating the campaign, click the **Start** button on the campaign overview page. Agni dials contacts automatically within your configured call window.
Track completion rates, call outcomes, and campaign progress in real-time from the campaign overview.
***
## Creating a Campaign
Click **+ New Campaign** from the Campaigns page. Campaign creation is a two-step process.
### Step 1 — Campaign Details
![New Campaign step 1 — enter campaign name, select AI agent, and choose Caller ID]()
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------ |
| **Campaign Name** | A recognizable label for your campaign (e.g., "Q1 Customer Outreach") |
| **AI Agent** | The voice agent that will handle the calls. You can search across all active agents. |
| **Caller ID** | The phone number calls will be placed from. Select from your verified numbers. |
### Step 2 — Contacts & Settings
![New Campaign step 2 — select contacts and configure call window]()
On the second step, select your contacts and configure the call schedule.
**Selecting Contacts**
Use the filter tabs to narrow your contact list:
| Tab | Description |
| ------------------ | -------------------------------------------- |
| **Fresh Leads** | Contacts that have never been called |
| **Need Follow-up** | Contacts that require a follow-up call |
| **Failed - Retry** | Contacts where previous call attempts failed |
| **All** | Your entire contact list |
You can also filter by **Tags**, **Status**, **Last Called**, or **Added** date, and use **Select All** to include your entire filtered list.
**Call Window**
Define when Agni is allowed to place calls:
| Setting | Description |
| --------------- | --------------------------------------------------------------------------- |
| **Timezone** | The timezone used to enforce your call window (e.g., UAE / Dubai UTC+04:00) |
| **From / To** | Start and end time for calls each day (default: 09:00 AM – 05:00 PM) |
| **Active Days** | Days of the week calls are permitted (default: Mon–Fri) |
**Advanced Settings**
| Setting | Description | Default |
| ------------------ | -------------------------------------------------------------- | --------------------- |
| **Max Concurrent** | Maximum simultaneous calls. Capped by your plan limit. | Up to 5 on free plans |
| **Retries** | Number of retry attempts per contact if the call is unanswered | 2 |
| **Gap (Min)** | Minimum time in minutes between retry attempts | 30 |
Max Concurrent calls are controlled by your plan. Free plans support up to 5 concurrent calls. Upgrade your plan to increase this limit.
![Call window and Advanced Settings panel showing Max Concurrent, Retries, and Gap fields]()
Click **Create Campaign** to finish. Your campaign will be created in **Draft** status.
***
## Starting a Campaign
After creation, you'll land on the campaign overview page. The campaign starts in **Draft** state — no calls are placed yet.
Click the **Start** button (top right) to activate the campaign. Agni will begin dialing contacts within your configured call window.
You can **pause** a running campaign at any time from the campaign card on the Campaigns page or from within the campaign overview.
***
## Campaign Overview
Once a campaign is created, clicking into it shows a full overview:
![Campaign overview page showing progress, stats, recent activity, and configuration panel]()
| Section | Description |
| --------------------- | ---------------------------------------------------------------------------- |
| **Campaign Progress** | Bar showing Successful, Failed, No Answer, In Progress, and Pending contacts |
| **Total Contacts** | Total number of contacts in the campaign |
| **Success Rate** | Percentage of calls that achieved the desired outcome |
| **Contacted** | Number of contacts successfully reached |
| **In Progress** | Calls currently being placed |
| **Recent Activity** | Live feed of call events as they happen |
The right panel shows your **Configuration** (agent, outbound number), **Schedule** (call window, max concurrent), and **Retry Policy** (attempts, gap between retries).
***
## Campaigns Dashboard
The main Campaigns page shows all your campaigns and a high-level summary at the top:
| Metric | Description |
| ----------------- | --------------------------------------- |
| **Total Calls** | Total calls placed across all campaigns |
| **Running Calls** | Calls currently in progress |
| **Avg Success** | Average success rate across campaigns |
| **Active** | Campaigns currently running |
| **Scheduled** | Campaigns scheduled to run |
Each campaign card displays the agent's phone number, creation date, total contacts, success rate, contacted count, and pending contacts. Campaigns can be in **Active**, **Paused**, **Completed**, or **Scheduled** states.
Use the filter tabs (**All**, **Active**, **Scheduled**, **Paused**) or the search bar to find specific campaigns.
***
## Contact Management
### Importing Contacts
Contacts can be added via CSV upload or the API before being assigned to a campaign.
**Via CSV Upload:**
```csv theme={null}
phone,name,company,appointment_date
+14155551234,John Smith,Acme Corp,March 30
+14155559876,Jane Doe,TechCo,April 2
+14155555555,Bob Wilson,StartupHQ,April 5
```
**Via API:**
```bash theme={null}
curl -X POST https://api.ravan.ai/api/v1/contacts/ \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+14155551234",
"first_name": "John",
"last_name": "Smith",
"company": "Acme Corp",
"custom_fields": {
"appointment_date": "March 30"
}
}'
```
### Using Contact Data in Calls
Contact fields map to dynamic variables in your agent prompt:
```text theme={null}
You are calling {{first_name}} {{last_name}} from {{company}}
about their appointment on {{appointment_date}}.
```
***
## Campaign Patterns
**Goal:** Reduce no-shows by confirming appointments 24 hours ahead.
* Agent prompt: Confirm date/time, offer reschedule option
* Concurrency: 5–10 (high volume, short calls)
* Call window: Business hours, day before appointment
* Retries: 2
* Dynamic variables: `{{patient_name}}`, `{{appointment_date}}`, `{{doctor_name}}`
**Goal:** Qualify inbound leads before passing to sales.
* Agent prompt: Ask qualifying questions (budget, timeline, decision maker)
* Concurrency: 3–5 (longer conversations)
* Call window: Within 5 minutes of lead submission
* Retries: 3 (over 2 days)
* Post-call analysis: Extract qualification score
**Goal:** Collect NPS or satisfaction feedback post-purchase.
* Agent prompt: Ask 3–5 structured questions, thank the customer
* Concurrency: 5–8
* Call window: 2–7 days after purchase
* Retries: 2
* Post-call extraction: Rating (1–10), comments, follow-up needed
**Goal:** Win back churned or inactive customers.
* Agent prompt: Acknowledge absence, offer incentive, address concerns
* Concurrency: 3–5
* Call window: Weekday afternoons (highest answer rate)
* Retries: 2 (avoid being pushy)
* Tone: Warm, no hard sell
***
## Cost Optimization
Test with 50–100 contacts first. Optimize the prompt and settings before scaling to thousands.
Calls between 10am–12pm and 2pm–5pm local time have the highest answer rates. Avoid early mornings and late evenings.
2 retries with a 30-minute gap is a solid default. More retries rarely improve reach and increase costs.
Start at 2–5 concurrent calls and scale up. Free plans are capped at 5 — upgrade for higher throughput.
***
## Compliance
Outbound calling is regulated. Ensure compliance with local laws before launching campaigns.
* **TCPA (US)** — Obtain prior express consent before automated calls. Honor Do Not Call lists.
* **GDPR (EU)** — Lawful basis required for processing phone numbers. Provide opt-out on every call.
* **Local regulations** — Check calling hour restrictions in your target regions.
* **Caller ID** — Always display a valid caller ID number. Spoofing is illegal.
Agni provides tools to manage opt-outs and consent — use them. Non-compliance can result in significant fines.
# Contacts
Source: https://docs.ravan.ai/guides/contacts
Manage your global contact list and view detailed interaction histories for outbound campaigns.
# Contacts
The **Contacts** page is your central hub for managing your global contact list and campaign assignments. From here, you can add new prospects, import bulk lists, and drill down into individual contact analytics to track your outbound calling efforts.
![Contacts List Dashboard]()
## Adding and Managing Contacts
From the main Contacts dashboard, you can search for existing contacts or use the top-right action buttons to manage your list:
* **Add Contact**: Manually create a new individual contact record.
* **Import CSV**: Upload a bulk list of contacts to quickly populate your database.
* **Export CSV**: Download your current contact list for external reporting.
* **Delete All**: Clear your existing contact database.
## Contact Details
Clicking on a specific contact from your list opens their **Contact Details** dashboard. This page provides a comprehensive, 360-degree view of their identity, performance metrics, and interaction history.
![Contact Details Overview]()
### Key Metrics
At the top of the profile, a quick-stat banner displays the overall calling outcomes for the contact:
* **Total Calls**: The total number of call attempts made to this contact.
* **Completed**: The number of calls that successfully connected and finished.
* **No Answer**: The number of calls that rang but were not answered.
* **Failed**: The number of calls that failed to connect due to network or routing issues.
* **Avg Duration**: The average length of time spent on the phone with this contact.
* **Total Time**: The cumulative duration of all successful calls.
### Insights & Metadata
Below the top-level metrics, several detail cards provide deeper context about the contact and their journey:
* **Contact snapshot**: Core identity and record metadata (including Contact ID, Organization, Creation/Update dates, and applied Tags).
* **Call performance**: Calling outcomes and duration metrics visualized for quick assessment.
* **Campaign footprint**: Campaign participation overview, summarizing how many campaigns the contact is part of and the associated calls or notes.
* **Latest call**: Information regarding the most recent outbound interaction.
* **Latest activity**: The last recorded event captured for this contact in the system.
### History and Assignments
At the bottom of the details page, you can switch between dedicated tabs to view historical data or take action on the contact:
![Contact Campaigns View]()
* **Activity**: Activities will appear here as you interact with this contact, providing a chronological timeline of events.
* **Calls**: Call history will appear once this contact has been called, logging detailed records of each attempt.
* **Campaigns**: Add this contact to a campaign to start reaching out, or view which campaigns they are already assigned to.
* **Notes**: A space for any manual notes, observations, or context gathered during interactions.
# Build your first phone agent in 5 minutes
Source: https://docs.ravan.ai/guides/create-first-agent
Step-by-step guide to create, test, and deploy your first AI phone agent.
Create a working phone agent by setting its role, voice, greeting, and deployment path. This guide keeps the setup focused so you can make your first test call in a few minutes.
![Agni Agents dashboard with existing agents and the option to create a new agent]()
## Before you start
You need access to an Agni workspace. If you have not signed in yet, follow [Authentication](/guides/authentication) first.
For live phone deployment, you also need a connected phone number. You can still create and test the agent in your browser without one.
Build the agent and define how it should handle calls.
Run a browser call before you send the agent to real callers.
Connect the agent to a number or campaign when it is ready.
## Create the agent
From the Agni dashboard, click **Agents** in the sidebar.
![Agents dashboard showing the list of configured agents]()
Click **+ New Agent** to open the agent builder.
The builder gives you a prompt editor, model controls, voice settings, and test tools in one workspace.
![Agni agent builder with the prompt editor and configuration panels]()
In the prompt editor, describe the agent's role, tone, goal, and boundaries.
Use this starter prompt for your first test:
```text theme={null}
You are Ava, a helpful phone agent for a dental clinic.
Your goal is to greet callers, understand why they are calling, and help them book an appointment.
Ask one question at a time.
Keep responses under two sentences.
If the caller asks for medical advice, explain that a dentist will help them during the appointment.
Confirm the caller's name, preferred date, preferred time, and phone number before ending the call.
```
Open the model selector and choose the model you want the agent to use.
For a first agent, choose the default recommended model unless you already know you need a faster or more specialized option.
![Model selector in the Agni agent builder]()
Choose a voice that matches the caller experience you want.
Click a voice to preview it, then select it for the agent.
![Voice picker showing available voices for an Agni agent]()
Open the **Welcome Message** settings and choose how the agent starts the call.
For your first agent, use a direct greeting:
```text theme={null}
Hi, this is Ava from Bright Dental. How can I help you today?
```
![Welcome message settings for an Agni agent]()
Keep the first version small. Add tools, knowledge bases, and advanced call handling after the agent can complete one simple conversation well.
## Test the agent
Use a browser call before connecting the agent to a phone number. This helps you catch prompt issues without spending telephony credits.
![Testing panel for running web and phone calls with an Agni agent]()
In the agent builder, open the testing panel.
Select **Web Call**, then start the call from your browser.
Speak like a real caller. For example:
```text theme={null}
Hi, I need to book a cleaning for next Tuesday afternoon.
```
Check whether the agent asked for the right details, stayed on task, and ended the call clearly.
If the agent gives long answers, add a prompt rule such as `Keep responses under two sentences.` If it skips required details, list those details explicitly in the prompt.
## Deploy the agent
Once the browser test works, connect the agent to a real calling path.
Open [Phone Numbers](/guides/phone-numbers) and buy, import, or connect a number.
![Phone Numbers dashboard showing connected phone numbers]()
For incoming calls, create an inbound rule and assign the phone number to your new agent. See [Inbound Calls](/guides/inbound-calls) under Campaigns for the full setup.
For outbound calls, add the agent to an outbound workflow after you have contacts and caller ID ready. See [Outbound](/guides/campaigns) under Campaigns for the workflow.
Call the number or launch a small test campaign. Confirm that the agent answers, follows the prompt, and captures the outcome you expect.
## Next steps
Configure tools, speech settings, memory, and post-call extraction.
Improve how your agent handles edge cases and caller intent.
Buy, import, and manage numbers for live calling.
Explore REST API endpoints for programmatic agent workflows.
# Dashboard Overview
Source: https://docs.ravan.ai/guides/dashboard
Your central command center for monitoring agent performance, tracking usage, and navigating your Agni workspace.
Once you log in, you are greeted by the Agni Dashboard. This is your central command center for monitoring agent performance, tracking usage, visualizing live traffic, and navigating your voice AI infrastructure.
![Agni Dashboard Overview]()
***
## At-a-Glance Metrics
At the top of your dashboard, you can quickly assess the high-level health and performance of your voice agents in real time:
Displays the aggregate conversational minutes consumed by your organization.
Displays the total number of AI agents currently active within your organization.
Shows the number of real-time, concurrent calls currently happening through your organization.
Shows the total amount of credits burned or consumed by your organization to date.
Highlights the overall percentage of calls made through the organization that successfully achieved their objective.
Displays the total number of customers that have been successfully converted during interactions.
***
## Live Visualizations & Analytics
The center of the dashboard provides a suite of interactive widgets to help you monitor system load and campaign outcomes dynamically.
A live 3D visualization showing exactly where in the world your active calls are currently taking place. Useful for understanding your geographic distribution.
Track how many calls and minutes have been spent over a specified period. Toggle between **Day**, **Week**, or **Month** views to spot patterns.
A detailed breakdown displaying the number of Total Outbound Calls, Total Failed Calls, Total Success Calls, and overall Total Calls.
Shows the total call volume for the current day, categorized by outbound, inbound, and web calls.
A quick view of your currently active agents and the respective number of calls they have handled.
Highlights the countries that have received the most calls or where you have initiated the highest call volume.
***
## Quick Actions
Located at the bottom of the dashboard, the **Quick Actions** panel provides one-click access to your most common operational workflows:
Build a new AI assistant.
Launch outbound calls.
Import or create users.
Provision a phone number.
***
## Workspace Navigation
The left sidebar is your primary map for navigating your Agni workspace. It is divided into focused sections:
Your daily operational views and agent configurations.
* **[Dashboard](/guides/dashboard):** Your high-level overview and metrics.
* **[Agents](/guides/agents):** Create, update, and deploy your AI agents.
* **[Knowledge Base](/guides/knowledge-base):** Manage the data and documents your agents use for context.
Build and tune agent behavior.
* **[Tools](/guides/tools):** Configure functions, actions, and integrations used by agents.
* **[Prompt Engineering](/guides/prompt-engineering):** Design prompts, guardrails, and response behavior.
Configure inbound and outbound calling workflows.
* **[Inbound Calls](/guides/inbound-calls):** Configure routing for incoming traffic.
* **[Outbound](/guides/campaigns):** Manage and monitor outbound calling workflows.
Detailed tracking and relationship management.
* **[All Call History](/guides/calls):** Review detailed call logs, transcripts, and session data.
* **[Appointments](/guides/appointments):** Manage booked calendar events and scheduling.
* **[Contacts](/guides/contacts):** Manage your CRM and address book.
* **[Integration](/guides/Integration):** Connect third-party systems and data flows.
The backend infrastructure of your workspace.
* **[Phone Numbers](/guides/phone-numbers):** Buy, import, and release phone numbers.
* **[Billing](/guides/billing):** Manage your subscription, credits, and invoices.
# Enterprise plan
Source: https://docs.ravan.ai/guides/enterprise-plan
Private onboarding and appointment booking for enterprise customers.
VVIP access
Enterprise concierge
For enterprise teams, we provide private onboarding, deployment guidance, and executive support.
Book a dedicated consultation with our enterprise team.
# Error codes
Source: https://docs.ravan.ai/guides/error-codes
Understand call failure errors, SIP status codes, Twirp wrappers, and the recommended next step for each failure.
# Error codes
Use this page to understand why a call failed and what action to take next. Call failures usually come from the telephony layer, so the most useful value is the **SIP status code** shown in the call details.
Twirp and HTTP codes may appear in technical details. These describe how the LiveKit API returned the failure. The SIP status explains the actual phone-call outcome.
***
## How to read call errors
When an outbound call fails, the call detail page may show an error like:
```text theme={null}
480: Temporarily Unavailable
```
Technical details may include a Twirp wrapper like:
```text theme={null}
TwirpError(code=resource_exhausted, status=429, metadata={
"sip_status_code": "480",
"sip_status": "Temporarily Unavailable"
})
```
In this example:
| Field | Meaning |
| ------------------------- | ------------------------------------------------------ |
| `480` | SIP status code. This is the main call failure reason. |
| `Temporarily Unavailable` | SIP status text shown by the telephony provider. |
| `resource_exhausted` | Twirp error code returned by the LiveKit API. |
| `429` | HTTP status for the Twirp response. |
***
## Call failure codes
| SIP code | Status | What it means | Recommended action | Agni tag |
| -------: | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------ |
| `480` | Temporarily Unavailable | The callee could not receive the call right now. The phone may be off, unreachable, out of coverage, or temporarily unable to accept calls. | Try again later. If it repeats, verify the number and carrier reachability. | `call_status:User Unavailable` |
| `486` | Busy Here | The callee is busy, already on another call, or the line rejected the call because it is occupied. | Try again later or call another number for the same contact. | `call_status:User Busy` |
| `408` | Request Timeout | The call timed out before the network or callee responded. | Try again. If it repeats, confirm the number and check telephony provider routing. | Not tagged automatically |
| `403` | Forbidden | The call was blocked by permission, routing, geo-permission, or provider policy. | Check phone number permissions, SIP trunk settings, and allowed destination countries. | Not tagged automatically |
| `404` | Not Found | The number or route could not be found by the carrier or telephony provider. | Confirm the phone number is valid and in E.164 format. | Not tagged automatically |
| `487` | Request Terminated | The call attempt was cancelled before it connected. | Retry the call. Check whether the campaign or user cancelled the attempt. | Not tagged automatically |
| `500` | Server Error | A provider or telephony service returned an internal error. | Retry after a short delay. Contact support if the issue continues. | Not tagged automatically |
| `503` | Service Unavailable | The carrier or telephony service was temporarily unavailable. | Retry later. Check provider status if many calls fail at once. | Not tagged automatically |
| `603` | Decline | The callee or carrier declined the call. | Try again later or use another contact method. | Not tagged automatically |
***
## Twirp error wrapper
Some call failures are returned through a Twirp error wrapper. For call troubleshooting, use the SIP metadata first.
| Twirp code | HTTP status | What it usually means in call failures |
| -------------------- | ----------: | ----------------------------------------------------------------------------------------------------------------------------- |
| `resource_exhausted` | `429` | LiveKit returned the SIP failure through a resource-exhausted response. Check `sip_status_code` and `sip_status` in metadata. |
| `unauthenticated` | `401` | The LiveKit API credentials were missing or invalid. Check `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET`. |
| `permission_denied` | `403` | The credentials are valid, but the request is not allowed. Check permissions and SIP trunk access. |
| `not_found` | `404` | The requested room, trunk, participant, or API route was not found. |
| `unavailable` | `503` | The LiveKit API or a dependent service was temporarily unavailable. Retry later. |
| `internal` | `500` | An internal service error occurred. Retry and contact support if it continues. |
Agni currently adds automatic call-status tags for `480 Temporarily Unavailable` and `486 Busy Here`. Other errors may still appear in technical details, but they are not mapped to custom call-status tags yet.
***
## What to include when contacting support
When you contact support about a failed call, include:
* The call ID or session ID
* The phone number or contact involved
* The visible error code and status
* The Twirp code and HTTP status, if shown
* The timestamp of the failed call
This helps support identify whether the issue came from the number, carrier, SIP trunk, LiveKit API, or Agni configuration.
# Inbound Calls
Source: https://docs.ravan.ai/guides/inbound-calls
Connect phone numbers to AI agents with dispatch rules so your agents automatically answer incoming calls.
The **Inbound Calls** page in the **Campaigns** section is where you connect the phone numbers you own to the AI agents you have built. By creating **Dispatch Rules**, you dictate exactly which agent answers the phone when a customer dials a specific number.
![Agni Inbound Calls Dashboard]()
***
## Prerequisites
Before creating dispatch rules, make sure you have:
You need an active, configured agent to answer the phone.
You must have a purchased or imported phone number available in your workspace.
***
## Create an Inbound Campaign
Setting up a new inbound campaign (dispatch rule) takes only a few clicks. Once configured, the route becomes **live immediately** after creation.
Under **Incoming Calls To**, click the dropdown and select the phone number the public will dial. If you have no numbers yet, follow the **buy one first** link.
Under **Routed To Agent**, click the dropdown and select the AI agent you want to handle the incoming calls.
Expand the **Schedule & Rules** section to control when and how inbound calls are handled:
| Setting | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Timezone** | The timezone used to interpret all time-window settings. |
| **Max Concurrent Calls** | Maximum simultaneous live calls for this route (Range: 1–10). |
| **Start Date** | The date from which this inbound route starts accepting calls. |
| **End Date** | The date on which this route stops accepting calls. |
| **Call Window Start / End** | Restrict calls to a specific daily time range (e.g., 09:00–18:00). Leave blank to allow calls at any time. |
| **Active Days** | Toggle individual days of the week (Mon–Sun) on which the route is active. |
Click the **+ Create Route** button to activate the campaign. Your agent is now live and will start handling inbound calls immediately.
**Strict 1-to-1 Mapping:** You can only create **one** inbound call route per phone number. If you want to assign a new agent to a number that is already in use, you must first complete or delete the previous inbound call rule.
***
## Inbound Route Detail View
Once a dispatch rule is created, it will appear in your **Inbound Call Rules** list. Clicking on a specific active rule opens the detailed Route Dashboard. This gives you a comprehensive overview of how that specific number is performing.
![Inbound Route Detailed Overview showing metrics and schedule]()
The detail view provides several key pieces of information:
* **Identity & Routing:** Quickly verify the **Assigned Agent**, the specific **Agent ID**, and the designated **Phone Number**.
* **Performance Metrics:** Monitor volume at a glance with counters for **Total Completed** calls, calls currently **Live In Progress**, and the total number of **Recent Calls**.
* **Schedule & Status:** The Schedule block confirms when the route was **Created**, when it ended (or if it is **Still active**), and provides the unique **Dispatch Rule ID**.
* **Recent Calls Log:** A dedicated table at the bottom of the page displays a live feed of all the calls that have recently come through this specific inbound route.
***
## Common Routing Patterns
The simplest setup. Buy a number, assign it to an agent, and you're live. Ideal for a single product line or department.
Buy separate numbers for sales, support, and billing. Create a dispatch rule for each, routing to specialized agents with different prompts and tools.
Use the **Call Window Start/End** and **Active Days** settings to restrict when your agent answers calls. For example, set window 09:00–18:00 on Mon–Fri to only route calls during business hours.
Use unique phone numbers for different marketing campaigns or ad channels. Route each to the same agent but use dynamic variables to track which campaign the caller came from.
***
## API Reference
To manage phone numbers and agents programmatically, refer to the following API endpoints:
List, buy, and manage the phone numbers available for routing.
Retrieve the list of your configured AI agents to use in dispatch rules.
# Knowledge Base
Source: https://docs.ravan.ai/guides/knowledge-base
Give your voice agents domain expertise with RAG-powered knowledge bases. Upload documents, configure retrieval, and improve answer accuracy.
# Knowledge Base (RAG)
Knowledge bases let your voice agents answer questions using your own data — product catalogs, FAQs, policies, pricing sheets, and more. Powered by Retrieval-Augmented Generation (RAG), your agent searches your knowledge base in real-time during calls to give accurate, contextual answers.
***
## How It Works
Give your knowledge base a name and choose whether to enable Auto Refresh for URL sources.
Add content via Text, URL, or File. Agni indexes your content automatically after each source is added.
Use the built-in Playground to query your knowledge base and verify it returns the right information before going live.
Open your agent in the agent builder and select the knowledge base from the Knowledge Base section.
***
## Creating a Knowledge Base
Navigate to **Knowledge Base** in the sidebar and click **+ Create Knowledge Base**.
![Knowledge Base page with no knowledge bases and Create Knowledge Base button]()
A modal will appear with two fields:
![Create Knowledge Base modal with Name field and Auto Refresh toggle]()
| Field | Description |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| **Name** | A label for your knowledge base (e.g., "Product Support KB") |
| **Auto Refresh** | When enabled, Agni automatically re-crawls URL sources periodically to keep content up to date |
Click **Create** to create the knowledge base. You'll be taken to the knowledge base detail page.
***
## Adding Sources
After creating a knowledge base, click **+ Add Source** to add content.
![Knowledge base detail page with no sources and Add Source button]()
The **Add Source** modal offers three source types:
![Add Source modal showing Text, URL, and File tabs with URL tab selected]()
Paste raw text or Q\&A content directly. Ideal for FAQs, policies, and short reference documents.
Enter a URL and click **Scan** to discover all linked pages. Select which URLs to index — you can select up to 500 at a time — then click **Add Sources**.
Use **Select All** to include all discovered URLs, or manually check individual pages.
Upload PDF, TXT, or other supported document formats. Agni extracts and indexes the content automatically.
Once added, your sources appear in the **Sources** tab with their type, indexing status, and date added.
![Knowledge base Sources tab showing an indexed URL source with COMPLETE status]()
| Column | Description |
| ---------- | ------------------------------------------------------- |
| **Source** | The source name or URL |
| **Type** | `URL`, `Text`, or `File` |
| **Status** | `COMPLETE` once indexed; shows progress during indexing |
| **Added** | Date the source was added |
***
## Managing Your Knowledge Base
From the knowledge base detail page, you have access to the following actions:
| Action | Description |
| -------------- | --------------------------------------------------------------------------- |
| **Refresh** | Manually re-crawl and re-index all URL sources |
| **Exclusions** | Add URL patterns to exclude from indexing (e.g., `/admin/*`, `/internal/*`) |
| **Delete** | Permanently delete the knowledge base |
The status badge in the top right (e.g., **READY**) shows whether the knowledge base is indexed and available. **Auto-refresh** is shown next to it when enabled.
***
## Testing with Playground
Click the **Playground** tab inside your knowledge base to test retrieval before connecting it to an agent.
![Knowledge Playground tab showing test question prompts and a chat input field]()
Type any question in the input field and Agni will return the most relevant information from your knowledge base. Suggested questions are shown to help you get started quickly.
The Playground performs a raw RAG query — it does not use any agent. It's only meant to verify what information your knowledge base contains.
***
## Connecting to an Agent
To use a knowledge base during calls, you need to attach it to an agent.
1. Go to **Agents** and open the agent you want to configure
2. Scroll down to the **Knowledge Base** section in the agent builder
3. Select the knowledge base you created
![Agent builder Knowledge Base section showing a knowledge base selected with 1 source]()
Once selected, the agent will automatically search the knowledge base during calls whenever a caller asks a relevant question.
***
## Content Best Practices
Structure content as questions and answers. This matches how callers phrase questions and improves retrieval accuracy.
Each source should cover one topic. A focused 500-word FAQ retrieves better than a 10,000-word manual.
Don't just list facts — include enough context for the agent to form natural, complete responses.
Stale information leads to wrong answers. Auto Refresh keeps URL sources current without manual re-indexing.
### Example: Good vs Bad Content
**Bad** (too terse):
```text theme={null}
Hours: 9-6 M-F
Returns: 30 days
Shipping: Free over $50
```
**Good** (natural, contextual):
```text theme={null}
Q: What are your business hours?
A: Our office is open Monday through Friday from 9:00 AM to 6:00 PM Eastern Time. We are closed on weekends and major holidays. For urgent matters outside business hours, you can leave a voicemail and we'll return your call the next business day.
Q: What is your return policy?
A: We offer a full refund within 30 days of purchase, no questions asked. After 30 days, we can offer store credit or an exchange. To initiate a return, the customer needs their order number and the email used at checkout.
```
***
## API Reference
### Add a document
```bash theme={null}
curl -X POST https://api.ravan.ai/api/v1/rag/documents \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Product FAQ",
"content": "Q: What are your business hours?\nA: We are open Monday through Friday, 9am to 6pm EST.",
"metadata": {
"category": "faq",
"last_updated": "2026-03-28"
}
}'
```
### Query the knowledge base
```bash theme={null}
curl -X POST https://api.ravan.ai/api/v1/rag/query \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "What is the return policy?",
"top_k": 3
}'
```
### Crawl a URL
```bash theme={null}
curl -X POST https://api.ravan.ai/api/v1/rag/discover \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourcompany.com/faq",
"depth": 2
}'
```
### Full endpoint reference
| Action | Endpoint | Description |
| ------------ | -------------------------------- | ------------------------------- |
| **Upload** | `POST /api/v1/rag/documents` | Add or update a document |
| **Get** | `GET /api/v1/rag/documents/{id}` | Retrieve a specific document |
| **List** | `GET /api/v1/rag/documents` | List all documents |
| **Query** | `POST /api/v1/rag/query` | Search the knowledge base |
| **Refresh** | `POST /api/v1/rag/refresh` | Re-index all documents |
| **Discover** | `POST /api/v1/rag/discover` | Auto-discover content from URLs |
***
## Troubleshooting
Your sources may be too broad. Split large documents into focused topics — each source should cover one subject area.
The content may not match how callers phrase their questions. Add multiple phrasings of common questions. Use the Playground to test retrieval directly.
Add more specific content — exact product names, numbers, dates, and policies. The more concrete your knowledge base, the more precise the answers.
Enable **Auto Refresh** when creating the knowledge base, or click **Refresh** manually from the knowledge base detail page to re-crawl all URL sources.
# Organizations and roles
Source: https://docs.ravan.ai/guides/organizations-and-roles
Understand how Agni organizations, admins, and users work together.
An organization is the main workspace for your Agni account. It contains your agents, Campaigns (inbound and outbound), phone numbers, knowledge bases, integrations, billing, and team members.
Think of the organization as the business account. Admins manage the account, and users work inside it.
***
## What is an organization?
An organization is the top-level container for everything your team builds in Agni.
Each organization can have its own:
* Agents
* Campaigns (Inbound and Outbound)
* Knowledge bases
* Contacts
* Phone numbers
* Integrations
* Billing and credits
* Team members
The first person who creates the account becomes the initial admin for that organization.
Admins can create and manage organizations from their account when their plan or account access supports multiple organizations.
***
## Admin role
Admins control the organization and its team access. This role is best for owners, managers, or technical leads who need full workspace control.
Admins can:
* Manage organization settings
* Invite users
* Add another admin
* Create and manage agents
* Manage Campaigns (Inbound and Outbound)
* Create and manage knowledge bases
* Manage integrations
* View usage and analytics
* Manage billing and credits
Use the admin role for people who should be able to manage the workspace, not only operate inside it.
***
## User role
Users are team members who work inside an organization. This role is best for employees or operators who need to build and manage workflows without controlling the full account.
Users can usually:
* Create and update agents
* Manage Campaigns (Inbound and Outbound)
* Create and manage knowledge bases
* Work with contacts
* Review calls and performance data
Users have restricted access to account-level controls. For example, users cannot buy credits, invite new users, or add another admin.
Exact permissions can vary by workspace configuration. If a user cannot access a feature, ask an admin to review their role and organization access.
***
## Role comparison
| Capability | Admin | User |
| --------------------------------------- | ----- | ------- |
| Manage organization settings | Yes | Limited |
| Invite team members | Yes | No |
| Add another admin | Yes | No |
| Create agents | Yes | Yes |
| Manage Campaigns (Inbound and Outbound) | Yes | Yes |
| Create knowledge bases | Yes | Yes |
| Buy credits | Yes | No |
| Manage billing | Yes | No |
***
## When to use each role
Use **Admin** for people who manage the business account, billing, team access, and organization settings.
Use **User** for employees who need to build agents, run outbound workflows, manage inbound routing, or maintain knowledge bases without changing billing or team permissions.
***
## Next steps
Manage organization settings, profile details, API keys, and team access.
Build your first agent inside your organization.
# Phone Numbers
Source: https://docs.ravan.ai/guides/phone-numbers
Provision, manage, and configure the telephony infrastructure for your AI agents—including Twilio, managed accounts, and custom SIP providers.
The **Phone Numbers** page is your control center for telephony. Before you can buy numbers or route inbound and outbound calls, you must configure your underlying telephony provider.
Agni natively supports **Twilio** (both Bring-Your-Own-Account and Managed options) as well as **Custom Providers** via SIP trunking.
![Choose Your Account Strategy]()
***
## First-Time Setup: Choose Your Strategy
When you access the Phone Numbers tab, you must first choose how you want to connect and manage your telephony infrastructure from the left-hand **Providers** menu.
### Option 1: Custom Provider (SIP Integration)
Choose this option if you want to bring your own telephony carrier (BYOC) using SIP trunking. This allows you to route calls from any external provider directly into your Agni agents.
![Custom Provider SIP Configuration]()
Navigate to the **Custom Provider** tab under the Providers menu.
Input the **Phone Number** you are importing (including the country code) and assign it a **Friendly Name** for easy identification within your workspace.
To successfully route inbound calls to your Agni agents, configure your external provider to point to Agni's infrastructure using our dedicated Termination URI:
`sip:68uajga988j.sip.livekit.cloud`
Input this into the **Termination URI** field.
Enter your **SIP Username** and **SIP Password** to authenticate the connection securely.
Click **Import Custom Number** to finalize the configuration. The number will immediately become available in your active inventory.
### Option 2: Twilio - Your Own Account (BYOT)
Choose this option if you already have a Twilio account and want full ownership, compliance control, and direct billing from Twilio.
Under the **Twilio** provider tab, click **Choose this option** under the "Your Own Account" card.
A confirmation modal will appear. Click **Continue Setup** to lock in your configuration.
![Confirm BYOT Selection]()
Provide a **Friendly Name** for your integration, along with your Twilio **Account SID** and **Auth Token**. These can be found in your [Twilio Console](https://console.twilio.com). Click **Connect Account**.
![Enter Twilio Credentials]()
**When to choose BYOT:** If you need regulatory compliance control, already have Twilio numbers, want to keep telephony billing separate from Agni, or need access to Twilio's full feature set.
### Option 3: Twilio - Managed Account
Choose this option if you want a zero-configuration experience. Agni will manage the underlying infrastructure, and telephony usage will be deducted directly from your Agni credit balance.
Under the **Twilio** provider tab, click **Choose this option** under the "Managed Account" card.
Because Agni handles the billing and compliance for Managed Accounts, you must review and accept the telephony terms.
* **Service Selection:** The Managed Twilio selection is permanent and cannot be changed without administrative approval.
* **Credit-Based Subscription:** Services operate on prepaid credits. Unused credits expire at the end of each billing cycle.
* **Phone Number Renewal:** Phone numbers must be renewed every 28 days. Failure to renew within the 48-hour window will result in permanent number release.
* **Strict No Refund Policy:** All purchases are final. No refunds are issued for unused credits, missed renewals, service interruptions, or account termination.
![Telephony Terms and Conditions]()
Give your managed connection a **Friendly Name** to identify it in your workspace, then click **Connect Account** to finalize the setup.
**When to choose Managed:** If you want the fastest setup, don't have an existing provider, and prefer consolidated billing through Agni.
### Option 4: Indian Telephony
Choose this option if you need to provision Indian (+91) phone numbers. You will need to complete a KYC compliance process before you can buy numbers.
Under the **Indian Telephony** provider tab from the left menu.
Verify your mobile number to start the process.
Complete the KYC (Know Your Customer) compliance process. This is a regulatory requirement for provisioning Indian phone numbers.
Once approved, you can purchase Indian numbers.
* **Monthly fee** — ₹295/mo.
* **Outbound rate** — ₹0.60/min.
* **Inbound rate** — ₹0.60/min.
***
## Managing Phone Numbers
Once your account strategy is configured, you will unlock the main Phone Numbers dashboard.
![Phone Numbers Dashboard]()
### Buy a New Number (Twilio Only)
If you are using a Twilio integration, use the left panel to search for and purchase new phone numbers directly into your workspace:
Select your desired **Country** from the dropdown menu to load available inventory.
Use the search bar to filter for specific area codes, prefixes, or vanity patterns.
Review the costs associated with the number:
* **Monthly fee** — Flat rate for owning the number (e.g., \$1.15/mo for US numbers).
* **Outbound rate** — Per-minute cost for calls your agent makes (e.g., \$0.0945/min).
* **Inbound rate** — Per-minute cost for calls your agent receives (e.g., \$0.0085/min).
Select a number and click **Buy Number** to provision it immediately to your workspace.
### Owned Numbers
The right panel displays your active inventory, including any numbers you have purchased or imported via a Custom Provider. Any number listed here is immediately ready to be used in your [Inbound Calls](/guides/inbound-calls) dispatch rules or as a Caller ID for outbound campaigns.
Phone numbers on Managed Accounts must be renewed every 28 days. Set a reminder or monitor your [Billing](/guides/billing) page to avoid accidental number loss.
***
## API Reference
Agni's Telephony API allows you to automate number provisioning and management directly from your backend.
Search the inventory for numbers available to purchase in any country.
Programmatically purchase a number and add it to your workspace.
Retrieve the active inventory of phone numbers connected to your account.
Release a phone number or remove a custom provider connection.
# Prompt Engineering
Source: https://docs.ravan.ai/guides/prompt-engineering
Write effective system prompts for your Agni voice agents. Templates, best practices, and industry-specific examples.
# Writing Effective Agent Prompts
Your system prompt is the single most important factor in how your voice agent performs. A well-crafted prompt turns a generic AI into a specialist that handles calls like your best employee.
***
## Prompt Structure
Every effective agent prompt follows this structure:
Who is the agent? Give it a name, role, and personality.
*"You are Sarah, a friendly appointment coordinator at Bright Smile Dental. You're warm, professional, and efficient."*
What should the agent accomplish on every call?
*"Your goal is to schedule, reschedule, or cancel dental appointments. Always confirm the patient's name, preferred date/time, and the type of visit."*
Step-by-step behavior rules and conversation flow.
*"1. Greet the caller warmly. 2. Ask how you can help today. 3. If scheduling, check availability. 4. Confirm all details before booking."*
What the agent should NOT do.
*"Never provide medical advice. Never share other patients' information. If asked about billing, transfer to the billing department."*
***
## Prompt Template
Use this as a starting point for any agent:
```text theme={null}
You are [NAME], a [ROLE] at [COMPANY]. You are [PERSONALITY TRAITS].
## Your Goal
[PRIMARY OBJECTIVE]
## How to Handle Calls
1. [STEP 1 - Usually greeting]
2. [STEP 2 - Identify caller needs]
3. [STEP 3 - Take action]
4. [STEP 4 - Confirm and close]
## Important Rules
- [RULE 1]
- [RULE 2]
- [RULE 3]
## When to Transfer
Transfer the call to a human agent if:
- [CONDITION 1]
- [CONDITION 2]
## Tone & Style
- Speak naturally and conversationally
- Keep responses concise (1-2 sentences at a time)
- Use the caller's name when confirmed
```
***
## Dynamic Variables
Personalize every call with dynamic variables using `{{variable_name}}` syntax:
```text theme={null}
You are {{agent_name}}, calling on behalf of {{company_name}}.
You're reaching out to {{contact_name}} about their {{appointment_type}}
scheduled for {{appointment_date}}.
```
Pass values via the API when initiating a call:
```bash theme={null}
curl -X POST https://api.ravan.ai/api/v1/calls/ \
-H "X-Api-Key: YOUR_API_KEY" \
-d '{
"agent_id": "your-agent-id",
"to_number": "+1234567890",
"variables": {
"contact_name": "John",
"company_name": "Bright Smile Dental",
"appointment_date": "March 30 at 2pm"
}
}'
```
***
## Industry Examples
```text theme={null}
You are Alex, a customer support specialist at TechCo. You're patient,
empathetic, and solution-oriented.
## Your Goal
Help customers resolve their issues on the first call. If you can't
resolve it, create a support ticket and set expectations.
## Conversation Flow
1. Greet the customer and ask how you can help
2. Listen carefully and identify the issue
3. Check if there's a known solution
4. Walk them through the fix step by step
5. Confirm the issue is resolved
6. Ask if there's anything else
## Rules
- Never blame the customer
- Don't say "I don't know" — say "Let me look into that for you"
- If the issue requires engineering, create a ticket and provide a reference number
- Apologize sincerely for any inconvenience
## Transfer Conditions
- Billing disputes over $500
- Account security concerns
- Requests for a manager
```
```text theme={null}
You are Maya, an appointment coordinator at Wellness Center. You're
cheerful, organized, and helpful.
## Your Goal
Book, reschedule, or cancel appointments efficiently while making
the caller feel valued.
## Conversation Flow
1. Greet warmly: "Hi! Thanks for calling Wellness Center. I'm Maya."
2. Ask: "Are you looking to book a new appointment, reschedule, or cancel?"
3. For new bookings: Ask for name, preferred date/time, and service type
4. Check availability and offer alternatives if needed
5. Confirm all details and provide a confirmation number
6. Ask if there's anything else
## Rules
- Always confirm spelling of the caller's name
- Offer at least 2 time slot alternatives
- Send confirmation via SMS after booking
- Don't book outside business hours (Mon-Fri 8am-6pm)
```
```text theme={null}
You are Jordan, a business development representative at SaaS Corp.
You're confident, consultative, and respectful of people's time.
## Your Goal
Qualify leads and book discovery calls with the sales team. Never
hard-sell — focus on understanding if there's a genuine fit.
## Conversation Flow
1. Introduce yourself briefly and state why you're calling
2. Ask if they have 2 minutes to chat
3. If yes: Ask about their current solution and pain points
4. Share 1-2 relevant benefits of your product
5. If interested: Book a demo with the sales team
6. If not interested: Thank them and offer to follow up later
## Rules
- If they say "not interested," respect it immediately
- Never call the same person more than twice
- Don't discuss pricing — leave that for the sales team
- Keep the call under 3 minutes unless they're engaged
```
```text theme={null}
You are Dr. Chen's office assistant, following up with patients after
their visit. You're caring, professional, and thorough.
## Your Goal
Check on patient recovery, remind about medication, and schedule
follow-up appointments if needed.
## Conversation Flow
1. Identify yourself: "Hi, this is a follow-up call from Dr. Chen's office."
2. Confirm you're speaking with the right patient
3. Ask how they're feeling since their visit on {{visit_date}}
4. Ask about medication: "Are you taking {{medication}} as prescribed?"
5. If any concerns: Recommend scheduling a follow-up
6. Remind about next appointment if already scheduled
## Rules
- NEVER provide medical advice or diagnoses
- If patient reports emergency symptoms, tell them to call 911 immediately
- All health information is confidential — verify identity first
- Transfer to a nurse if patient has clinical questions
```
***
## Voice Models
Agni offers two real-time voice models optimized for different use cases:
| Model | Best For | Strengths |
| ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Thunder** | Complex conversations, nuanced decisions, emotional intelligence | Deeper reasoning, natural turn-taking, handles multi-step conversations with ease. Ideal for sales, healthcare, and high-value calls. |
| **Thunder Lite** | High-volume calls, simple tasks, fast responses | Ultra-low latency, cost-efficient, great for appointment booking, confirmations, and data collection at scale. |
**When to use which?** Start with **Thunder** for any customer-facing call where conversation quality matters. Use **Thunder Lite** when you need speed and volume — like outbound confirmation calls or simple FAQ handling.
**Temperature guide:**
* **0.1 - 0.3** — Strict, deterministic. Good for data collection and form-filling.
* **0.4 - 0.6** — Balanced. Good for customer support and appointment booking.
* **0.7 - 0.9** — Creative, varied. Good for sales and casual conversations.
***
## Pronunciation Guide
Voice agents read text aloud, so how you write things in your prompt directly affects how they sound. Use these techniques to make your agent pronounce emails, phone numbers, dates, and other tricky content naturally.
### Email Addresses
Write emails exactly as you want them spoken. Use "at" and "dot" in plain words.
```text theme={null}
❌ Don't write: info@ravan.ai
✅ Write: support at ravan dot A I
❌ Don't write: john.doe@gmail.com
✅ Write: john dot doe at gmail dot com
```
In your prompt instructions, add: *"When reading email addresses aloud, say 'at' for the @ symbol and 'dot' for periods. Spell out the domain letter by letter if it's uncommon."*
### Phone Numbers
Break phone numbers into natural spoken groups. Never read them as one big number.
```text theme={null}
❌ Don't write: +12125551234
✅ Write: 2 1 2, 5 5 5, 1 2 3 4
❌ Don't write: Call us at 8005551234
✅ Write: Call us at 800, 555, 1 2 3 4
```
Add this to your prompt:
```text theme={null}
When reading phone numbers, say each digit individually. Group them as:
area code (3 digits), then 3 digits, then 4 digits. Pause briefly
between each group.
```
### Dates & Times
Write dates the way you want them spoken — avoid numeric-only formats.
```text theme={null}
❌ Don't write: 03/28/2026
✅ Write: March 28th, 2026
❌ Don't write: DOB: 1990-05-15
✅ Write: Date of birth: May 15th, 1990
❌ Don't write: Appointment at 14:00
✅ Write: Appointment at 2 PM
```
Add this to your prompt:
```text theme={null}
Always say dates in full spoken form — for example, "March twenty-eighth,
twenty twenty-six." Never read dates as raw numbers like "oh three slash
twenty-eight." For times, use 12-hour format with AM or PM.
```
### Date of Birth
When collecting or confirming date of birth, instruct the agent to repeat it back clearly:
```text theme={null}
When confirming a date of birth, always repeat it back in full spoken form.
For example: "Just to confirm, your date of birth is January 5th, 1992 —
is that correct?"
If the caller says something like "oh one oh five ninety-two", interpret
it as January 5th, 1992 and confirm in full.
```
### Dollar Amounts & Numbers
```text theme={null}
❌ Don't write: $1250.00
✅ Write: twelve hundred and fifty dollars
❌ Don't write: Your balance is 49.99
✅ Write: Your balance is forty-nine dollars and ninety-nine cents
❌ Don't write: Reference #A1B2C3
✅ Write: Reference number: A as in Alpha, 1, B as in Bravo, 2, C as in Charlie, 3
```
### Addresses
Break addresses into natural spoken chunks:
```text theme={null}
❌ Don't write: 123 W 45th St, Ste 200, NY, NY 10036
✅ Write: 123 West 45th Street, Suite 200, New York, New York, 10036
When reading zip codes, say each digit: "one zero zero three six."
```
### Spelling Out Names & Codes
For anything that needs to be spelled out (confirmation codes, names, etc.):
```text theme={null}
Add to your prompt:
"When spelling out words or codes, use the NATO phonetic alphabet.
For example, spell 'BKNG42' as: Bravo, Kilo, November, Golf, Four, Two."
```
### General Pronunciation Tips
Add these instructions to any agent prompt for cleaner speech:
```text theme={null}
## Speech Rules
- Never read raw URLs, file paths, or code aloud
- Say "percent" not "%", "dollar" not "$", "and" not "&"
- For abbreviations like "Dr." say "Doctor", "St." say "Street"
- Spell out acronyms unless they're commonly spoken words (e.g., say "NASA" but spell out "C R M")
- When reading a list, pause briefly between items
- If you need to read a long number like an account number, group digits in sets of 3 or 4 with pauses
```
***
## Common Mistakes
Avoid these common prompt pitfalls:
| Mistake | Problem | Fix |
| ------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------- |
| Wall of text | Agent gets confused by too many instructions | Keep prompts under 500 words. Use bullet points. |
| No guardrails | Agent goes off-topic or makes promises it can't keep | Always define what the agent should NOT do. |
| Generic personality | Agent sounds robotic and impersonal | Give a specific name, role, and 2-3 personality traits. |
| No transfer rules | Caller gets stuck with no way to reach a human | Always define when to transfer to a live agent. |
| Long responses | Agent talks too much, caller loses interest | Instruct: "Keep responses to 1-2 sentences." |
| Ignoring edge cases | Agent fails on unexpected questions | Add a catch-all: "For questions outside your scope, offer to transfer." |
***
## Testing Your Prompt
After writing your prompt:
1. **Web Call Test** — Click "Start Web Call" in the agent builder to have a live conversation
2. **Edge Case Testing** — Try asking off-topic questions to test guardrails
3. **Tone Check** — Listen for natural, conversational speech vs robotic responses
4. **Transfer Test** — Verify the agent transfers correctly when conditions are met
5. **Iterate** — Refine based on real conversations. Small wording changes make big differences.
Contact [info@ravan.ai](mailto:info@ravan.ai) for prompt review and optimization advice.
# Workspace Settings
Source: https://docs.ravan.ai/guides/settings
Configure your organization, manage team access, secure your account, generate API keys, and connect third-party integrations.
The **Settings** menu is your central hub for administering your Agni workspace. To access it, click on your user profile in the bottom-left corner of the dashboard and select **Settings**.
![Navigate to Settings]()
***
## Organization & Profile
Manage the core identity of your workspace and your personal account details.
The **Organization** tab allows you to manage your top-level workspace settings.
* View your active **Organization ID** and current plan (you'll need the org ID for some API calls).
* Update your **Organization Name** and **Website**.
* Restrict access by defining **Allowed Email Domains** (comma-separated). Only users with matching email domains can be invited to your workspace.
* Set your default **Region** for data residency and latency optimization.
![Organization Settings]()
The **Profile** tab displays your current role (e.g., ADMIN) and registered email address. You can update your **First Name** and **Last Name** here.
![Profile Settings]()
***
## Security & Access
Secure your account and manage programmatic access to your voice infrastructure.
Protect your account from unauthorized access:
* **Change Password:** Update your current login credentials.
* **Two-Factor Authentication (2FA):** Add an extra layer of security to your account. Highly recommended for production workspaces.
* **Active Sessions:** Review all devices currently logged into your account. Use the **Revoke** button to instantly disconnect unrecognized or old sessions.
![Security Settings]()
Generate and manage the secret keys required to interact with the Agni REST API.
Click **+ New Key** to generate a token. The key is displayed once -- copy it immediately and store it securely.
Never expose API keys in client-side code, public repos, or browser-accessible files. If a key is compromised, delete it immediately and generate a new one.
![API Keys]()
Use your key in the `X-Api-Key` header:
```bash theme={null}
curl https://api.ravan.ai/api/v1/agents/ \
-H "X-Api-Key: YOUR_API_KEY"
```
***
## Team Management
Agni allows you to collaborate securely by inviting team members directly to your workspace.
The **Users** tab displays a complete directory of everyone with access to your organization, along with their assigned roles and permissions.
Navigate to the **Invite User** tab. Enter their **Email**, **First Name**, and **Last Name**, then click **Send Invitation**.
Invited users will receive an email containing a temporary password. They will be required to change this password upon their first successful login.
## API Reference
Once you have generated your API Keys or connected your integrations, you can begin automating your workflow.
Full REST API documentation with cURL, Python, and JavaScript examples.
Manage your GoHighLevel connections and appointments programmatically.
Manage your Cal.com connections and event types programmatically.
# Support
Source: https://docs.ravan.ai/guides/support
Contact Agni support, share the right troubleshooting details, and report urgent production outages.
# Support
If you need help with Agni, start with the support widget in the bottom right corner of the product. The widget is visible on every page in Agni, so you can open it from wherever you are working and send a message to the support team.
## Contact support
You can contact the Agni support team in either of these ways:
* Use the support widget in the bottom right corner of any page in Agni
* Email [info@ravan.ai](mailto:info@ravan.ai)
## What to include in your support ticket
Include the most helpful context so the team can investigate faster:
* Your Agni organization ID
* Your agent ID
* Your call session ID
* The issue you are facing
* The steps to reproduce the issue
* Screenshots of the issue
## Report an outage
If you are facing an urgent outage that is breaking your voice agent production traffic, report it from the call session directly:
Go to the **Call History** tab in Agni.
Open the call session that shows the outage or failed production traffic.
Click the **Report** button to submit the issue. The Agni team will review the outage report and act on it in a timely manner.
For urgent issues, include the affected call session ID and a short description of the production impact in your outage report.
# Tools & Functions
Source: https://docs.ravan.ai/guides/tools
Equip your AI agents with real-world capabilities—end calls, transfer to humans, navigate IVRs, and call external APIs during live conversations.
The **Functions** section inside the Agent Builder is where you define the specific actions your AI agents can perform during a live call. By attaching functions, you upgrade your agent from a conversational assistant to an active participant capable of executing real-world tasks.
To add a function to your agent, open the **Functions** dropdown in the right sidebar of the Agent Builder and click **+ Add Function**.
![Functions dropdown showing End Call, Transfer Call, IVR, and Custom Function]()
We provide four primary types of functions:
***
## 1. End Call
The **End Call** function allows the AI agent to politely and intentionally hang up the phone when a conversation has naturally concluded or a specific objective has been met.
![End Call configuration popup]()
**Configuration Fields:**
* **Name:** The internal identifier for the function (e.g., `end_call`).
* **Description:** A natural-language instruction telling the AI exactly when it should trigger this function (e.g., *"End the call after the user's appointment time is confirmed."*).
***
## 2. Transfer Call
The **Transfer Call** function allows the AI to seamlessly route an active caller to a different destination. We offer three different ways an agent can transfer a call:
### Static vs. Dynamic Transfers
* **Static:** Routes the caller to a single, predefined phone number.
* **Dynamic:** Allows you to provide a prompt instructing the LLM to choose between multiple numbers based on the user's input (e.g., *"Ask the user which department they want, then transfer the call to the corresponding number."*).
![Transfer Call settings showing Static and Dynamic options]()
![Dynamic Transfer prompt configuration]()
### Assign Human Agent (GoHighLevel Integration)
This powerful feature allows you to transfer calls directly to members of your GoHighLevel (GHL) team.
### Scheduling (Optional)
You can apply strict operating hours to your transfer functions. By selecting a **Timezone**, **Start Time**, and **End Time**, you ensure the call transfer will only execute if the call occurs within the specified window.
![Schedule block for timezone and active transfer hours]()
***
## 3. IVR / Press Digit
The **IVR / Press Digit** function empowers your agent to navigate automated phone menus (like pressing '1' for Support or '2' for Sales).
![IVR / Press Digit configuration]()
* **Pause Detection Delay (ms):** Controls exactly how long the agent waits in silence after speaking before it presses the required digit. The default is **1000ms**, giving the receiving system time to register the input.
***
## 4. Custom Functions
Custom functions let you integrate your agent directly with your own application ecosystem. We support two execution types:
![Custom Function API configuration screen]()
### Custom (Server-Side API)
Configure a direct HTTP webhook call that the agent triggers mid-conversation.
* **API Endpoint:** Define the HTTP method (GET, POST, PUT, PATCH, DELETE) and your secure `https://` URL.
* **Timeout (ms):** Set maximum execution limits to prevent the agent from stalling.
* **Headers & Query Parameters:** Pass required authorization keys or specific identifiers.
* **Parameters (JSON Schema):** Define the strict JSON payload format the LLM must generate to fulfill the API request.
### Client Function
Execute functions strictly on the client side. Simply provide a **Name**, a **Description** of what the tool does, and an optional **JSON Schema** defining the parameters the LLM will pass directly to your client application.
***
## Extended Agent Capabilities
Beyond tools, the Agent Builder sidebar includes several dedicated panels to refine how your agent operates and connects with external data:
### Calendars & Human Agents
* **Calendars:** Link your agent to **Lead Connector (GoHighLevel)** or **Cal.com** so it can autonomously negotiate times and book appointments.
* **Assign Human Agent:** Quickly bind specific GHL users (configured via the "My Staff" step above) directly to the agent's workflow.
### Knowledge Base
Attach a custom dataset to your agent. This grants the AI access to your company’s specific documents, ensuring it knows your product details intimately and can answer questions without hallucinating.
### Speech Settings
Control the exact auditory experience of the call:
* **Background Sound:** Layer in realistic ambient noise, choosing from *Office, City, Forest, Crowded, Keyboard,* or *Hold* music.
* **Interruption Sensitivity:** Adjust how easily the caller can talk over the agent (e.g., `0.9`).
* **Reminder Message Frequency:** Define how many seconds of dead air should pass, and how many times the AI should attempt to re-engage, before speaking a custom **Reminder Message**.
### Call Settings & Memory
* **Telephony Rules:** Toggle **Voicemail detection**, set **Silence timeouts** (e.g., 10s), enforce a hard **Max duration** limit (e.g., 30 min) to control costs, and configure **Emergency fallback** to transfer the call to a backup number on failure.
* **Memory:** When enabled, the agent remembers specific details about users across both inbound and outbound calls. For example, if a caller provided their name in a previous interaction, the agent can access that context and greet them personally ("Hey Aryan, how are you?") on the next call.
### Post-Call Data Extraction
Automatically synthesize data the moment the call disconnects. You can configure the LLM to analyze **Sentiments** (Negative, Positive, Neutral) or draft a detailed **Summary** of the conversation to pass along to your CRM or a human agent.
# Troubleshooting
Source: https://docs.ravan.ai/guides/troubleshooting
Diagnose and fix common issues with Agni voice agents. Call failures, voice quality, integration problems, and performance tips.
# Troubleshooting
A quick reference for diagnosing and fixing the most common issues with Agni voice agents.
***
## Call Issues
**Check these in order:**
1. **Phone number active?** — Go to **Phone Numbers** in the dashboard. Ensure your number is active and not released.
2. **Agent status** — Verify the agent is set to `ACTIVE` (not paused or draft).
3. **Inbound dispatch rule** — For inbound calls, ensure a dispatch rule routes your phone number to the correct agent.
4. **Twilio balance** — If using BYOT, check your Twilio account has sufficient balance.
5. **Number region** — International calls may be blocked by default. Check Twilio geo-permissions.
**Common causes:**
* **Model too heavy** — Switch from `Thunder Emotion Lite` to `Thunder Emotion` for faster first response
* **Long system prompt** — Trim your prompt to under 500 words
* **Welcome message missing** — Set a `begin_message` so the agent speaks immediately on connection
* **Start speaker set to "user"** — If you want the agent to speak first, set `start_speaker` to `"agent"`
**For web calls:**
* Allow microphone permission in your browser
* Check you're using a supported browser (Chrome, Edge, Firefox)
* Disable browser extensions that block WebRTC
**For phone calls:**
* Test with a different phone to rule out device issues
* Check if the call connects but only one party can hear — this usually indicates a network/NAT issue on the telephony side
* **Max call duration** — Check `max_call_duration_ms` in agent settings. Default may be too short.
* **End on silence** — If `end_call_after_silence` is enabled, the agent hangs up during pauses. Increase the silence threshold or disable it.
* **Twilio limits** — BYOT accounts may have call duration limits. Check your Twilio console.
* **Network issues** — Intermittent connectivity on the caller's side causes drops.
* **Prompt too vague** — Add specific instructions and examples. See the [Prompt Engineering Guide](/guides/prompt-engineering).
* **Temperature too high** — Lower the temperature (0.3-0.5) for more deterministic responses.
* **Knowledge base stale** — Refresh your knowledge base if answers reference outdated information.
* **No guardrails** — Add explicit "do NOT" rules for topics the agent should avoid.
* **Transfer number format** — Use E.164 format: `+14155551234`
* **SIP address** — For SIP transfers, verify the SIP URI is correct and reachable
* **Tool configured?** — Ensure the Call Transfer tool is attached to the agent in the Functions tab
* **Trigger description** — The tool's trigger description must clearly define when to transfer
***
## Integration Issues
**GoHighLevel:**
* Re-authorize the OAuth connection in **Settings → Integrations**
* Verify the GHL calendar ID is correct
* Check that the GHL account has the Calendars permission enabled
**Cal.com:**
* Reconnect via **Settings → Integrations → Cal.com**
* Ensure the event type exists and is active in your Cal.com dashboard
* Check timezone settings match between Agni and Cal.com
* **URL accessible?** — Test your endpoint with `curl -X POST https://your-url.com/webhook`
* **HTTPS required** — Agni only sends webhooks over HTTPS
* **Check logs** — Look at your agent's webhook delivery logs in the dashboard
* **Return 200** — Your server must return HTTP 200 within 30 seconds or it's marked as failed
* See the [Webhooks Guide](/guides/webhooks) for setup details.
* **Check API key** — Copy the key fresh from **Settings → API Keys**
* **Header name** — Use `X-Api-Key` (not `Authorization: Bearer`)
* **Key active?** — Regenerate the key if it may have been revoked
* **No extra spaces** — Ensure no trailing whitespace in the key
You've hit the rate limit. Solutions:
* Add retry logic with exponential backoff
* Reduce request frequency
* Use webhooks instead of polling for status updates
* Contact [info@ravan.ai](mailto:info@ravan.ai) for higher limits on enterprise plans
***
## Voice Quality
* **Try a different voice** — Some voices sound more natural. Test several in the voice picker.
* **Lower temperature** — Very low temperatures (0.1) can make speech sound mechanical. Try 0.5.
* **Shorten responses** — Add "Keep your responses to 1-2 sentences" to your prompt.
* **Add personality** — Prompts like "speak casually and warmly" improve naturalness.
* **Responsiveness** — Increase the responsiveness setting to make the agent more patient before responding
* **Turn-taking** — Enable backchanneling so the agent uses filler words ("Mhm", "I see") while listening
* **Prompt instruction** — Add: "Wait for the caller to finish speaking before responding."
* **Ambient sound volume** — If using background sounds, lower `ambient_sound_volume` to 0.1-0.3
* **Caller side** — Background noise from the caller is harder to control. The agent's speech recognition handles moderate noise well.
***
## Quick Fixes Checklist
| Symptom | Quick Fix |
| -------------------- | --------------------------------------------------- |
| Call doesn't connect | Check phone number is active + dispatch rule exists |
| Agent doesn't speak | Set `begin_message` and `start_speaker: "agent"` |
| Slow first response | Switch to `Thunder Emotion`, shorten prompt |
| Wrong answers | Lower temperature, add guardrails to prompt |
| Transfer fails | Check E.164 format, verify tool is attached |
| Webhook not received | Verify HTTPS URL, check it returns 200 |
| 401 API error | Use `X-Api-Key` header with valid key |
| Calendar not syncing | Re-authorize OAuth in Settings |
***
## Getting Help
If you've gone through this guide and the issue persists:
Reach out to [info@ravan.ai](mailto:info@ravan.ai) with your agent ID and a description of the issue.
Check the API docs for endpoint-specific error codes and parameters.
# Trust Center
Source: https://docs.ravan.ai/guides/trust-center
Agni is built on enterprise-grade security. SOC 2 Type II certified, GDPR ready, HIPAA compliant, and hosted on AWS infrastructure.
# Trust Center
At Agni, security isn't an afterthought — it's the foundation. We've built our voice AI platform from the ground up with enterprise-grade security, privacy, and compliance controls so you can deploy with confidence.
Independently audited controls for security, availability, and confidentiality.
Full compliance with EU data protection regulations.
Safeguards for protected health information (PHI).
***
## Compliance & Certifications
### SOC 2 Type II
Agni has completed a SOC 2 Type II audit conducted by an independent third-party auditor. This certification validates that our systems and processes meet rigorous standards across all five Trust Service Criteria:
Systems are protected against unauthorized access through multi-layered security controls including encryption at rest and in transit, network segmentation, intrusion detection, and role-based access control.
Infrastructure is designed for high availability with redundant systems, automated failover, real-time monitoring, and defined SLAs. Our platform maintains 99.9%+ uptime.
Sensitive data is classified, encrypted, and access-restricted. We enforce strict data handling policies and conduct regular access reviews.
System processing is complete, valid, accurate, and timely. We maintain audit trails for all data operations and API transactions.
Personal data is collected, used, retained, and disclosed in conformity with our privacy commitments and applicable regulations.
To request a copy of our latest SOC 2 Type II report, please contact [info@ravan.ai](mailto:info@ravan.ai).
***
### GDPR Ready
Agni is built with **GDPR readiness** in mind for organizations operating in or serving users in the European Union. Our platform provides the tools and controls needed to support your GDPR compliance obligations.
We provide a DPA that details our role as a data processor, lawful basis for processing, data retention policies, and sub-processor disclosures.
We support all GDPR data subject rights including access, rectification, erasure, portability, and the right to restrict processing.
Data is processed and stored in AWS regions within the EU or US based on your configuration. You choose where your data lives.
In the event of a data breach, we notify affected customers within 72 hours as required by GDPR, with full incident details and remediation steps.
***
### HIPAA Compliance
For healthcare organizations and businesses handling Protected Health Information (PHI), Agni provides the safeguards required under the **Health Insurance Portability and Accountability Act (HIPAA)**.
* **Business Associate Agreement (BAA)** — We execute BAAs with all customers who require HIPAA compliance
* **PHI Encryption** — All protected health information is encrypted at rest (AES-256) and in transit (TLS 1.2+)
* **Access Controls** — Role-based access with audit logging for all PHI access events
* **Minimum Necessary Standard** — Our systems are designed to access only the minimum data required for processing
* **Audit Trail** — Complete audit logs of all data access, modifications, and API calls involving PHI
HIPAA compliance features are available on enterprise plans. Contact [info@ravan.ai](mailto:info@ravan.ai) to enable HIPAA-compliant configurations for your organization.
***
## Infrastructure Security
### Hosted on AWS
Agni runs entirely on **Amazon Web Services (AWS)**, leveraging world-class infrastructure with built-in security controls.
Deployed across multiple AWS regions (US and EU) with automatic failover and geo-redundancy.
VPC isolation, private subnets, security groups, and AWS WAF protect all network traffic.
Hardened container images, automated patching, and immutable infrastructure deployments.
24/7 monitoring with AWS CloudWatch, GuardDuty threat detection, and automated incident response.
### Encryption
| Layer | Standard | Details |
| ------------------- | -------- | ---------------------------------------------------------------------------- |
| **Data at rest** | AES-256 | All databases, file storage, and backups encrypted with AWS KMS managed keys |
| **Data in transit** | TLS 1.2+ | All API calls, WebSocket connections, and voice streams encrypted end-to-end |
| **Voice data** | AES-256 | Call recordings and transcripts encrypted with per-customer keys |
| **API keys** | SHA-256 | Hashed and salted — we never store API keys in plain text |
### Network Architecture
* **DDoS Protection** — AWS Shield Standard on all endpoints, Shield Advanced available
* **Web Application Firewall** — AWS WAF with custom rules blocking injection, XSS, and bot attacks
* **Private Networking** — All internal services communicate over private VPC links, never over the public internet
* **Rate Limiting** — API rate limiting at the edge to prevent abuse and ensure fair usage
***
## Data Privacy & Handling
### Data Retention
| Data Type | Retention | Notes |
| -------------------- | --------------- | --------------------------------------------------------------------------- |
| **Call recordings** | 90 days default | Configurable per organization. Can be set to 0 (no recording) |
| **Call transcripts** | 90 days default | Configurable. Supports automatic deletion policies |
| **Analytics data** | 12 months | Aggregated metrics retained for reporting |
| **API logs** | 30 days | Request/response logs for debugging and audit |
| **Account data** | Until deletion | Retained while account is active. Deleted within 30 days of account closure |
### Data Deletion
* **Self-service** — Delete call recordings, transcripts, and contacts via the dashboard or API
* **Account deletion** — Full data purge within 30 days of account closure
* **Right to erasure** — GDPR Article 17 requests processed within 72 hours
* **Automated cleanup** — Expired data is automatically purged per your retention settings
### Sub-Processors
We use a limited number of trusted sub-processors, each bound by strict data processing agreements:
| Provider | Purpose | Location |
| ----------------------------- | -------------------------------------- | -------- |
| **Amazon Web Services (AWS)** | Cloud infrastructure, compute, storage | US / EU |
| **Twilio** | Telephony, phone numbers, SMS | US |
| **OpenAI** | LLM processing (configurable) | US |
| **Stripe** | Billing and payment processing | US |
We maintain a current list of sub-processors. Customers are notified of any sub-processor changes with 30 days advance notice.
***
## Application Security
### Secure Development
* **Secure SDLC** — Security is integrated into every phase of development: design review, code review, static analysis, and penetration testing
* **Dependency Scanning** — Automated scanning of all dependencies for known vulnerabilities (CVEs)
* **Code Review** — All code changes require peer review before merge
* **CI/CD Security** — Build pipelines include security checks, linting, and automated tests
### Authentication & Access Control
* **API Key Authentication** — Unique per-organization API keys with SHA-256 hashing
* **Role-Based Access Control (RBAC)** — Granular permissions for team members (Owner, Admin, Member)
* **Two-Factor Authentication (2FA)** — Available for all user accounts
* **Session Management** — Configurable session timeouts and active session monitoring
* **SSO** — Google OAuth supported, with SAML/OIDC available on enterprise plans
### Vulnerability Management
* **Penetration Testing** — Annual third-party penetration tests with remediation tracking
* **Bug Bounty** — Responsible disclosure program for security researchers
* **Incident Response** — Documented incident response plan with defined escalation procedures
* **Patching** — Critical vulnerabilities patched within 24 hours; high-severity within 7 days
***
## Responsible AI
### Voice AI Ethics
Agni is committed to the responsible development and deployment of voice AI technology:
* **Transparency** — All AI-powered calls clearly identify themselves as AI agents when required by law
* **Consent** — Call recording and monitoring comply with local consent laws (one-party and two-party)
* **Bias Mitigation** — Regular audits of AI model outputs for fairness across demographics
* **Human Oversight** — Call transfer to human agents is always available as a fallback
* **Data Minimization** — We collect only the data necessary to provide the service
***
## Frequently Asked Questions
Yes. Contact [info@ravan.ai](mailto:info@ravan.ai) with your organization details, and we'll share the latest report under NDA.
Yes. We execute Business Associate Agreements for healthcare customers on enterprise plans. Reach out to [info@ravan.ai](mailto:info@ravan.ai) to get started.
All data is stored on AWS infrastructure. By default, data is stored in US regions. EU data residency is available upon request.
You can delete call recordings, transcripts, and contacts from the dashboard or via the API. For full account deletion, contact support and all data will be purged within 30 days.
We never sell customer data. Data is shared only with sub-processors listed above, strictly for providing the service. All sub-processors are bound by DPAs.
Our incident response team is available 24/7. Affected customers are notified within 72 hours with full incident details, impact assessment, and remediation steps.
***
Reach out to our security team at [info@ravan.ai](mailto:info@ravan.ai). We're happy to discuss your compliance requirements, share audit reports, or schedule a security review.
# Webhooks
Source: https://docs.ravan.ai/guides/webhooks
Receive real-time notifications for call events, transcripts, and post-call analysis using Agni webhooks.
# Using Webhooks
Webhooks let you receive real-time HTTP callbacks when events happen in Agni — like when a call starts, ends, or when post-call analysis is ready. Instead of polling our API, we push data to your server instantly.
***
## How It Works
Set up a publicly accessible HTTPS endpoint on your server that can receive POST requests.
Add your webhook URL in the agent's webhook settings or via the API.
Agni sends a POST request to your endpoint whenever a subscribed event occurs.
Your server processes the payload and returns a 200 status. We'll retry on failure.
***
## Webhook Events
The primary webhook event is `call.completed`, dispatched automatically when a call ends.
| Event | Trigger | Payload Includes |
| ---------------- | ----------------- | --------------------------------------------------------------------- |
| `call.completed` | Call session ends | Full call data, transcripts, recording, sentiment, post-call analysis |
See the complete After-Call Webhook API reference for every field in the payload, with types and descriptions.
***
## `call.completed` Payload
When a call ends, Agni sends the complete call record including metadata, transcripts, AI analysis, and costs:
```json theme={null}
{
"event": "call.completed",
"org_id": "1268c1f0-19f3-47db-aefb-c16a7c3ace6e",
"data": {
"campaign_id": "uuid-or-null",
"contact_id": "uuid-or-null",
"phone": "+14155550100",
"status": "completed",
"duration_sec": 125,
"call_session_id": "019d2b3c-8e9f-7a0b-1c2d-4e5f6a7b8c9d",
"attempt": 1,
"summary": "AI-generated summary of the conversation...",
"recording_url": "https://storage.agniai.com/rec/019d2b3c-8e9f.mp3",
"caller_number": "+18881234567",
"callee_number": "+14155550100",
"caller_name": "John Doe",
"caller_email": "john@example.com",
"agent_name": "Support Agent",
"channel": "voice",
"disconnect_reason": "customer_hangup",
"cost_total": 0.42,
"call_latency_ms": 150,
"started_at": "2026-03-24T18:30:00Z",
"ended_at": "2026-03-24T18:32:05Z",
"created_at": "2026-03-24T18:30:00Z",
"post_call_analysis": {
"sentiment": "positive",
"disposition": "meeting_booked",
"goals_met": true,
"next_steps": "Send follow-up details via email"
},
"transcripts": [
{
"id": "t-001",
"timestamp_ms": 0,
"role": "agent",
"message": { "content": "Hello! How can I help you today?", "format": "text" },
"created_at": "2026-03-24T18:30:00Z"
},
{
"id": "t-002",
"timestamp_ms": 3200,
"role": "user",
"message": { "content": "I'd like to schedule an appointment.", "format": "text" },
"created_at": "2026-03-24T18:30:03Z"
}
]
}
}
```
### Key Fields
| Field | Type | Description |
| -------------------------------- | ------- | ------------------------------------------------------------- |
| `status` | string | `completed`, `failed`, `no_answer`, `busy`, `voicemail` |
| `channel` | string | `voice` (phone), `web` (browser), `sip` |
| `disconnect_reason` | string | `customer_hangup`, `agent_hangup`, `error` |
| `post_call_analysis.sentiment` | string | `positive`, `neutral`, `negative` |
| `post_call_analysis.disposition` | string | e.g. `meeting_booked`, `not_interested`, `callback_requested` |
| `post_call_analysis.goals_met` | boolean | Whether the agent achieved its objective |
| `transcripts[]` | array | Full conversation, ordered by `timestamp_ms` |
***
## Setting Up Your Webhook
### Via Dashboard
1. Navigate to **Agents** → Select your agent
2. Open the **Webhook Settings** tab in the right sidebar
3. Enter your endpoint URL (must be HTTPS)
4. Select which events to subscribe to
5. Click **Save**
### Via API
```bash cURL theme={null}
curl -X PUT https://api.ravan.ai/api/v1/agents/{agent_id} \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"webhook_url": "https://your-server.com/webhooks/agni",
"webhook_events": ["call.completed"]
}'
```
***
## Example Webhook Receivers
```javascript theme={null}
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhooks/agni', (req, res) => {
const { event, org_id, data } = req.body;
if (event === 'call.completed') {
console.log(`Call ${data.call_session_id} completed`);
console.log(`Duration: ${data.duration_sec}s, Status: ${data.status}`);
console.log(`Summary: ${data.summary}`);
console.log(`Sentiment: ${data.post_call_analysis?.sentiment}`);
console.log(`Disposition: ${data.post_call_analysis?.disposition}`);
console.log(`Transcripts: ${data.transcripts?.length} messages`);
// Store in your database
// Update CRM with call outcome
// Trigger follow-up workflows based on disposition
}
res.status(200).json({ received: true });
});
app.listen(3000);
```
```python theme={null}
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhooks/agni', methods=['POST'])
def handle_webhook():
payload = request.json
event = payload.get('event')
data = payload.get('data', {})
if event == 'call.completed':
print(f"Call {data['call_session_id']} completed")
print(f"Duration: {data['duration_sec']}s, Status: {data['status']}")
print(f"Summary: {data.get('summary')}")
analysis = data.get('post_call_analysis', {})
print(f"Sentiment: {analysis.get('sentiment')}")
print(f"Disposition: {analysis.get('disposition')}")
print(f"Goals met: {analysis.get('goals_met')}")
transcripts = data.get('transcripts', [])
print(f"Transcript entries: {len(transcripts)}")
# Store in database, update CRM, trigger workflows
return jsonify({'received': True}), 200
if __name__ == '__main__':
app.run(port=3000)
```
***
## Retry Policy
If your endpoint returns a non-2xx response or times out (30 seconds), Agni retries with exponential backoff:
| Attempt | Delay |
| ----------- | ---------- |
| 1st retry | 30 seconds |
| 2nd retry | 2 minutes |
| 3rd retry | 10 minutes |
| 4th retry | 1 hour |
| Final retry | 6 hours |
After 5 failed attempts, the webhook is marked as failing. You'll receive an email notification and can check failed deliveries in the dashboard.
***
## Best Practices
Process the webhook asynchronously. Return 200 immediately and handle the data in a background job.
Use the `call_id` as an idempotency key. The same event may be delivered more than once during retries.
Check that the event type and required fields are present before processing. Ignore unknown event types gracefully.
Webhook URLs must use HTTPS. We do not send payloads over unencrypted connections.
***
## Troubleshooting
* Verify your endpoint URL is correct and publicly accessible
* Check that your server returns 200 status within 30 seconds
* Ensure your firewall allows incoming POST requests from Agni's IP ranges
* Check the webhook logs in your agent's settings
This is normal during retries. Implement idempotency using the `call_id` field — check if you've already processed that event before acting on it.
After 5 consecutive failures, webhooks pause. Fix your endpoint, then re-save the webhook URL in agent settings to resume delivery.
# Agni - by Ravan.ai
Source: https://docs.ravan.ai/index
The world's most natural voice AI. Real emotion. Real turn-taking. Real conversation. Not a chatbot. Not a script. Just talk.
Explore Enterprise Plan
You can go here to book an appointment for your enterprise onboarding.
## Experience it. Don't read. Listen.
We could write paragraphs about latency, orchestration, and cost curves. Or you could just talk to it and know.
Experience Agni immediately. No signup required. Talk to it and then decide.
Dive straight into our API reference and start integrating in minutes.
***
## Real-Time Voice Infrastructure
Enterprise-grade scale and performance, out of the box.
Human-speed response times. No awkward pauses.
Tested and proven at scale across production workloads.
Trusted by teams worldwide for customer-facing calls.
No provider throttling. Scale on your terms.
Transparent, usage-based pricing. Contact sales for details.
Native fluency globally. Not just translation.
***
## Why this is different.
Built from scratch for the post-real-time era. Not retrofitted. Not patched. Designed.
Agni doesn't stitch audio clips together. It thinks in voice -- it pauses, laughs, hesitates, and breathes. It sounds the way humans actually talk.
We don't lock you into one vendor. Agni dynamically routes across real-time engines to guarantee the best latency, quality, and cost -- on every single call.
No provider contracts throttling your scale. Concurrency is entirely in your hands -- whether you need 50, 500, or 5,000 simultaneous sessions.
Competitors architected their systems before streaming models even existed. Agni was designed from day one for the world we're in right now.
***
## Transparent Pricing
\$
Usage-Based Pricing
Simple. Transparent. No hidden fees. Pricing is matched to your region and usage.
For pricing-related questions, visit the pricing page for your region.
View pricing
## Explore the Docs
Step-by-step walkthroughs for every feature in the Agni platform.
Full REST API documentation with cURL, Python, and JavaScript examples.
Words don't do it justice. Try the demo and then decide.