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" }
  }'

From Node.js

Node 18 and newer have fetch built in. Keep the key in an environment variable on your server, never in browser code.

const res = await fetch("https://api.rimbra.app/ntf/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RIMBRA_NOTIFY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channel: "whatsapp", to: "+2348012345678", content: { text: "Your order has shipped" } }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.detail);

From Python

python

import os, requests

r = requests.post(
    "https://api.rimbra.app/ntf/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['RIMBRA_NOTIFY_KEY']}"},
    json={"channel": "whatsapp", "to": "+2348012345678", "content": {"text": "Your order has shipped"}},
    timeout=30,
)
r.raise_for_status()
print(r.json()["id"], r.json()["status"])  # queued → sent or failed

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
400	Something in the request is missing, e.g. the number has no country code. `detail` says what
422	No connected number to send from, the recipient isn’t on WhatsApp, or they opted out
429	Your workspace used its monthly social notifications allowance. Buy more in Billing → Usage or upgrade