Quickstart

Goes from signup to first successful API call.

Before you start

A Keebai account at app.keebai.com.
The developer.manage_tokens permission on your role. If your account doesn’t show API Keys, ask your tenant admin to grant it under System Settings → Roles.
At least one WhatsApp channel connected and one template approved by Meta.
Anything that speaks HTTP — curl, Postman, Insomnia, or your favorite SDK.

1. Create a token

Open API Keys

Go to System Settings → API Keys in the dashboard: app.keebai.com/system-settings/api-keys.Not seeing it? Your role is missing developer.manage_tokens. Ask an admin.

Create a new key

Click Create API Key. Three fields:

Name — anything descriptive. Sales backend, Nightly reports, Local dev.
Permissions (scopes) — only the ones the token will actually use. For this quickstart, pick messages:send and templates:read.
Expiration (optional) — we recommend 90 days. Leave blank for no expiry.

Copy the token

Keebai shows the token once. Format: kbai_pk_<64 hex chars>.

This is the only time you’ll see the full token. Store it in a secret manager (1Password, AWS Secrets Manager, GitHub Actions secrets, a local .env). If you lose it, you’ll have to revoke and create a new one.

2. List your approved templates

To send a template you need its template_name, language, and variable names. Pull them with GET /v1/templates:

curl https://api.keebai.com/v1/templates \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Expected response (HTTP 200):

{
  "items": [
    {
      "id": "65f3a1b2c3d4e5f6a7b8c9d0",
      "name": "welcome_v2",
      "language": "es",
      "status": "APPROVED",
      "category": "MARKETING",
      "parameter_format": "NAMED",
      "variables": ["name", "amount"]
    }
  ],
  "page": 0,
  "limit": 50,
  "total": 1
}

3. Send your first message

Grab the phone_number_id of your channel from GET /v1/whatsapp/numbers, then call POST /v1/messages with a template message:

curl -X POST https://api.keebai.com/v1/messages \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number_id": "100000000000001",
    "to": "+15551234567",
    "message": {
      "type": "template",
      "name": "welcome_v2",
      "language": "en_US",
      "variables": {
        "name": "Alex",
        "amount": "1500"
      }
    }
  }'

Expected response (HTTP 202):

{
  "message_id": "wamid.HBgL...",
  "status": "sent",
  "sent_at": "2026-05-13T00:00:00.000Z"
}

The message is on its way — WhatsApp usually delivers within seconds.

4. If something breaks

Status	Meaning	What to do
`401 Unauthorized`	Token is invalid, revoked, or expired.	Check you copied the full token (`kbai_pk_` prefix included). If it’s not in your active token list, mint a new one.
`403 Forbidden` (`INSUFFICIENT_SCOPE`)	Token doesn’t carry the scope the endpoint needs.	Mint a new token with the missing scopes checked.
`400 Bad Request`	Body is malformed or `phone_number_id` is off.	Check the JSON against the endpoint contract.
`429 Too Many Requests`	You hit the rate limit (60 req/min, 200 req/hour, 1,000 req/day per project).	Read `Retry-After-<window>` and wait. See Rate limits.

5. Where to next

TypeScript SDK

Skip writing HTTP by hand — use the typed client.

CLI

keebai login and keebai whatsapp messages send from your shell.

Manage tokens

Create, list, revoke, and rotate tokens.

Scopes

What each scope does and when to use it.

Bulk send

Send the same template to thousands of recipients and track status.

OpenAPI spec

Swagger UI with every endpoint, schema, and example.

Get started

Authentication

MCP

SDK

CLI

Agent Skills

Limits

Before you start

1. Create a token

2. List your approved templates

3. Send your first message

4. If something breaks

5. Where to next

TypeScript SDK

CLI

Manage tokens

Scopes

Bulk send

OpenAPI spec

​Before you start

​1. Create a token

​2. List your approved templates

​3. Send your first message

​4. If something breaks

​5. Where to next

TypeScript SDK

CLI

Manage tokens

Scopes

Bulk send

OpenAPI spec

Before you start

1. Create a token

2. List your approved templates

3. Send your first message

4. If something breaks

5. Where to next