Chatbox AI developer docs

What you can build

The Public API is what a Shopify app, a WordPress plugin or your own backend is written against. It sends WhatsApp template and text messages, upserts contacts, posts orders (each status change messages the customer for you), and manages webhook subscriptions so your server hears about deliveries, failures, replies and button taps.

The MCP server exposes the same capabilities as tools for AI agents such as Claude, Cursor, VS Code and Codex. Connect it with the same API key, and the key's scopes decide what the agent is allowed to do. See the MCP server guide.

Base URL and versioning

https://api.chatboxai.dev/api/v1

Everything is versioned in the path. v1 will not change shape under you: fields get added, never renamed or removed. The MCP server lives at https://api.chatboxai.dev/mcp.

Quickstart

1. Create an API key

In the Chatbox AI dashboard, open Settings → API & Webhooks and create a key. Pick only the scopes you need: for this quickstart, templates:read and messages:send. The key is shown in full exactly once, so copy it straight into an environment variable:

export CHATBOX_API_KEY="cbk_live_YOUR_KEY"

2. List your templates

Anything you start must be an approved template, so find out which ones you have:

curl https://api.chatboxai.dev/api/v1/templates \
  -H "Authorization: Bearer $CHATBOX_API_KEY"

Count the {{n}} placeholders in each template's body: that is how many parameters your send has to supply, in order.

3. Send a template

curl -X POST https://api.chatboxai.dev/api/v1/messages/template \
  -H "Authorization: Bearer $CHATBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-shipped" \
  -d '{
    "to": "+919999900000",
    "template": "order_shipped",
    "language": "en",
    "reference": "order:1234:shipped",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Asha" },
          { "type": "text", "text": "#1234" },
          { "type": "text", "text": "Friday" }
        ]
      }
    ]
  }'

The response is the message, with status: "SENT". That means WhatsApp accepted it, not that it was delivered. Subscribe to message.delivered and message.failed through webhooks to find out what happened. The Idempotency-Key header makes a retry of the same request safe.

Next steps