Ringg AI APIs for Developers

Initiate Individual Call

Start a new outbound call to a specific recipient using your configured AI agent. This endpoint supports both immediate calls and scheduled calls for future execution.

Phone Number Format:

All phone numbers must include country code (e.g., +91 for India, +1 for US)
Invalid formats will result in call failure

Scheduled Calls

Use scheduled_at to schedule calls for a specific date and time:

"call_time": {
  "call_start_time": "09:00",
  "call_end_time": "18:00", 
  "timezone": "Asia/Kolkata",
  "scheduled_at": "2025-11-24T01:55:00"
}

Scheduled Calls: When scheduled_at is provided, the call will be queued and executed at that specific date and time. The time window (call_start_time and call_end_time) still applies as additional validation. Use this for precise scheduling of important calls.

Custom Variables

Use the custom_args_values field to pass dynamic data to your agent:

Reference variables in your agent prompt using @{{variable_name}} syntax
Common variables: callee_name, company_name, appointment_date, etc.
Variables are replaced with actual values during the call

Important Notes

Agent Configuration: Ensure your agent is properly configured with prompts and variables
From Numbers: Use phone numbers that are provisioned in your workspace
Credits: Each call consumes credits based on duration and destination
Retry Logic: Configure retry attempts for busy/failed calls in call_config

Headers

X-API-KEY

string

required

(Required) Your Ringg AI API key.

Example:

"7251cb4b-3373-43a4-844c-b27a1d45e0c9"

Body

application/json

name

string

required

The name of the person to call

Example:

"John Doe"

mobile_number

string

required

The phone number to call (must include country code, e.g., +91 for India)

Example:

"+1234567890"

agent_id

string

required

UUID of the agent that will handle the call

Example:

"830f767a-397e-4b39-82ff-235cd344e2f9"

from_number

string

required

The phone number to call from (with country code)

Example:

"+1987654321"

custom_args_values

object

Custom variables that will be replaced in the agent's prompt using @{{variable_name}} syntax

Show child attributes

custom_args_values.company_name

string

Company name for context

Example:

"XYZ Corp"

custom_args_values.appointment_date

string

Appointment date

Example:

"2025-01-20"

custom_args_values.product_name

string

Product name for sales calls

Example:

"Premium Service"

Example:

{
  "company_name": "XYZ Corp",
  "appointment_date": "2025-01-20",
  "product_name": "Premium Service"
}

call_config

object

(Optional) Override default call configuration

Show child attributes

call_config.idle_timeout_warning

integer

default:5

Seconds before idle warning (default: 5)

Example:

10

call_config.idle_timeout_end

integer

default:10

Seconds before call termination (default: 10)

Example:

15

call_config.max_call_length

integer

default:240

Maximum call duration in seconds (default: 240)

Example:

300

call_config.call_retry_config

object

Retry configuration for failed calls

Show child attributes

call_config.call_retry_config.retry_count

integer

Number of retry attempts

Example:

3

call_config.call_retry_config.retry_busy

integer

Minutes to wait if busy (default: 30)

Example:

30

call_config.call_retry_config.retry_not_picked

integer

Minutes to wait if not picked (default: 30)

Example:

30

call_config.call_retry_config.retry_failed

integer

Minutes to wait if failed (default: 30)

Example:

30

Example:

{
  "retry_count": 3,
  "retry_busy": 30,
  "retry_not_picked": 30,
  "retry_failed": 30
}

call_config.call_time

object

Time window configuration for calls

Show child attributes

call_config.call_time.call_start_time

string

default:08:00

When calls can start (default: 08:00)

Example:

"08:00"

call_config.call_time.call_end_time

string

default:20:00

When calls must end (default: 20:00)

Example:

"20:00"

call_config.call_time.timezone

string

default:Asia/Kolkata

Timezone for call times (default: Asia/Kolkata)

Example:

"Asia/Kolkata"

call_config.call_time.scheduled_at

string<date-time>

Schedule the call for a specific date and time (ISO 8601 format). When provided, the call will be queued and executed at this exact time. The call_start_time and call_end_time window still applies as additional validation. Use this for precise scheduling of individual calls. Format: YYYY-MM-DDTHH:MM:SS

Example:

"2025-11-24T01:55:00"

Example:

{
  "call_start_time": "08:00",
  "call_end_time": "20:00",
  "timezone": "Asia/Kolkata",
  "scheduled_at": "2025-11-24T01:55:00"
}

Example:

{
  "idle_timeout_warning": 10,
  "idle_timeout_end": 15,
  "max_call_length": 300,
  "call_retry_config": {
    "retry_count": 3,
    "retry_busy": 30,
    "retry_not_picked": 30,
    "retry_failed": 30
  },
  "call_time": {
    "call_start_time": "08:00",
    "call_end_time": "20:00",
    "timezone": "Asia/Kolkata",
    "scheduled_at": "2025-11-24T01:55:00"
  }
}

Response

Successful Response: Details about the initiated call.

status

string

Example:

"success"

data

object

Show child attributes

data.call_id

string

Example:

"31106b7c-9d02-4723-8b07-5bb8d90240cb"

data.call_direction

string

Example:

"outbound"

data.call_status

string

Example:

"ongoing"

data.initiated_at

string<date-time>

Example:

"2025-11-24T07:33:49.629642"

data.agent_id

string

Example:

"a31f36c4-c8ea-4c4b-9ad6-743dabacafbd"

data.custom_args_values

object

Custom variables passed in the request

Example:

{
  "callee_name": "abhishek",
  "mobile_number": "+912332423423",
  "transfer_to": "+917404243687"
}

message

string

Example:

"Call initiated successfully"

Get Started

Webhooks Setup

API Reference

Initiate Individual Call

Initiate Individual Call

Scheduled Calls

Custom Variables

Important Notes

Headers

Body

Response

Get Started

Webhooks Setup

API Reference

​Initiate Individual Call

​Scheduled Calls

​Custom Variables

​Important Notes

Headers

Body

Response

Initiate Individual Call

Scheduled Calls

Custom Variables

Important Notes