# API Documentation (legacy)

> The AI Voice Calling Agent API provides a comprehensive platform for managing user campaigns, triggering automated outbound voice calls, and analyzing campaign performance. The system allows you to organize users into campaigns, attach relevant data, create triggers with AI-generated columns, and execute targeted calling campaigns.

URL: /api-reference/call-trigger-apis
Markdown: /api-reference/call-trigger-apis.md



## Base URLs [#base-urls]

* **Production**: `https://api.revrag.ai`
* **Staging**: `https://staging-api.revrag.ai`

## Authentication [#authentication]

All API requests require an API key to be included in the request headers:

```
X-API-Key: YOUR_API_KEY
```

## Single Trigger APIs [#single-trigger-apis]

> **🚀 Quick Start:** Want to test these APIs immediately? Check out our [Postman Collection](./postman-collection) with all endpoints pre-configured and ready to import!

### 1. Get All Agents [#1-get-all-agents]

**GET** `/v1/campaigns/agents`

Get All Agents

#### Header Parameters [#header-parameters]

| Parameter   | Type   | Required | Description                |
| ----------- | ------ | -------- | -------------------------- |
| `X-API-Key` | string | Yes      | API Key for authentication |

#### Response [#response]

**Success (200 OK)**

```json
[
  {
    "id": "agent_123e4567-e89b-12d3-a456-426614174000",
    "name": "customer-support-agent",
    "variables": [
      {
        "name": "customer_name",
        "type": "string",
        "default_value": null
      }
    ]
  }
]
```

#### cURL Example [#curl-example]

```bash
curl -X GET "https://staging-api.revrag.ai/v1/campaigns/agents" \
  -H "X-API-Key: YOUR_API_KEY"
```

***

### 2. Trigger Single Call [#2-trigger-single-call]

**POST** `/v1/campaigns/trigger/single`

Trigger a single AI call for testing purposes.

#### Header Parameters [#header-parameters-1]

| Parameter   | Type   | Required | Description                |
| ----------- | ------ | -------- | -------------------------- |
| `X-API-Key` | string | Yes      | API Key for authentication |

#### Request Body [#request-body]

```json
{
  "agent_id": "agent_123e4567-e89b-12d3-a456-426614174000",
  "to_phone_number": "+1234567890",
  "variable_fields": {
    "first_name": "John",
    "company": "Acme Inc."
  },
  "custom_metadata": {
    "campaign_type": "follow_up",
    "source": "web_form",
    "priority": "high"
  }
}
```

#### Request Parameters [#request-parameters]

| Parameter         | Type           | Required | Description                                                                                                     |
| ----------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `agent_id`        | string (uuid)  | Yes      | The ID of the agent                                                                                             |
| `to_phone_number` | string         | Yes      | Recipient phone number                                                                                          |
| `variable_fields` | object or null | No       | Variable fields for the call                                                                                    |
| `custom_metadata` | object or null | No       | Custom metadata fields for tracking and organization. This field is flexible and can accept any key-value pairs |

#### Response [#response-1]

**Success (200 OK)**

```json
{
  "success": true,
  "message": "Call triggered successfully",
  "to_phone_number": "+1234567890",
  "agent_id": "agent_123e4567-e89b-12d3-a456-426614174000",
  "call_id": "call_456e7890-f12c-34d5-b678-901234567890"
}
```

#### cURL Example [#curl-example-1]

```bash
curl -X POST "https://staging-api.revrag.ai/v1/campaigns/trigger/single" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_123e4567-e89b-12d3-a456-426614174000",
    "to_phone_number": "+1234567890",
    "variable_fields": {
      "first_name": "John",
      "company": "Acme Inc."
    },
    "custom_metadata": {
      "campaign_type": "follow_up",
      "source": "web_form",
      "priority": "high"
    }
  }'
```

**Validation Error (422)**

```json
{
  "detail": [
    {
      "loc": ["body", "to_phone_number"],
      "msg": "Invalid phone number format",
      "type": "value_error"
    }
  ]
}
```

***

### 3. Get Call Status [#3-get-call-status]

**GET** `/v1/campaigns/trigger/status/{call_id}`

Get the status of a specific call by its call\_id.

