Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt

Use this file to discover all available pages before exploring further.

Ringg AI gives your product programmable voice agents for outbound calls, inbound calls, web calls, bulk campaigns, and post-call analytics. Create the assistant in the dashboard, trigger calls from your backend, and receive results through webhooks or the call history APIs.
Use X-API-KEY only from trusted server-side code. Do not put workspace API keys in browser or mobile app source code unless you are using the managed Ringg web widget flow.

​
Choose your path

Start with the path that matches your role. Each path links to the smallest useful guide first, then to deeper reference pages.

Backend/API integration

Make outbound calls, run campaigns, receive webhooks, query history, and build production backend workflows.

Web widget integration

Embed Ringg voice or chat assistance in a website, then configure styling, events, chat widgets, CSP, and QA.

Dashboard setup

Create assistants, prompts, knowledge bases, numbers, campaigns, and analytics views without reading API docs first.

​
5-minute integration path

Get an API key

In the Ringg dashboard, open API and copy your workspace API key. Send it on every API request as X-API-KEY.

Check workspace access

Call GET /workspace to verify the key, workspace, and available credits before starting a call flow.

Choose an assistant

Call GET /agent/all and select an assistant configured for your channel, such as outbound calls or web calls.

Choose a caller number

Call GET /workspace/numbers and use a provisioned number as from_number_id. The individual-call API requires exactly one caller-number option: from_number_id or from_number.

Initiate the call

Call POST /calling/outbound/individual with the recipient, assistant, caller number, and any custom_args_values your prompt uses.

Process the result

Store the returned call_id, then use webhooks for real-time events or GET /calling/history for polling and reporting.

​
Copy-paste starter

export RINGG_BASE_URL="https://prod-api.ringg.ai/ca/api/v0"
export RINGG_API_KEY="your-api-key"
export AGENT_ID="your-agent-id"
export FROM_NUMBER_ID="your-from-number-id"

curl --request POST "$RINGG_BASE_URL/calling/outbound/individual" \
  --header "X-API-KEY: $RINGG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "John Doe",
    "mobile_number": "+919876543210",
    "agent_id": "'"$AGENT_ID"'",
    "from_number_id": "'"$FROM_NUMBER_ID"'",
    "custom_args_values": {
      "callee_name": "John",
      "order_id": "ORD-1042"
    },
    "callback_url": "https://api.example.com/ringg/callback"
  }'

​
API basics

ConcernWhat to use
Base URLhttps://prod-api.ringg.ai/ca/api/v0
AuthenticationX-API-KEY: your-api-key
Request bodyJSON for normal API calls, multipart/form-data for campaign CSV uploads
Phone numbersE.164 format with country code, for example +919876543210
Dynamic prompt datacustom_args_values, referenced in prompts as @{{variable_name}}
Call identifierStore the returned call_id for history lookup, webhook dedupe, and support debugging
Async resultsPrefer webhooks for production integrations; use history APIs for dashboards and reconciliation

​
Integration paths

Outbound calling API

Start immediate or scheduled calls, pass custom variables, configure retry behavior, and use smart formatting for names.

Campaign API

Upload a CSV, map columns to assistant variables, choose campaign windows, and start calls with selected from numbers.

Assistant setup

Create prompts, select voices, configure variables, and prepare an assistant for phone or web calling.

Number management

Buy, import, assign, and verify phone numbers used by outbound and inbound call flows.

Webhooks

Receive call_started, call_completed, recording, analysis, and all_processing_completed events.

Analytics and history

Retrieve transcripts, statuses, durations, recordings, classifications, and performance metrics.

​
Design for production

  • Keep API keys in server secrets and rotate them when team access changes.
  • Validate phone numbers before sending calls. Include country code on every recipient number.
  • Store Ringg IDs in your database: agent_id, from_number_id, call_id, bulk_list_id, and campaign IDs.
  • Pass only the data the assistant needs in custom_args_values; avoid unnecessary personal data.
  • Configure call_config.call_time and retry settings for calling windows, time zones, busy users, and no-answer flows.
  • Subscribe to all_processing_completed when your product needs the full transcript, recording, platform analysis, and custom analysis in one event.
  • Make webhook handlers idempotent by deduping on call_id plus event_type.
  • Return 2xx from webhook handlers quickly, then do heavier processing in your own job queue.
  • Reconcile webhook data with call history exports for dashboards, billing, and support workflows.

​
Troubleshooting map

SymptomCheck firstGo deeper
401 UnauthorizedMissing or invalid X-API-KEYAuthentication
Call does not startAssistant type, credits, from number, recipient formatInitiate individual call
Variables are not spokencustom_args_values keys and prompt placeholdersConfigure assistant
Campaign upload failsCSV headers, variables_map, country code, future campaign windowUpload campaign contact list
Missing post-call dataWebhook event subscription and endpoint 2xx responsesWebhook setup
Poor web call experienceDomain whitelist, microphone permission, CSP, SDK versionWeb call integration

​
Next steps

Quick Start

Make a real API call and learn the request shape.

API Overview

Review resources, headers, pagination, errors, and versioning.

Security Guidelines

Protect API keys, webhook endpoints, recordings, and user data.