Make Your First Outbound Call Tutorial

Use this tutorial when you already have a Ringg workspace and want to prove the end-to-end phone call flow from your backend.

Keep X-API-KEY on your server. Do not expose it in browser or mobile source code.

Prerequisites

A Ringg AI workspace and API key
An outbound assistant
A provisioned workspace number
A recipient phone number in E.164 format, for example +919876543210

Step 1: Verify your workspace

curl --request GET "https://prod-api.ringg.ai/ca/api/v0/workspace" \
  --header "X-API-KEY: $RINGG_API_KEY"

If this returns 401, fix the key before continuing.

Step 2: Get an assistant ID

curl --request GET "https://prod-api.ringg.ai/ca/api/v0/agent/all" \
  --header "X-API-KEY: $RINGG_API_KEY"

Choose the assistant that should conduct the conversation and save its agent_id.

Step 3: Get a caller number ID

curl --request GET "https://prod-api.ringg.ai/ca/api/v0/workspace/numbers" \
  --header "X-API-KEY: $RINGG_API_KEY"

Choose a number available in your workspace and save its from_number_id.

Step 4: Initiate the outbound call

curl --request POST "https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual" \
  --header "X-API-KEY: $RINGG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "John Doe",
    "mobile_number": "+919876543210",
    "agent_id": "your-agent-id",
    "from_number_id": "your-from-number-id",
    "custom_args_values": {
      "callee_name": "John",
      "order_id": "ORD-1042"
    }
  }'

custom_args_values should include every variable your assistant prompt references, such as @{{callee_name}} or @{{order_id}}.

Step 5: Store the call ID

A successful response includes a unique call ID. Store it in your system.

{
  "Call Status": "success",
  "data": {
    "Unique Call ID": "dd6c63db-66c7-42ae-9a82-e4988bef428e",
    "Call Direction": "outbound",
    "Call Status": "registered",
    "From Number": "+918035737034",
    "To Number": "+919876543210",
    "Agent ID": "cdcf1b39-173a-4492-8396-c493123ea443",
    "System generated message": "Call initiated successfully"
  }
}

Step 6: Check the result

For manual verification, use call history:

curl --request GET "https://prod-api.ringg.ai/ca/api/v0/calling/history?limit=20&offset=0" \
  --header "X-API-KEY: $RINGG_API_KEY"

For production, configure webhooks and subscribe to all_processing_completed so your backend receives the final transcript, recording, and analysis data automatically.

Status reference

Status	Meaning
`registered`	Call is queued and waiting to be processed
`ongoing`	Call is in progress
`retry`	Ringg will retry based on retry configuration
`completed`	Recipient answered and the call reached a terminal completed state
`failed`	Retries were exhausted or the provider failed the call
`error`	Unexpected terminal error
`cancelled`	Call was cancelled before completion

Get Started

API Reference

Webhooks Setup

Telephony Integration

External Integrations

Making Your First Call

Prerequisites

Step 1: Verify your workspace

Step 2: Get an assistant ID

Step 3: Get a caller number ID

Step 4: Initiate the outbound call

Step 5: Store the call ID

Step 6: Check the result

Status reference

Next steps

Configure webhooks

Start bulk calls

​Prerequisites

​Step 1: Verify your workspace

​Step 2: Get an assistant ID

​Step 3: Get a caller number ID

​Step 4: Initiate the outbound call

​Step 5: Store the call ID

​Step 6: Check the result

​Status reference

​Next steps

Configure webhooks

Start bulk calls

Prerequisites

Step 1: Verify your workspace

Step 2: Get an assistant ID

Step 3: Get a caller number ID

Step 4: Initiate the outbound call

Step 5: Store the call ID

Step 6: Check the result

Status reference

Next steps