Introduction
Overview Authentication Rate Limits
Agents API
GET /api/v1/agents POST /api/v1/agents GET /api/v1/agents/{id}
Conversations API
POST /api/v1/calls POST /api/v1/whatsapp
Webhooks
Event Types Verification

REST API Reference

Integrate CallAI's omnichannel capabilities directly into your CRM, ERP, or custom applications using our robust RESTful JSON API.

Authentication

All API requests require authentication via an API Key. You can generate an API Key from your CallAI Dashboard under Settings > Developers.

Pass the API key in the Authorization header as a Bearer token:

Authorization: Bearer <YOUR_API_KEY>

Rate Limits

To ensure platform stability, all endpoints are rate-limited to 100 requests per minute per IP/Account by default. Status code 429 Too Many Requests will be returned if limits are exceeded.

POST /api/v1/calls/initiate

Dispatch an outbound AI voice call to a designated phone number.

Request Body (JSON)

Field Type Description
agent_id String Unique identifier of the AI agent handling the call.
to_number String Destination phone number in international E.164 format.
metadata Object (Optional) Key-value pairs providing context to the agent (e.g., customer name, order ID).

Example Request

curl -X POST https://api.gocallai.ng/v1/calls/initiate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "ag_98f6d2b3", "to_number": "+2348012345678", "metadata": { "customer_name": "Adebayo", "order_status": "Shipped" } }'

Example Response

{ "status": "success", "data": { "call_id": "c_54fa89d1", "status": "queued" } }
POST /api/v1/whatsapp/send

Send a templated or free-form WhatsApp message using an AI agent.

Request Body (JSON)

Field Type Description
agent_id String Agent assigned to respond to replies from this message.
to_number String Destination phone number in international format.
message_type String Either template or text.
content String/Obj The message text or the template object parameters.

Webhooks

Webhooks allow your application to receive real-time notifications when events occur in CallAI. For instance, when a call finishes, CallAI can POST the call summary and recording URL to your server.

Webhooks are configured via the dashboard. Make sure your server successfully responds with a 200 OK status immediately upon receiving a webhook.