### Start Campaign V2 Request Example

Source: https://docs.ringg.ai/api-reference/endpoint/campaign/start-campaign-v2

This example demonstrates the structure of a request to start a campaign. Ensure you replace placeholder IDs with your actual values.

```json
{
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "list_id": "123e4567-e89b-12d3-a456-426614174000",
  "number_pool_id": "pool-uuid-here",
  "callback_url": "https://api.example.com/ringg/campaign-callback",
  "email_completion_user_ids": [
    "user-id-1",
    "user-id-2"
  ]
}
```

--------------------------------

### Start Campaign V2 Error Response Example

Source: https://docs.ringg.ai/api-reference/endpoint/campaign/start-campaign-v2

This example shows a potential error response when a required resource, such as a number pool, is not found.

```json
{
  "detail": "Number pool not found."
}
```

--------------------------------

### Make Large Campaign Calls Async Request Example

Source: https://docs.ringg.ai/api-reference/endpoint/campaign/make-large-campaign-calls-async

Example of how to make an asynchronous call to start a large campaign. Ensure processing is complete and balance is sufficient before using this endpoint.

```bash
curl --request POST "https://prod-api.ringg.ai/ca/api/v0/campaign/make-call-async" \
  --header "X-API-KEY: $RINGG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ \
    "agent_id": "your-agent-id", \
    "bulk_list_id": "your-bulk-list-id", \
    "from_numbers": ["your-from-number-id"], \
    "callback_url": "https://api.example.com/ringg/campaign-callback" \
  }'
```

--------------------------------

### Assistant Configuration Example

Source: https://docs.ringg.ai/api-reference/endpoint/assistant/get-assistant-by-id

An example of an assistant's configuration object, demonstrating custom variables, agent prompt, introductory message, and knowledge base details.

```json
{
  "custom_variables": {
    "callee_name": "string",
    "mobile_number": "string"
  },
  "agent_prompt": "You are a helpful sales assistant.",
  "intro_message": "Hello! I'm calling from Ringg AI.",
  "knowledge_base_id": "7a9c2d5e-4f6b-1a2b-3c4d-5e6f7a8b9c0d",
  "knowledge_base_name": "Product FAQ",
  "template_name": "sales",
  "template_label": "Sales Agent",
  "template_icon": "💼",
  "created_at": "2024-12-16T13:03:29.947147+00:00",
  "updated_at": "2024-12-16T14:15:32.123456+00:00",
  "tools": [],
  "secondary_language": "hi-IN",
  "secondary_voice_id": "4c6d8e3b-9f0a-5b2c-ad7e-3f6a9b8c5d7e",
  "template_type": "outbound"
}
```

--------------------------------

### Start Campaign V2

Source: https://docs.ringg.ai/api-reference/endpoint/campaign/start-campaign-v2

Initiates a campaign using the V2 API. This endpoint allows for starting a campaign with specified parameters.

```APIDOC
## POST /campaign/start-campaign-v2

### Description
Starts a campaign using the V2 API.

### Method
POST

### Endpoint
/campaign/start-campaign-v2

### Request Body
- **campaign_id** (string) - Required - The ID of the campaign to start.
- **start_time** (string) - Optional - The desired start time for the campaign in ISO 8601 format.

### Request Example
```json
{
  "campaign_id": "campaign_123",
  "start_time": "2024-01-01T10:00:00Z"
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the campaign start operation.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "status": "success",
  "message": "Campaign started successfully."
}
```

ERROR HANDLING:
- **400**: Bad Request - Invalid request parameters.
  - **detail** (string) - Description of the error.
- **401**: Unauthorized - Invalid or missing authentication.
  - **detail** (string) - Example: Invalid credentials
- **500**: Internal Server Error - An unexpected error occurred.
  - **detail** (string) - Example: An unexpected error occurred.
```

--------------------------------

### Initiate Individual Call V2

Source: https://docs.ringg.ai/api-reference/endpoint/calling/initiate-individual-call-v2

Initiates an individual call with basic request parameters. This is a minimal example demonstrating the essential fields required to start a call.

