---
name: Ringg
description: Use when building voice AI integrations, creating outbound calling campaigns, embedding web call widgets, managing phone numbers, configuring webhooks, or querying call history and analytics. Agents should reach for this skill when users need to make programmatic voice calls, run bulk calling campaigns, embed voice assistants on websites, or integrate voice AI into backend systems.
metadata:
    mintlify-proj: ringg
    version: "1.0"
---

# Ringg AI Skill

## Product summary

Ringg AI is a voice AI platform that lets you create programmable voice agents for outbound calls, inbound calls, web calls, bulk campaigns, and post-call analytics. Agents use the REST API to trigger calls from backend code, configure assistants in the dashboard, manage phone numbers, subscribe to webhook events for real-time updates, and query call history and analytics. The primary API base URL is `https://prod-api.ringg.ai/ca/api/v0`. Authentication uses `X-API-KEY` header. Key resources: assistants (agents), phone numbers (from_number_id), contact lists (bulk_list_id), and call records (call_id). Start at https://docs.ringg.ai for full documentation.

## When to use

Reach for this skill when:
- A user wants to make outbound calls programmatically from their backend
- A user needs to run bulk calling campaigns with CSV contact lists
- A user wants to embed a voice or chat widget on their website
- A user needs to set up inbound call routing to an AI assistant
- A user wants to receive real-time call events via webhooks
- A user needs to query call history, transcripts, recordings, or analytics
- A user is integrating their own telephony provider (Twilio, Plivo, Exotel)
- A user needs to configure custom variables, knowledge bases, or post-call analysis
- A user is troubleshooting call failures, authentication errors, or webhook delivery

## Quick reference

### API Base URL and Authentication
```
Base URL: https://prod-api.ringg.ai/ca/api/v0
Header: X-API-KEY: your-api-key
```

### Core IDs to Store
| ID | Source | Used for |
|---|---|---|
| `agent_id` | `GET /agent/all` or dashboard | API calls, campaigns, webhooks |
| `from_number_id` | `GET /workspace/numbers` | Outbound calls, campaigns |
| `call_id` | Call initiation response | Webhook dedupe, history lookup, support |
| `list_id` / `bulk_list_id` | Campaign upload response | Campaign start, analytics, history filter |

### Essential Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| GET | `/workspace` | Verify API key and check credits |
| GET | `/agent/all` | List all assistants in workspace |
| GET | `/workspace/numbers` | List available caller numbers |
| POST | `/calling/outbound/individual` | Start one outbound call |
| POST | `/campaign/save` | Upload CSV and create campaign |
| POST | `/campaign/start` | Start a campaign |
| GET | `/calling/history` | Retrieve call records and transcripts |
| PATCH | `/agent/v1` | Configure webhook subscriptions |

### Phone Number Format
Always use E.164 format with country code: `+919876543210` (country code + number)

### Custom Variables in Prompts
Reference in prompt with `@{{variable_name}}`, pass in API with `custom_args_values` object:
```json
{
  "custom_args_values": {
    "callee_name": "John",
    "order_id": "ORD-1042"
  }
}
```

### Webhook Event Types
| Event | When it fires | Typical use |
|---|---|---|
| `call_started` | Call initiated | Mark as queued in your system |
| `call_completed` | Call attempt finishes | Update status, duration, transcript |
| `recording_completed` | Recording processed | Store or display recording URL |
| `platform_analysis_completed` | Ringg analysis done | Store summary, classification, key points |
| `client_analysis_completed` | Custom analysis done | Store your configured extraction fields |
| `all_processing_completed` | All post-call processing done | Final consolidated payload with everything |

## Decision guidance

### When to use individual calls vs campaigns
| Scenario | Use |
|---|---|
| One call per user action (order confirmation, appointment reminder) | `POST /calling/outbound/individual` |
| Bulk calling 100+ contacts on a schedule | `POST /campaign/save` then `POST /campaign/start` |
| Bulk calling 5,000+ rows with async processing | Beta large-campaign flow: `/campaign/upload-csv`, poll status, `/campaign/make-call-async` |

### When to use webhooks vs polling
| Scenario | Use |
|---|---|
| Real-time product UI updates, immediate downstream actions | Webhooks with `call_started`, `call_completed`, `all_processing_completed` |
| Dashboards, reconciliation, periodic exports, support tools | `GET /calling/history` polling |
| Production integrations needing both | Webhooks for real-time, history API for dashboards and backfills |

### When to use from_number_id vs from_number
| Scenario | Use |
|---|---|
| Stable caller ID across number formatting changes | `from_number_id` (preferred) |
| One-off calls with raw phone number | `from_number` (must include country code) |
| Never use both in same request | Error if both provided |

### Knowledge base type selection
| Type | Best for | Tradeoff |
|---|---|---|
| Deterministic KB | Pricing tables, policy fields, product catalogs, eligibility rules | More setup, more predictable answers |
| Non-Deterministic KB | FAQs, articles, manuals, SOPs | Faster setup, answers may need more testing |

## Workflow

### Making your first outbound call
1. **Get API key**: Log in to dashboard, open API, copy workspace API key
2. **Verify access**: Call `GET /workspace` with `X-API-KEY` header to confirm key and check credits
3. **Choose assistant**: Call `GET /agent/all`, select an assistant configured for outbound calls, save `agent_id`
4. **Choose number**: Call `GET /workspace/numbers`, select a provisioned number, save `from_number_id`
5. **Prepare variables**: If your prompt uses `@{{callee_name}}` or other placeholders, prepare `custom_args_values` object
6. **Make the call**: POST to `/calling/outbound/individual` with recipient name, phone number (E.164), agent_id, from_number_id, and custom_args_values
7. **Store call_id**: Save the returned `call_id` for webhook dedupe and history lookup
8. **Receive results**: Subscribe to webhooks or poll `GET /calling/history` for transcripts, recordings, and analysis

