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.

Base URLs

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

Authentication

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

X-API-Key: YOUR_API_KEY

Single Trigger APIs

🚀 Quick Start: Want to test these APIs immediately? Check out our Postman Collection with all endpoints pre-configured and ready to import!

1. Get All Agents

GET /v1/campaigns/agents

Get All Agents

Header Parameters

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

Response

Success (200 OK)

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

cURL Example

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

2. Trigger Single Call

POST /v1/campaigns/trigger/single

Trigger a single AI call for testing purposes.

Header Parameters

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

Request Body

{
  "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

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

Success (200 OK)

{
  "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 -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)

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

3. Get Call Status

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

Get the status of a specific call by its call_id.

Path Parameters

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

Header Parameters

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

Response

Success (200 OK)

{
  "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

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

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

Contact our support team at contact@revrag.ai to configure your webhook URL.

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:

{
  "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

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

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

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

Email: contact@revrag.ai

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