#### Path Parameters [#path-parameters]

| Parameter | Type          | Required | Description        |
| --------- | ------------- | -------- | ------------------ |
| `call_id` | string (uuid) | Yes      | The ID of the call |

#### Header Parameters [#header-parameters-2]

| Parameter   | Type   | Required | Description                |
| ----------- | ------ | -------- | -------------------------- |
| `X-API-Key` | string | Yes      | API Key for authentication |

#### Response [#response-2]

**Success (200 OK)**

```json
{
  "call_status": "ENDED",
  "call_id": "call_123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "agent_456e7890-f12c-34d5-b678-901234567890",
  "from_number": "+918045342561",
  "to_number": "+1234567890",
  "summary": "Customer inquired about pricing options for our services. Discussed various pricing tiers and provided information about premium features. Customer showed interest in upgrading their current plan.",
  "start_time": "2024-01-15T10:00:00.000000",
  "end_time": "2024-01-15T10:15:30.500000",
  "duration": 930.5,
  "disconnection_reason": "USER_HANGUP",
  "recording_url": "https://cdn.revrag.ai/voice/recordings/room_abc123def456/room_abc123def456_audio.mp4",
  "transcription": {
    "messages": [
      {
        "role": "assistant",
        "content": "Hello, this is Sarah from Customer Support. Am I speaking with John?",
        "timestamp": "2024-01-15T10:00:15.000000+00:00"
      },
      {
        "role": "user",
        "content": "Yes, this is John speaking.",
        "timestamp": "2024-01-15T10:00:25.000000+00:00"
      },
      {
        "role": "assistant",
        "content": "Great! I'm calling to follow up on your recent inquiry about our services.",
        "timestamp": "2024-01-15T10:00:35.000000+00:00"
      },
      {
        "role": "user",
        "content": "Yes, I was interested in learning more about the pricing options.",
        "timestamp": "2024-01-15T10:00:50.000000+00:00"
      }
    ]
  },
  "custom_variables": [
    {
      "key": "customer_tier",
      "description": "Customer subscription tier level",
      "value": "premium",
      "type": "string"
    },
    {
      "key": "account_balance",
      "description": "Current account balance in USD",
      "value": 1250.75,
      "type": "number"
    },
    {
      "key": "is_first_time_caller",
      "description": "Whether this is the customer's first call",
      "value": false,
      "type": "boolean"
    }
  ],
  "variables_fields": {
    "first_name": "John",
    "company": "Acme Inc."
  },
  "custom_metadata": {
    "campaign_type": "follow_up",
    "source": "web_form",
    "priority": "high"
  }
}
```

#### Response Parameters [#response-parameters]

| Parameter              | Type           | Description                                                                                                                                               |
| ---------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `call_status`          | string         | Current status of the call (QUEUED, RUNNING, or ENDED)                                                                                                    |
| `call_id`              | string (uuid)  | Unique identifier for the call                                                                                                                            |
| `agent_id`             | string (uuid)  | ID of the agent used for this call                                                                                                                        |
| `from_number`          | string         | Phone number from which the call was made                                                                                                                 |
| `to_number`            | string         | Phone number to which the call was made                                                                                                                   |
| `summary`              | string         | AI-generated summary of the call conversation                                                                                                             |
| `start_time`           | string         | ISO 8601 timestamp when the call started                                                                                                                  |
| `end_time`             | string         | ISO 8601 timestamp when the call ended                                                                                                                    |
| `duration`             | number         | Call duration in seconds                                                                                                                                  |
| `disconnection_reason` | string         | Reason why the call ended (see Disconnection Reason Values)                                                                                               |
| `recording_url`        | string         | URL to the call recording (MP4 format)                                                                                                                    |
| `transcription`        | object         | Full transcription of the call with messages and timestamps                                                                                               |
| `custom_variables`     | array          | AI-extracted variables from the conversation during the call                                                                                              |
| `variables_fields`     | object or null | The original variable fields that were passed when triggering the call (note: the request body uses `variable_fields`; the response key has an extra `s`) |
| `custom_metadata`      | object or null | The original custom metadata that was passed when triggering the call                                                                                     |

#### cURL Example [#curl-example-2]

