ConvoAI Developer Hub

What you can build

The ConvoAI API gives you full programmatic control over every part of the platform. Common use cases:

How it works

ConvoAI sits between Meta's WhatsApp Cloud API and your customers. Your application interacts with ConvoAI's REST API and receives events via webhooks.

1. A customer messages your WhatsApp number. Meta delivers it to ConvoAI via webhook.
2. ConvoAI's AI agent searches the knowledge base, generates a contextual reply using its AI engine, and sends it back through the WhatsApp API.
3. ConvoAI fires a webhook to your configured URL for every significant event (message received, lead qualified, appointment booked, handoff triggered).
4. Your application can also push data to ConvoAI — update knowledge, send messages, or read conversation history — via the REST API at any time.

Authentication

All API requests require a secret API key passed as a Bearer token in the Authorization header. Keys are scoped to your account and inherit your subscription limits.

Generating an API key

1. Log in to your ConvoAI dashboard
2. Go to Settings → API Keys
3. Click Generate New Key, give it a descriptive name
4. Copy the key immediately — it is only shown once

Key format

Live keys are prefixed ck_live_. Test keys (sandbox mode, no real WhatsApp messages sent) are prefixed ck_test_.

# All requests require this header
Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Example curl
curl https://app.convoai.cloud/api/v1/agents/ \
  -H "Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Verify your credentials

curl https://app.convoai.cloud/api/v1/me/ \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "usr_01HXYZ1234ABCD",
  "email": "you@yourbusiness.com",
  "plan": "pro",
  "agents_count": 2,
  "api_version": "v1.4"
}

Quick Start

Get from zero to sending your first API-triggered WhatsApp message in under 5 minutes.

Step 1 — List your agents

curl https://app.convoai.cloud/api/v1/agents/ \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "count": 1,
  "results": [
    {
      "id": "agt_01HXYZ1234ABCD",
      "name": "My Sales Agent",
      "status": "active",
      "phone_number": "+14155550123",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Step 2 — Push a knowledge base document

curl -X POST https://app.convoai.cloud/api/v1/agents/agt_01HXYZ1234ABCD/knowledge/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer 2026 Pricing",
    "content": "Our summer plans start at $49/mo. Enterprise quotes available.",
    "doc_type": "text"
  }'

Step 3 — Send a message to a contact

curl -X POST https://app.convoai.cloud/api/v1/agents/agt_01HXYZ1234ABCD/messages/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155559876",
    "type": "text",
    "text": "Hi! Your order has been confirmed. Reply anytime if you need help."
  }'

{
  "message_id": "msg_01HABC9876WXYZ",
  "status": "queued",
  "to": "+14155559876",
  "queued_at": "2026-05-10T14:22:01Z"
}

Step 4 — Register a webhook

curl -X POST https://app.convoai.cloud/api/v1/agents/agt_01HXYZ1234ABCD/webhooks/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/convoai",
    "events": ["lead.qualified", "appointment.booked", "handoff.triggered"],
    "secret": "whsec_your_signing_secret"
  }'

Rate Limits

Rate limits are applied per API key. All responses include rate limit headers.

When a limit is exceeded, the API returns 429 Too Many Requests. Inspect the response headers to determine when to retry:

X-RateLimit-Limit:     300
X-RateLimit-Remaining: 247
X-RateLimit-Reset:     1715349600
Retry-After:           12

API Versioning

The current stable version is v1.4. The version is specified in the URL path: https://app.convoai.cloud/api/v1/.

We will never make breaking changes within a major version. When a new major version is released, the previous version remains supported for a minimum of 12 months. Breaking change deprecations are announced via email, the changelog, and a Deprecation response header.

Developer Policies

By integrating with the ConvoAI API you agree to our developer policies. Read each document before going live — especially the Acceptable Use Policy, which governs what you may and may not send via WhatsApp.

Next steps