ConvoAI developer docs

What you can build#

The API gives you programmatic control over the same agents, contacts and conversations you manage in the dashboard. Common uses:

How it works#

ConvoAI sits between your customers' channels (the messenger on your website, WhatsApp through Meta's Cloud API, email, and Instagram, Messenger and SMS in private beta) and your team. Your application talks to ConvoAI's REST API and receives events through webhooks.

1. A customer messages your WhatsApp number (the example used here). Meta delivers the message to ConvoAI.
2. The agent searches its knowledge base, generates a reply with its AI engine and sends it back through the WhatsApp API.
3. ConvoAI sends a webhook to each URL you registered for the events it subscribes to, for example when the agent sends a reply or an appointment is created.
4. At any time your application can push data to ConvoAI (update knowledge, send messages, reply as a human) or read conversation history through the REST API.

Authentication#

Every request needs your secret API key, passed as a Bearer token in the Authorization header. A key belongs to your account and inherits your plan's limits. API access is included in the Pro and Enterprise plans; on other plans authenticated requests return 403 forbidden.

Generating an API key

1. Log in to your ConvoAI dashboard and open Settings.
2. In the API section, generate a key.
3. Copy it immediately. It is shown only once; ConvoAI stores a hash, never the key itself.

Keys expire 90 days after they are generated; requests with an expired key return 401 api_key_expired. Your account has one key at a time, so generating a new key replaces the old one, which stops working straight away.

# Every request carries this header
Authorization: Bearer YOUR_API_KEY

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

Verify your credentials

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

{
  "id": 17,
  "email": "you@yourbusiness.com",
  "plan": "pro",
  "subscription_status": "active",
  "agents_count": 2,
  "api_version": "v1",
  "rate_limit_per_minute": 300
}

Quick start#

From an API key to a registered webhook in four requests. IDs in the API are integers.

Step 1: List your agents

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

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 42,
      "name": "My Sales Agent",
      "business_name": "Acme Dental",
      "phone_number": "+14155550123",
      "status": "active",
      "training_status": "ready",
      "ai_enabled": true,
      "language": "en",
      "knowledge_count": 12,
      "widget": { "enabled": true, "embed_key": "…" },
      "created_at": "2026-01-15T10:30:00+00:00"
    }
  ]
}

Step 2: Push a knowledge document

curl -X POST https://convoai.cloud/api/v1/agents/42/knowledge/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer pricing",
    "doc_type": "text",
    "content": "Cleanings are $89. New-patient exams are $120."
  }'

Step 3: Send a WhatsApp message to a contact

The agent must be connected to WhatsApp, otherwise the API returns 422 unprocessable.

curl -X POST https://convoai.cloud/api/v1/agents/42/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."
  }'

{
  "status": "queued",
  "agent_id": 42,
  "to": "+14155559876"
}

Step 4: Register a webhook

curl -X POST https://convoai.cloud/api/v1/agents/42/webhooks/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/convoai",
    "events": ["message.sent", "conversation.resolved", "appointment.created"],
    "description": "Production webhook"
  }'

Rate limits#

Limits apply per API key over a sliding 60-second window.

Successful responses carry the current state of your window. X-RateLimit-Reset is the number of seconds until the oldest request in the window expires, not a timestamp.

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 41

Over the limit, the API returns 429 rate_limited with X-RateLimit-Remaining: 0 and Retry-After: 60.

Pagination#

List endpoints return 50 results per page. Pass ?page=2 (and so on) to move through results; next and previous hold ready-made URLs, or null at either end.

{
  "count": 137,
  "next": "https://convoai.cloud/api/v1/contacts/?page=2",
  "previous": null,
  "results": [ … ]
}

Versioning#

The version is part of the URL path: https://convoai.cloud/api/v1/. Pin your integration to /api/v1/ explicitly. A machine-readable OpenAPI 3.1 description is published at /api/v1/openapi.json.

Developer policies#

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

Next steps#