```APIDOC
## POST /v2/call/initiate/individual

### Description
Initiates an individual call to a specified number. This endpoint allows for the inclusion of custom arguments to dynamically pass data to the assistant and utilizes a smart formatter to normalize callee names.

### Method
POST

### Endpoint
/v2/call/initiate/individual

### Parameters
#### Request Body
- **name** (string) - Required - The name of the person to call.
- **mobile_number** (string) - Required - The mobile number of the person to call in E.164 format.
- **agent_id** (string) - Required - The ID of the agent to use for the call.
- **number_pool_id** (string) - Required - The ID of the number pool to use for the call.
- **custom_args_values** (object) - Optional - A key-value object for passing dynamic data to the assistant. Keys can be referenced in prompts using `@{{variable_name}}`.
  - **callee_name** (string) - Optional - The name of the callee.
  - **order_id** (string) - Optional - The order ID associated with the call.
- **smart_formatter** (object) - Optional - Configuration for normalizing callee names.
  - **extract_first_name** (boolean) - Optional - If true, extracts the first name from the callee's name.
  - **transliteration** (boolean) - Optional - If true, transliterates the callee's name.
  - **transliteration_language** (object) - Optional - Specifies the source and target languages for transliteration.
    - **source** (string) - Required - The source language code (e.g., "en").
    - **target** (string) - Required - The target language code (e.g., "hi").

### Request Example
```json
{
  "name": "John Doe",
  "mobile_number": "+919876543210",
  "agent_id": "your-agent-id",
  "number_pool_id": "your-number-pool-id",
  "custom_args_values": {
    "callee_name": "John",
    "order_id": "ORD-1042"
  },
  "smart_formatter": {
    "extract_first_name": true,
    "transliteration": true,
    "transliteration_language": {
      "source": "en",
      "target": "hi"
    }
  }
}
```

### Response
#### Success Response (200)
- **call_id** (string) - The unique identifier for the initiated call.

#### Response Example
```json
{
  "call_id": "call_abc123xyz789"
}
```

### Common failure checks
- **401 Unauthorized**: Missing or invalid `X-API-KEY`.
- **Validation error**: Missing required field, no number source provided, or both `from_number_id` and `from_number` set.
- **Call remains queued**: Issues with calling window, scheduled time, workspace credits, pool availability, or provider health.
- **Assistant says wrong data**: Prompt placeholders do not match `custom_args_values` keys.
```

--------------------------------

### cURL Request Example

Source: https://docs.ringg.ai/api-reference/endpoint/campaign/check-large-campaign-balance

Example of how to make a cURL request to check the campaign balance. Ensure you replace 'your-bulk-list-id' and set your API key.

```bash
curl --request POST "https://prod-api.ringg.ai/ca/api/v0/campaign/check-balance/your-bulk-list-id" \
  --header "X-API-KEY: $RINGG_API_KEY"
```

--------------------------------

### Assistant Template Type Example

Source: https://docs.ringg.ai/api-reference/endpoint/assistant/get-assistants

Defines the type of template used for the assistant, with 'outbound' as an example.

```yaml
template_type:
  type: string
  example: outbound
```

--------------------------------

### CSV Template Example

Source: https://docs.ringg.ai/api-reference/endpoint/contact/delete-contact-list

Example of the minimum required columns for a campaign CSV file. Ensure 'Mobile Number' is present and other columns match your assistant's variables.

```text
Mobile Number,Name,Policy ID,Due Date
+919876543210,John Doe,POL-123,20/10/2026
+919876543211,Jane Smith,POL-124,21/10/2026

```

--------------------------------

### Example Removal of Knowledge Base Content

Source: https://docs.ringg.ai/api-reference/endpoint/kb/edit-knowledge-base

Demonstrates how to remove files, URLs, and FAQs from a knowledge base by providing their IDs. Ensure you have retrieved the correct IDs using the 'Get Knowledge Base by ID' endpoint.

```json
{
  "files_to_remove": "[\"7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d\"]",
  "urls_to_remove": "[\"https://example.com/old-page\"]",
  "faqs_to_remove": "[\"9c0d1e2f-3a4b-5c6d-7e8f-9a0b1c2d3e4f\"]"
}
```

--------------------------------

### Get Call Details Response Example

Source: https://docs.ringg.ai/api-reference/endpoint/history/get-call-details

This snippet shows a successful response for retrieving call details, including metadata, recording URLs, and transcription.

```json
{
  "agent_id": "agent-123-456",
  "initiation_time": "2024-01-15T14:30:00Z",
  "recording_url": "https://example.com/recordings/call-123.mp3",
  "transcription_url": [
    {
      "bot": "Hello, how can I help you today?"
    },
    {
      "user": "I need information about my order"
    },
    {
      "bot": ">- I'd be happy to help you with that. Can you provide your order number?"
    },
    {
      "user": "Sure, it's ORDER-12345"
    }
  ]
}
```

--------------------------------

### Example CSV Calling List

Source: https://docs.ringg.ai/get-started/guides/create-campaign

