The WhatsApp API

Send text and media, check status and read conversations from your code.

Authentication

Send your secret key from WhatsApp → API as a Bearer token. The base URL is https://api.rimbra.app/ntf/v1. Rotate the key from the same page if it is ever exposed; the old key stops working right away.

bash

curl https://api.rimbra.app/ntf/v1/whatsapp/numbers \
  -H "Authorization: Bearer $RIMBRA_NOTIFY_KEY"

Send a message

to is the recipient with country code. from is optional: pass a number ID from /whatsapp/numbers to pick the sender, otherwise your most recently connected number is used. The response is the message with status queued; it becomes sent or failed within seconds.

bash

curl -X POST https://api.rimbra.app/ntf/v1/messages \
  -H "Authorization: Bearer $RIMBRA_NOTIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+2348012345678",
    "content": { "text": "Your order has shipped" }
  }'

Send media

Add media_url, an https link Rimbra can download, and media_type: image, video, audio or document. The text becomes the caption.

json

{
  "channel": "whatsapp",
  "to": "+2348012345678",
  "content": {
    "text": "Your invoice",
    "media_url": "https://example.com/invoice-1042.pdf",
    "media_type": "document"
  }
}

Endpoints

Endpoint	Does
POST /messages	Send a text or media message
GET /messages, GET /messages/{id}	Recent messages and one message’s status
GET /whatsapp/numbers	Your numbers, their status and how many they sent today
GET /inbox/threads, GET /inbox/threads/{id}/messages	Conversations
GET /contacts, PATCH /contacts/{id}	Contact names and opt-outs
GET /usage?from=YYYY-MM-DD&to=YYYY-MM-DD	Daily sent, received and failed
GET, POST, PATCH, DELETE /webhooks	Webhook endpoints

Limits and errors

Contacts who reply STOP or UNSUBSCRIBE are opted out automatically. Turn messaging back on for them in Contacts.

Code	Meaning
401	The key is missing or wrong
422	The recipient isn’t on WhatsApp or has opted out
429	Your workspace used its monthly social notifications allowance. Buy more in Billing → Usage or upgrade