Skip to main content
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

1

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.
2

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.
3

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/template: 
curl -X POST https://api.keebai.com/v1/messages/template \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "phone_number_id": "100000000000001",
    "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

StatusMeaningWhat to do
401 UnauthorizedToken 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 RequestBody is malformed or phone_number_id is off.Check the JSON against the endpoint contract.
429 Too Many RequestsYou hit the rate limit (60 req/min, 1,000 req/hour per token).Back off, then retry with exponential backoff.

​
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.