This is an example of a CSV file format for uploading contacts. Ensure column names match assistant variables.

```csv
phone_number,callee_name,course_name
+919994008915,Sarath,JEE Advanced
+919731553396,Vikram,NEET
+917404156687,Sahil,Class 10 Foundation
```

--------------------------------

### Send the API key

Source: https://docs.ringg.ai/api-reference/quick-start/authentication

Ringg API requests use a workspace API key in the `X-API-KEY` header. This example shows how to include the API key in a GET request to the workspace endpoint.

```APIDOC
## GET /workspace

### Description
This endpoint is used as a simple authentication check by sending the API key in the request header.

### Method
GET

### Endpoint
https://prod-api.ringg.ai/ca/api/v0/workspace

### Parameters
#### Request Headers
- **X-API-KEY** (string) - Required - The workspace API key for authentication.

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

```javascript
const response = await fetch("https://prod-api.ringg.ai/ca/api/v0/workspace", {
  headers: {
    "X-API-KEY": process.env.RINGG_API_KEY
  }
});

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

const workspace = await response.json();
```

### Response
#### Success Response (200)
- **workspace_info** (object) - Contains information about the workspace.
  - **id** (string) - The unique identifier of the workspace.
  - **name** (string) - The name of the workspace.
  - **created_at** (string) - The timestamp when the workspace was created.
  - **credits** (number) - The available credits for the workspace.
  - **locked_credits** (number) - The number of locked credits.
  - **api_key** (string) - The workspace API key (redacted in response).

#### Response Example
```json
{
  "workspace_info": {
    "id": "7251cb4b-72a3-42dc-9586-edf0328e2973",
    "name": "Acme Support Workspace",
    "created_at": "2026-04-15T10:30:00.000000+00:00",
    "credits": 3025.0,
    "locked_credits": 0.0,
    "api_key": "redacted-api-key"
  }
}
```
```

--------------------------------

### Assistant Custom Variables Example

Source: https://docs.ringg.ai/api-reference/endpoint/assistant/get-assistants

Defines the structure for custom variables that can be passed when creating or updating an assistant. Includes examples for callee name, mobile number, company, and lead source.

```yaml
custom_variables:
  type: object
  example:
    callee_name: string
    mobile_number: string
    company: string
    lead_source: string
```

--------------------------------

### Edit Knowledge Base Request Example

Source: https://docs.ringg.ai/api-reference/endpoint/kb/edit-knowledge-base

This example demonstrates how to send a PATCH request to edit a knowledge base, including removing existing items and adding new ones. Ensure you provide the correct kb_id and format the data as specified.

```bash
curl -X PATCH https://prod-api.ringg.ai/ca/api/v0/external/kb \
-H "X-API-KEY: 7251cb4b-3373-43a4-844c-b27a1d45e0c9" \
-F "kb_id=550e8400-e29b-41d4-a716-446655440000" \
-F "files_to_remove='["7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d", "8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e"]'" \
-F "urls_to_remove='["https://example.com/old-page"]'" \
-F "faqs_to_remove='["9c0d1e2f-3a4b-5c6d-7e8f-9a0b1c2d3e4f", "0d1e2f3a-4b5c-6d7e-8f9a-0b1c2d3e4f5a"]'" \
-F "new_urls='["https://example.com/new-docs"]'" \
-F "new_faqs='[{"question": "Do you ship internationally?", "answer": "Yes, worldwide shipping available"}]'" \
-F "new_files=@/path/to/your/file.pdf"
```

--------------------------------

### Start Campaign

Source: https://docs.ringg.ai/llms.txt

Initiates a new campaign with the specified configuration.

```APIDOC
## POST /api/v1/campaign/start

### Description
Initiates a new campaign with the specified configuration.

### Method
POST

### Endpoint
/api/v1/campaign/start

### Parameters
#### Request Body
- **name** (string) - Required - The name of the campaign.
- **contact_list_id** (string) - Required - The ID of the contact list to use for the campaign.
- **script_id** (string) - Required - The ID of the script to use for the campaign.
- **from_number** (string) - Required - The phone number to use as the caller ID.
- **max_concurrent_calls** (integer) - Optional - The maximum number of concurrent calls for the campaign.

### Request Example
```json
{
  "name": "Q1 Sales Campaign",
  "contact_list_id": "cl_abc123",
  "script_id": "script_xyz789",
  "from_number": "+15551234567",
  "max_concurrent_calls": 10
}
```

### Response
#### Success Response (201)
- **campaign_id** (string) - The unique identifier of the newly created campaign.
- **status** (string) - The initial status of the campaign (e.g., 'pending').
```