```bash
curl -X GET "https://staging-api.revrag.ai/v1/campaigns/trigger/status/call_123e4567-e89b-12d3-a456-426614174000" \
  -H "X-API-Key: YOUR_API_KEY"
```

***

### 4. Webhook Notifications (Optional) [#4-webhook-notifications-optional]

Instead of polling the call status endpoint, you can configure a webhook URL to receive real-time call completion notifications. When a call ends, we'll automatically send the same response body structure as the "Get Call Status" API to your webhook endpoint.

#### Webhook Configuration [#webhook-configuration]

Contact our support team at **[contact@revrag.ai](mailto:contact@revrag.ai)** to configure your webhook URL.

#### Webhook Payload [#webhook-payload]

The webhook will receive a **POST** request with the same JSON structure as the call status response, including the original values you passed as `variable_fields` (echoed back on the payload as `variables_fields`) and `custom_metadata`:

```json
{
  "call_status": "ENDED",
  "call_id": "call_123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "agent_456e7890-f12c-34d5-b678-901234567890",
  "from_number": "+918045342561",
  "to_number": "+1234567890",
  "summary": "Customer inquired about pricing options for our services. Discussed various pricing tiers and provided information about premium features. Customer showed interest in upgrading their current plan.",
  "start_time": "2024-01-15T10:00:00.000000",
  "end_time": "2024-01-15T10:15:30.500000",
  "duration": 930.5,
  "disconnection_reason": "USER_HANGUP",
  "recording_url": "https://cdn.revrag.ai/voice/recordings/room_abc123def456/room_abc123def456_audio.mp4",
  "transcription": {
    "messages": [
      {
        "role": "assistant",
        "content": "Hello, this is Sarah from Customer Support. Am I speaking with John?",
        "timestamp": "2024-01-15T10:00:15.000000+00:00"
      },
      {
        "role": "user",
        "content": "Yes, this is John speaking.",
        "timestamp": "2024-01-15T10:00:25.000000+00:00"
      }
    ]
  },
  "custom_variables": [
    {
      "key": "customer_tier",
      "description": "Customer subscription tier level",
      "value": "premium",
      "type": "string"
    },
    {
      "key": "account_balance",
      "description": "Current account balance in USD",
      "value": 1250.75,
      "type": "number"
    },
    {
      "key": "is_first_time_caller",
      "description": "Whether this is the customer's first call",
      "value": false,
      "type": "boolean"
    }
  ],
  "variables_fields": {
    "first_name": "John",
    "company": "Acme Inc."
  },
  "custom_metadata": {
    "campaign_type": "follow_up",
    "source": "web_form",
    "priority": "high"
  }
}
```

***

### Call Status Values [#call-status-values]

| Status    | Description                   |
| --------- | ----------------------------- |
| `QUEUED`  | Call is queued for execution  |
| `RUNNING` | Call is currently in progress |
| `ENDED`   | Call has ended                |

### Disconnection Reason Values [#disconnection-reason-values]

When a call ends, the `disconnection_reason` field indicates why the call was terminated:

| Reason               | Description                                                                      |
| -------------------- | -------------------------------------------------------------------------------- |
| `USER_HANGUP`        | The callee hung up the call                                                      |
| `USER_REJECTED`      | Callee rejected the call (busy)                                                  |
| `MAX_DURATION`       | The set maximum call duration was reached                                        |
| `VOICEMAIL_REACHED`  | Voicemail was reached                                                            |
| `AGENT_HANGUP`       | The agent ended the call as per prompt or upon detecting conversation completion |
| `SILENCE_TIMEOUT`    | Callee was silent for longer than the configured silence timeout period          |
| `CALL_NOT_PICKED`    | Call was not picked up by the callee                                             |
| `ERROR_OCCURRED`     | An error occurred during the call                                                |
| `CALL_NOT_CONNECTED` | Call was not connected due to Telephony Issue                                    |
| `CALL_DROPPED`       | Call was dropped in Between due to Network Issues                                |

***

## Support [#support]

If you encounter any issues or need assistance with the API, please contact our support team:

**Email**: [contact@revrag.ai](mailto:contact@revrag.ai)

Our team will respond to your inquiries and help resolve any technical issues you may experience while using the API.