> ## 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 Developer Docs

> Integrate Ringg AI voice agents into your product with REST APIs, web calls, campaigns, and webhooks.

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.

<Warning>
  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.
</Warning>

## 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.

<CardGroup cols={3}>
  <Card title="Backend/API integration" icon="server-cog" href="/api-reference/quick-start/guide">
    Make outbound calls, run campaigns, receive webhooks, query history, and build production backend workflows.
  </Card>

  <Card title="Web widget integration" icon="globe" href="/get-started/guides/embedding-widget">
    Embed Ringg voice or chat assistance in a website, then configure styling, events, chat widgets, CSP, and QA.
  </Card>

  <Card title="Dashboard setup" icon="layout-dashboard" href="/get-started/guides/create-assistant">
    Create assistants, prompts, knowledge bases, numbers, campaigns, and analytics views without reading API docs first.
  </Card>
</CardGroup>

## 5-minute integration path

<Steps>
  <Step title="Get an API key" icon="key-round">
    In the Ringg dashboard, open **API** and copy your workspace API key. Send it on every API request as `X-API-KEY`.
  </Step>

  <Step title="Check workspace access" icon="shield-check">
    Call `GET /workspace` to verify the key, workspace, and available credits before starting a call flow.
  </Step>

  <Step title="Choose an assistant" icon="bot-message-square">
    Call `GET /agent/all` and select an assistant configured for your channel, such as outbound calls or web calls.
  </Step>

  <Step title="Choose a caller number" icon="hash">
    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`.
  </Step>

  <Step title="Initiate the call" icon="phone-call">
    Call `POST /calling/outbound/individual` with the recipient, assistant, caller number, and any `custom_args_values` your prompt uses.
  </Step>

  <Step title="Process the result" icon="workflow">
    Store the returned `call_id`, then use webhooks for real-time events or `GET /calling/history` for polling and reporting.
  </Step>
</Steps>

## Copy-paste starter

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  const BASE_URL = "https://prod-api.ringg.ai/ca/api/v0";

  async function startRinggCall() {
    const response = await fetch(`${BASE_URL}/calling/outbound/individual`, {
      method: "POST",
      headers: {
        "X-API-KEY": process.env.RINGG_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "John Doe",
        mobile_number: "+919876543210",
        agent_id: process.env.RINGG_AGENT_ID,
        from_number_id: process.env.RINGG_FROM_NUMBER_ID,
        custom_args_values: {
          callee_name: "John",
          order_id: "ORD-1042",
        },
        callback_url: "https://api.example.com/ringg/callback",
      }),
    });

    if (!response.ok) {
      throw new Error(`Ringg API error: ${response.status} ${await response.text()}`);
    }

    return response.json();
  }
  ```
</CodeGroup>

## API basics

| Concern             | What to use                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| Base URL            | `https://prod-api.ringg.ai/ca/api/v0`                                                           |
| Authentication      | `X-API-KEY: your-api-key`                                                                       |
| Request body        | JSON for normal API calls, `multipart/form-data` for campaign CSV uploads                       |
| Phone numbers       | E.164 format with country code, for example `+919876543210`                                     |
| Dynamic prompt data | `custom_args_values`, referenced in prompts as `@{{variable_name}}`                             |
| Call identifier     | Store the returned `call_id` for history lookup, webhook dedupe, and support debugging          |
| Async results       | Prefer webhooks for production integrations; use history APIs for dashboards and reconciliation |

## Integration paths

<CardGroup cols={2}>
  <Card title="Outbound calling API" icon="phone-forwarded" href="/api-reference/endpoint/calling/initiate-individual-call">
    Start immediate or scheduled calls, pass custom variables, configure retry behavior, and use smart formatting for names.
  </Card>

  <Card title="Campaign API" icon="send" href="/api-reference/endpoint/campaign/upload-campaign-contact-list">
    Upload a CSV, map columns to assistant variables, choose campaign windows, and start calls with selected from numbers.
  </Card>

  <Card title="Assistant setup" icon="bot" href="/get-started/guides/create-assistant">
    Create prompts, select voices, configure variables, and prepare an assistant for phone or web calling.
  </Card>

  <Card title="Number management" icon="hash" href="/get-started/guides/manage-numbers">
    Buy, import, assign, and verify phone numbers used by outbound and inbound call flows.
  </Card>

  <Card title="Webhooks" icon="radio-tower" href="/webhooks/payloads">
    Receive `call_started`, `call_completed`, recording, analysis, and `all_processing_completed` events.
  </Card>

  <Card title="Analytics and history" icon="chart-no-axes-combined" href="/api-reference/endpoint/history/get-call-history">
    Retrieve transcripts, statuses, durations, recordings, classifications, and performance metrics.
  </Card>
</CardGroup>

## 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

| Symptom                  | Check first                                                        | Go deeper                                                                                     |
| ------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `401 Unauthorized`       | Missing or invalid `X-API-KEY`                                     | [Authentication](/api-reference/quick-start/authentication)                                   |
| Call does not start      | Assistant type, credits, from number, recipient format             | [Initiate individual call](/api-reference/endpoint/calling/initiate-individual-call)          |
| Variables are not spoken | `custom_args_values` keys and prompt placeholders                  | [Configure assistant](/get-started/guides/configure-assistant)                                |
| Campaign upload fails    | CSV headers, `variables_map`, country code, future campaign window | [Upload campaign contact list](/api-reference/endpoint/campaign/upload-campaign-contact-list) |
| Missing post-call data   | Webhook event subscription and endpoint `2xx` responses            | [Webhook setup](/webhooks/initial-setup)                                                      |
| Poor web call experience | Domain whitelist, microphone permission, CSP, SDK version          | [Web call integration](/get-started/best-practices/web-call-integration)                      |

## Next steps

<CardGroup cols={3}>
  <Card title="Quick Start" icon="rocket" href="/api-reference/quick-start/guide">
    Make a real API call and learn the request shape.
  </Card>

  <Card title="API Overview" icon="book-open" href="/api-reference/quick-start/api-overview">
    Review resources, headers, pagination, errors, and versioning.
  </Card>

  <Card title="Security Guidelines" icon="lock-keyhole" href="/get-started/best-practices/security-guidelines">
    Protect API keys, webhook endpoints, recordings, and user data.
  </Card>
</CardGroup>