--------------------------------

### Get Assistants

Source: https://docs.ringg.ai/api-reference/endpoint/assistant/get-assistants

Retrieves a list of all available assistants in your workspace. This is commonly used during setup to select an assistant for handling calls.

```APIDOC
## GET /agent/all

### Description
Retrieves a list of all available assistants in your workspace.

### Method
GET

### Endpoint
/agent/all

### Parameters
#### Header Parameters
- **X-API-KEY** (string) - Required - Your Ringg AI API key.

#### Query Parameters
- **limit** (integer) - Optional - Number of items to return (default: 20, max: 100).
- **offset** (integer) - Optional - Number of items to skip (default: 0).

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the response.
- **data** (object) - Contains the list of agents.
  - **agents** (array) - A list of assistant objects.
    - **id** (string) - The unique identifier for the assistant.
    - **agent_display_name** (string) - The display name of the assistant.
    - **agent_type** (string) - The type of the assistant (e.g., 'outbound').
    - **created_at** (string) - The timestamp when the assistant was created.
    - **updated_at** (string) - The timestamp when the assistant was last updated.
    - **template_name** (string) - The name of the template used for the assistant.
    - **template_label** (string) - The label of the template.
    - **template_icon** (string) - The icon associated with the template.
    - **template_source** (string) - The source of the template.
    - **call_count** (integer) - The number of calls handled by the assistant.

#### Response Example
{
  "status": "success",
  "data": {
    "agents": [
      {
        "id": "830f767a-397e-4b39-82ff-235cd344e2f9",
        "agent_display_name": "Sales Assistant",
        "agent_type": "outbound",
        "created_at": "2024-12-16T13:03:29.947147+00:00",
        "updated_at": "2024-12-16T14:15:32.123456+00:00",
        "template_name": "sales",
        "template_label": "Sales Agent",
        "template_icon": "💼",
        "template_source": "custom",
        "call_count": 47
      }
    ]
  }
}
```

--------------------------------

### Create Knowledge Base Request Example

Source: https://docs.ringg.ai/api-reference/endpoint/kb/create-knowledge-base

This snippet demonstrates how to create a knowledge base with a name, files, and URLs. Ensure you include your API key in the header. Files are processed asynchronously.

```yaml
post /external/kb
openapi: 3.0.0
info:
  title: Ringg AI API Documentation
  description: >-
    This is the documentation for the Ringg AI APIs. The Ringg AI API follows
    RESTful principles, making it intuitive and easy to integrate with your
    applications. All API requests should be made to the base URL. The API
    accepts and returns data in JSON format. Ensure your requests include the
    appropriate Content-Type header for POST and PATCH requests.
  version: 2.0.0
servers:
  - url: https://prod-api.ringg.ai/ca/api/v0
security: []
tags:
  - name: workspace
    description: Endpoints for managing your workspace.
  - name: agent
    description: Endpoints for managing assistants (agents).
  - name: calling
    description: Endpoints for making and managing calls.
  - name: campaign
    description: Endpoints for managing campaigns.
  - name: analytics
    description: Endpoints for accessing call analytics and performance metrics.
  - name: termination
    description: Endpoints for terminating active calls using different methods.
  - name: knowledgebase
    description: Endpoints for managing knowledge bases.
paths:
  /external/kb:
    post:
      tags:
        - knowledgebase
      summary: Create Knowledge Base
      description: >-
        Creates a new non-deterministic knowledge base. Rate limit: 10 requests
        per hour per workspace. File size limit: 2 MB per file, 5 MB total.
        Maximum 10 files and 20 URLs per request.
      operationId: createKnowledgeBase
      parameters:
        - name: X-API-KEY
          in: header
          description: (Required) Your Ringg AI API key.
          required: true
          schema:
            type: string
            example: 7251cb4b-3373-43a4-844c-b27a1d45e0c9
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: 
                - kb_name
              properties:
                kb_name:
                  type: string
                  description: (Required) Name of the knowledge base
                  example: Product Documentation
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: >-
                    (Optional) Array of files to upload (max 10 files, 2 MB
                    each, 5 MB total)
                urls:
                  type: string
                  description: (Optional) JSON string array of URLs to index (max 20 URLs)
                  example: '["https://example.com/docs", "https://example.com/faq"]'
                faqs:
                  type: string
                  description: (Optional) JSON string array of FAQ objects
                  example: >-
                    [{"question": "What is your return policy?", "answer":
                    "30-day money back guarantee"}]
      responses:
        '200':
          description: Knowledge base created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Knowledge Base creation initiated
                  kb_id:
                    type: string
                    example: 550e8400-e29b-41d4-a716-446655440000
                  processing_status:
                    type: string
                    example: pending
                  files_queued:
                    type: integer
                    example: 3
        '400':
          description: Bad Request - Invalid parameters or file size exceeded.
        '401':
          description: Unauthorized - Invalid or missing API key.
        '429':
          description: Rate limit exceeded - Maximum 10 requests per hour.
```