### Running a bulk campaign
1. **Prepare CSV**: Create file with "Mobile Number" column (E.164 format) and any custom variable columns matching your prompt
2. **Download template**: Get the exact template from dashboard campaigns tab for your assistant
3. **Upload campaign**: POST to `/campaign/save` with CSV file, agent_id, campaign name, start/end times, timezone, and variable mapping
4. **Save list_id**: Store the returned `list_id` from upload response
5. **Start calling**: POST to `/campaign/start` with list_id, selected from_number_ids, and call config (retries, calling windows)
6. **Monitor progress**: Use `GET /campaign/all` to check status, or subscribe to webhooks for real-time events
7. **Retrieve results**: Use `GET /calling/history` with `bulk_list_id` filter to get all campaign call records

### Setting up webhooks
1. **Choose events**: Decide which events your product needs (usually start with `all_processing_completed`)
2. **Prepare endpoint**: Create HTTPS endpoint that accepts POST, validates requests, returns 2xx quickly, handles duplicates idempotently
3. **Configure subscription**: PATCH `/agent/v1` with `operation: "edit_event_subscriptions"`, agent_id, callback_url, and optional headers for authentication
4. **Dedupe on call_id + event_type**: Store received events with `call_id` and `event_type` as composite key to avoid duplicates
5. **Do heavy work async**: Return 2xx immediately, then process transcript/recording/analysis in your own job queue
6. **Reconcile with history API**: Periodically compare webhook data with `GET /calling/history` for consistency checks

### Embedding a web call widget
1. **Configure assistant**: Open assistant in dashboard, go to WebCall settings, add your domain to Whitelist Domains
2. **Get embed code**: Dashboard generates snippet with agentId and xApiKey for that assistant
3. **Add to page**: Paste snippet before closing `</body>` tag, load CDN script and stylesheet
4. **Set variables**: Pass runtime values in `variables` object (callee_name, account_id, etc.)
5. **Configure mode**: Set `defaultTab: "audio"` for voice-first or `"text"` for chat-first
6. **Update CSP**: If site uses Content Security Policy, allow `https://cdn.jsdelivr.net` for scripts and styles
7. **Test on staging**: Verify widget loads, microphone permission works, calls complete, domain is whitelisted
8. **Pin CDN version**: Replace `latest` with specific version after testing, update CSP entries to match

## Common gotchas

- **API key in client code**: Never put `X-API-KEY` in browser JavaScript, mobile apps, or public repos. Use only from trusted server-side code. Web widget uses a separate `xApiKey` scoped to that assistant.
- **Phone number format**: Always use E.164 with country code (`+919876543210`). Missing country code causes silent failures.
- **Both from_number_id and from_number**: Providing both in same request causes validation error. Use exactly one.
- **Custom variable mismatch**: If prompt says `@{{callee_name}}` but you pass `custom_args_values: { "name": "John" }`, the variable won't be spoken. Keys must match exactly.
- **CSV headers with spaces**: Campaign CSV headers like `"Mobile Number "` (trailing space) won't match your variable mapping. Download template and use exact headers.
- **Webhook endpoint not 2xx**: If your endpoint returns 4xx or 5xx, Ringg retries and may drop events. Always return 2xx quickly, do heavy work async.
- **Duplicate webhook events**: Same event can arrive multiple times. Dedupe on `call_id` + `event_type`, don't create duplicate records.
- **Campaign start time in past**: `campaign_start_time` must be in the future. Scheduling calls for yesterday fails silently.
- **Missing calling window**: If `call_start_time` is 09:00 and you call at 08:00, the call queues until 09:00. Check timezone matches recipient location.
- **Regenerating API key**: Invalidates old key immediately. Update all backend services before rotating.
- **Large campaign CSV (5000+ rows)**: Use beta large-campaign flow (`/campaign/upload-csv`, poll status, `/campaign/make-call-async`), not standard `/campaign/save`.
- **Recording/transcript not ready**: `all_processing_completed` event fires when everything is done. Don't poll history immediately after `call_completed`.

## Verification checklist

Before submitting work with Ringg AI:

- [ ] API key is stored in environment variables or secret manager, not in code
- [ ] Tested `GET /workspace` to verify authentication and check available credits
- [ ] Retrieved and stored `agent_id`, `from_number_id`, and `call_id` values
- [ ] Phone numbers are in E.164 format with country code
- [ ] Custom variable keys in `custom_args_values` match prompt placeholders exactly
- [ ] Campaign CSV headers match variable mapping (no extra spaces)
- [ ] Webhook endpoint returns 2xx within timeout, handles duplicates idempotently
- [ ] Webhook subscription configured with correct event types and callback URL
- [ ] Calling windows and timezones are set correctly for target audience
- [ ] Web widget domain is whitelisted in assistant WebCall settings
- [ ] CSP allows CDN domain if using web widget
- [ ] Tested in staging before deploying to production
- [ ] Call history and analytics queries use correct filters (agent_id, bulk_list_id, date range)
- [ ] Reconciled webhook events with history API for consistency

## Resources

- **Full navigation**: https://docs.ringg.ai/llms.txt — comprehensive page-by-page listing for agent reference
- **Quick Start Guide**: https://docs.ringg.ai/api-reference/quick-start/guide — make your first API call
- **API Overview**: https://docs.ringg.ai/api-reference/quick-start/api-overview — understand resources, versioning, error handling
- **Webhook Setup**: https://docs.ringg.ai/webhooks/initial-setup — configure real-time event subscriptions

---

> For additional documentation and navigation, see: https://docs.ringg.ai/llms.txt