--------------------------------

### Get Workspace Info using cURL

Source: https://docs.ringg.ai/api-reference/endpoint/workspace/get-workspace-info

Use this cURL command to make a GET request to the workspace endpoint. Ensure you set the RINGG_API_KEY environment variable with your valid API key. This is useful for initial setup and backend connectivity checks.

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

--------------------------------

### Additional agent action examples

Source: https://docs.ringg.ai/get-started/guides/embedding-widget-agent-actions

Demonstrates handling 'show_promo_modal' with a simplified payload extraction, scrolling to a pricing section, and pre-filling an email form field.

```javascript
// Open a promo modal when the agent suggests a discount
window.addEventListener("show_promo_modal", (event) => {
  showPromoModal({ discount: event.detail.discount_pct });
});

// Scroll to the pricing section
window.addEventListener("scroll_to_pricing", () => {
  document.querySelector("#pricing")?.scrollIntoView({ behavior: "smooth" });
});

// Pre-fill a form field
window.addEventListener("prefill_email", (event) => {
  document.querySelector("input[name=email]").value = event.detail.email;
});
```

--------------------------------

### Create Knowledge Base with FAQs

Source: https://docs.ringg.ai/api-reference/endpoint/kb/create-knowledge-base

Example of creating a knowledge base with FAQ content. Ensure the 'faqs' field is a JSON string containing an array of question-answer objects.

```json
{
  "faqs": "[{{\"question\": \"What is your return policy?\", \"answer\": \"30-day money back guarantee\"}}]"
}
```

--------------------------------

### Successful Workspace Response

Source: https://docs.ringg.ai/api-reference/quick-start/authentication

This is an example of a successful JSON response when calling the GET /workspace endpoint, which can be used as a basic authentication check.

```json
{
  "workspace_info": {
    "id": "7251cb4b-72a3-42dc-9586-edf0328e2973",
    "name": "Acme Support Workspace",
    "created_at": "2026-04-15T10:30:00.000000+00:00",
    "credits": 3025.0,
    "locked_credits": 0.0,
    "api_key": "redacted-api-key"
  }
}
```

--------------------------------

### Get Workspace Numbers (curl)

Source: https://docs.ringg.ai/api-reference/endpoint/contact/delete-contact-list

Retrieve a list of available workspace number IDs. These IDs are required for the `from_numbers` parameter when starting a campaign.

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

```

--------------------------------

### Start a Bulk Campaign

Source: https://docs.ringg.ai/api-reference/tutorials/setting-up-bulk-calls

Initiate a bulk calling campaign by sending a POST request to the `/campaign/start` endpoint. Provide the `agent_id`, the `list_id` obtained from uploading the contact list, an array of `from_numbers` (caller IDs), and a `callback_url` for receiving campaign status updates.

```bash
curl --request POST "https://prod-api.ringg.ai/ca/api/v0/campaign/start" \
  --header "X-API-KEY: $RINGG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ 
    "agent_id": "your-agent-id",
    "list_id": "your-list-id",
    "from_numbers": ["your-from-number-id"],
    "callback_url": "https://api.example.com/ringg/campaign-callback"
  }'
```

--------------------------------

### Assistant Tools Example

Source: https://docs.ringg.ai/api-reference/endpoint/assistant/get-assistants

Specifies the format for tools that can be associated with an assistant. An empty array indicates no tools are currently configured.

```yaml
tools:
  type: array
  items:
    type: object
  example: []
```

--------------------------------

### Start Campaign

Source: https://docs.ringg.ai/skill.md

Initiates a campaign using an uploaded contact list.

```APIDOC
## POST /campaign/start

### Description
Starts a campaign using a previously uploaded contact list.

### Method
POST

### Endpoint
/campaign/start

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **bulk_list_id** (string) - Required - The ID of the contact list to use for the campaign.
- **agent_id** (string) - Required - The ID of the agent to handle the campaign calls.
- **campaign_name** (string) - Optional - A name for the campaign.

### Request Example
```json
{
  "bulk_list_id": "bl-pqrst",
  "agent_id": "ag-abcde",
  "campaign_name": "Follow-up Campaign"
}
```

### Response
#### Success Response (200)
- **campaign_id** (string) - The unique identifier for the started campaign.
- **status** (string) - The initial status of the campaign.

#### Response Example
```json
{
  "campaign_id": "camp-uvwxy",
  "status": "starting"
}
```
```

--------------------------------

### Get Call Details with Analysis Response Example

Source: https://docs.ringg.ai/api-reference/endpoint/history/get-call-details

This snippet illustrates a successful response for call details when analysis is requested, including sentiment, outcome, and lead scores.

```json
{
  "with_analysis": {
    "summary": "Call details with analysis (send_analysis=true)",
    "value": {
      "status": "success",
      "data": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "call_direction": "outbound",
        "call_status": "completed",
        "call_sub_status": "ACCEPTED",
        "from_number": "+1234567890",
        "to_number": "+0987654321",
        "callee_name": "John Doe",
        "agent_id": "agent-123-456",
        "initiation_time": "2024-01-15T14:30:00Z",
        "recording_url": "https://example.com/recordings/call-123.mp3",
        "transcription_url": [
          {
            "bot": "Hello, how can I help you today?"
          },
          {
            "user": "I need information about my order"
          },
          {
            "bot": ">- I'd be happy to help you with that. Can you provide your order number?"
          },
          {
            "user": "Sure, it's ORDER-12345"
          }
        ],
        "platform_analysis": {
          "sentiment": "positive",
          "call_outcome": "successful",
          "duration_score": 8.5
        },
        "client_analysis": {
          "lead_score": 85,
          "follow_up_required": true,
          "customer_satisfaction": "high"
        }
      }
    }
  }
}
```

--------------------------------

### Start Campaign (curl)

Source: https://docs.ringg.ai/api-reference/endpoint/contact/delete-contact-list

Initiate a campaign using the saved `list_id` and selected `from_numbers`. A `callback_url` can be provided to receive real-time campaign status updates.

```bash
curl --request POST "https://prod-api.ringg.ai/ca/api/v0/campaign/start" \
  --header "X-API-KEY: $RINGG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ 
    "agent_id": "your-agent-id",
    "list_id": "your-list-id",
    "from_numbers": ["your-from-number-id"],
    "callback_url": "https://api.example.com/ringg/campaign-callback"
  }'

```

--------------------------------

### Assistant Secondary Language Example

Source: https://docs.ringg.ai/api-reference/endpoint/assistant/get-assistants

Specifies a secondary language for the assistant, with an example for Hindi-Indian.

```yaml
secondary_language:
  type: string
  nullable: true
  example: hi-IN
```

--------------------------------

### Assistant Secondary Voice ID Example

Source: https://docs.ringg.ai/api-reference/endpoint/assistant/get-assistants

Provides an example for a secondary voice ID, which can be used for assistant responses.

```yaml
secondary_voice_id:
  type: string
  nullable: true
  example: 4c6d8e3b-9f0a-5b2c-ad7e-3f6a9b8c5d7e
```

--------------------------------

### Example Custom Arguments Values

Source: https://docs.ringg.ai/api-reference/endpoint/campaign/upload-campaign-contact-list

Demonstrates the structure for custom arguments that can be provided for each contact in the uploaded list.

```json
[
  {
    "callee_name": "John Doe",
    "company_name": "XYZ Corp",
    "mobile_number": "+1234567890"
  }
]
```

--------------------------------

### Start Campaign V2 Success Response

Source: https://docs.ringg.ai/api-reference/endpoint/campaign/start-campaign-v2

A successful response indicates that the campaign has been registered and is ready to start processing calls.

```json
{
  "status": "campaign registered successfully!",
  "has_ongoing_calls": false
}
```

--------------------------------

### POST /campaign/make-call-async

Source: https://docs.ringg.ai/api-reference/endpoint/campaign/make-large-campaign-calls-async

Starts a large campaign by scheduling calls asynchronously. This beta endpoint requires a `bulk_list_id` obtained from `/campaign/upload-csv`, along with agent and campaign details.

```APIDOC
## POST /campaign/make-call-async

### Description
Beta endpoint for starting calls from a draft bulk list created by `/campaign/upload-csv`.

### Method
POST

### Endpoint
/campaign/make-call-async

### Parameters
#### Header Parameters
- **X-API-KEY** (string) - Required - Your Ringg AI API key.

#### Request Body
- **bulk_list_id** (string) - Required - Draft bulk list ID returned by `/campaign/upload-csv`.
- **agent_id** (string) - Required - Assistant ID used during upload.
- **country_code** (string) - Required - Phone number country code.
- **campaign_start_time** (string) - Required - Campaign start time in DD/MM/YYYY, HH:MM format.
- **campaign_end_time** (string) - Required - Campaign end time in DD/MM/YYYY, HH:MM format.
- **from_numbers** (array of strings) - Optional - Explicit list of FromNumber UUIDs / phone numbers. Provide exactly one of `from_numbers` or `number_pool_id`.
- **number_pool_id** (string) - Optional - Managed number pool ID (rotation, spam skipping, auto-purchase). Provide exactly one of `from_numbers` or `number_pool_id`.
- **call_config** (object) - Required - Configuration for the calls.
  - **call_retry_config** (object) - Optional - Configuration for retrying calls.
    - **retry_count** (integer) - Optional - Number of times to retry a call. Defaults to 0.
    - **retry_busy** (integer) - Optional - Time in seconds to wait before retrying a busy call. Defaults to 30.
    - **retry_not_picked** (integer) - Optional - Time in seconds to wait before retrying a call that was not picked up. Defaults to 30.

### Request Example
```json
{
  "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "country_code": "+91",
  "campaign_start_time": "18/10/2026, 09:00",
  "campaign_end_time": "18/10/2026, 18:00",
  "from_numbers": [
    "from-number-id"
  ],
  "call_config": {
    "call_retry_config": {
      "retry_count": 1,
      "retry_busy": 30,
      "retry_not_picked": 30
    }
  }
}
```

### Response
#### Success Response (200)
- **bulk_list_id** (string) - The ID of the bulk list.
- **status** (string) - The status of the campaign scheduling (e.g., "scheduled").
- **message** (string) - A confirmation message indicating the campaign calls have been queued.

#### Response Example
```json
{
  "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "scheduled",
  "message": "Large campaign calls queued"
}
```
```

--------------------------------

### Get all agents

Source: https://docs.ringg.ai/api-reference/quick-start/guide

Retrieve a list of available agents using the GET /agent/all endpoint. This is used to select an assistant for running calls.

```bash
curl --request GET "$RINGG_BASE_URL/agent/all" \
  --header "X-API-KEY: $RINGG_API_KEY"
```

--------------------------------

### Load and Configure Ringg AI Widget

Source: https://docs.ringg.ai/get-started/guides/embedding-widget-configuration

This snippet demonstrates how to load the Ringg AI widget CDN and initialize it with essential configuration options like agent ID, API key, runtime variables, and UI customizations.

```javascript
loadAgentsCdn("latest", function () {
  loadAgent({
    agentId: "your-agent-id",
    xApiKey: "your-api-key",
    variables: {
      callee_name: "John",
      account_id: "ACC-42",
    },
    defaultTab: "audio",
    hideTabSelector: false,
    title: "Talk to our assistant",
    description: "Ask a question or start a voice call.",
    buttons: {
      modalTrigger: {
        styles: {
          backgroundColor: "#4F46E5",
          color: "white",
          borderRadius: "50%",
        },
      },
      call: {
        textBeforeCall: "Start Call",
        textDuringCall: "End Call",
      },
    },
    widgetPosition: {
      triggerPlacement: "fixed",
      triggerAlignment: "bottom-right",
      hideTriggerOnExpand: true,
      widgetAlignment: "bottom-right",
    },
  });
});
```

--------------------------------

### Start Campaign

Source: https://docs.ringg.ai/api-reference/endpoint/contact/delete-contact-list

Initiates a campaign using the previously uploaded contact list. Requires the list ID and caller numbers.

```APIDOC
## POST /campaign/start

### Description
Starts a campaign using a specified contact list and caller numbers.

### Method
POST

### Endpoint
https://prod-api.ringg.ai/ca/api/v0/campaign/start

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent to use for the campaign.
- **list_id** (string) - Required - The ID of the contact list to use for the campaign (obtained from `/campaign/save`).
- **from_numbers** (array of strings) - Required - An array of number IDs to be used as caller numbers.
- **callback_url** (string) - Optional - A URL to receive campaign status callbacks.

### Request Example
```json
{
  "agent_id": "your-agent-id",
  "list_id": "your-list-id",
  "from_numbers": ["your-from-number-id"],
  "callback_url": "https://api.example.com/ringg/campaign-callback"
}
```
```

--------------------------------

### Get workspace numbers

Source: https://docs.ringg.ai/api-reference/quick-start/guide

Retrieve a list of available caller numbers using the GET /workspace/numbers endpoint. Save the ID of the number you want Ringg to use for calls.

```bash
curl --request GET "$RINGG_BASE_URL/workspace/numbers" \
  --header "X-API-KEY: $RINGG_API_KEY"
```

--------------------------------

### Save and Start Campaign API Flow

Source: https://docs.ringg.ai/get-started/guides/create-campaign

For standard API usage, developers should first save the campaign configuration and then initiate the campaign.

```http
POST /campaign/save
POST /campaign/start
```

--------------------------------

### Get Call Details OpenAPI Specification

Source: https://docs.ringg.ai/api-reference/endpoint/history/get-call-details

This OpenAPI specification defines the GET /calling/call-details endpoint, including parameters for call ID and analysis inclusion, and response schemas.

```yaml
openapi: 3.0.0
info:
  title: Ringg AI API Documentation
  description: >-
    This is the documentation for the Ringg AI APIs. The Ringg AI API follows
    RESTful principles, making it intuitive and easy to integrate with your
    applications. All API requests should be made to the base URL. The API
    accepts and returns data in JSON format. Ensure your requests include the
    appropriate Content-Type header for POST and PATCH requests.
  version: 2.0.0
servers:
  - url: https://prod-api.ringg.ai/ca/api/v0
security: []
tags:
  - name: workspace
    description: Endpoints for managing your workspace.
  - name: agent
    description: Endpoints for managing assistants (agents).
  - name: calling
    description: Endpoints for making and managing calls.
  - name: campaign
    description: Endpoints for managing campaigns.
  - name: analytics
    description: Endpoints for accessing call analytics and performance metrics.
  - name: termination
    description: Endpoints for terminating active calls using different methods.
  - name: knowledgebase
    description: Endpoints for managing knowledge bases.
paths:
  /calling/call-details:
    get:
      tags:
        - calling
      summary: Get Call Details
      description: >-
        Retrieves detailed information about a specific call using its unique
        identifier. Use the send_analysis parameter to include analysis data in
        the response.
      operationId: getCallDetails
      parameters:
        - name: X-API-KEY
          in: header
          description: (Required) Your Ringg AI API key.
          required: true
          schema:
            type: string
            example: 7251cb4b-3373-43a4-844c-b27a1d45e0c9
        - name: id
          in: query
          description: (Required) The unique identifier (UUID) of the call.
          required: true
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
        - name: send_analysis
          in: query
          description: >-
            (Optional) Whether to include analysis data (platform_analysis and
            client_analysis) in the response.
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: Call details retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The unique identifier of the call
                        example: 550e8400-e29b-41d4-a716-446655440000
                      call_direction:
                        type: string
                        description: The direction of the call
                        enum:
                          - inbound
                          - outbound
                          - webcall
                        example: outbound
                      call_status:
                        type: string
                        description: The current status of the call
                        enum:
                          - registered
                          - ongoing
                          - retry
                          - error
                          - completed
                          - failed
                          - cancelled
                          - forwarded
                        example: completed
                      call_sub_status:
                        type: string
                        description: >-
```

--------------------------------

### OpenAPI Specification for Get All Knowledge Bases

Source: https://docs.ringg.ai/api-reference/endpoint/kb/get-all-knowledge-bases

This OpenAPI 3.0 specification defines the GET /external/kb/all endpoint, detailing parameters, responses, and schemas for retrieving knowledge bases.

```yaml
get /external/kb/all:
  tags:
    - knowledgebase
  summary: Get All Knowledge Bases
  description: >-
    Retrieves all knowledge bases for the current workspace. Rate limit: 60
    requests per hour per workspace.
  operationId: getAllKnowledgeBases
  parameters:
    - name: X-API-KEY
      in: header
      description: (Required) Your Ringg AI API key.
      required: true
      schema:
        type: string
        example: 7251cb4b-3373-43a4-844c-b27a1d45e0c9
  responses:
    '200':
      description: List of all knowledge bases retrieved successfully.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                kb_id:
                  type: string
                  example: 550e8400-e29b-41d4-a716-446655440000
                kb_name:
                  type: string
                  example: Product Documentation
                type:
                  type: string
                  example: non_deterministic
                created_at:
                  type: string
                  format: date-time
                  example: '2024-12-16T13:03:29.947147+00:00'
    '401':
      description: Unauthorized - Invalid or missing API key.
    '429':
      description: Rate limit exceeded - Maximum 60 requests per hour.
```