Skip to main content
Briq’s WhatsApp Business API lets your backend send text, template, media, and interactive messages, read conversation history, and receive real-time delivery events (sent -> delivered -> read / failed) on your own webhook - all scoped to a Developer App you own. This page is the integrator’s overview: what to set up, the rules the API enforces, and how the pieces fit together. For payload-level detail, see the Karibu WhatsApp API reference.

​
Prerequisites

To send WhatsApp messages you need:
  1. A workspace with WhatsApp enabled (at least one approved sender number / WABA configured). New senders are onboarded via the Briq dashboard.
  2. A Developer App linked to that workspace. Every WhatsApp endpoint is workspace-scoped - a key with no workspace is rejected with 403. See Developer Apps.
  3. An active developer API key (X-API-Key header). Generate one in the Briq dashboard.
  4. At least one approved template if you intend to start conversations or message users outside the 24-hour window.
  5. Recipient phone numbers in E.164 digits-only format (no +, no spaces) - e.g. 255712345678.

​
The two rules that matter most

These two rules trip up most integrations. Internalize them before writing code.
1. The 24-hour customer-care window. WhatsApp only allows freeform messages (text, media, interactive) within 24 hours of the customer’s last inbound message. Outside that window you must send an approved template. Briq enforces this - freeform sends return WINDOW_CLOSED (HTTP 422) when the window is closed. Sending a template opens or refreshes the window.2. Templates must be APPROVED. You can only send a template whose admin status is APPROVED. Anything else returns TEMPLATE_NOT_APPROVED / TEMPLATE_NOT_FOUND_OR_UNAPPROVED.

​
What you can send

TypeEndpointWindow-gated?
Freeform textPOST /v1/whatsapp/messages/send-textYes (default)
Pre-approved templatePOST /v1/whatsapp/messages/send-templateNo - opens/refreshes the window
Media (image/document/video)POST /v1/whatsapp/messages/send-mediaYes (default)
Interactive (buttons/lists)POST /v1/whatsapp/messages/send-interactiveYes (default)
Read receipt for an inbound messagePOST /v1/whatsapp/messages/{message_id}/readn/a
See Sending messages for the narrative walkthrough.

​
Async sends: 200 vs 202

A successful send returns one of two statuses - treat both as success:
  • 200 (status: "sent") - the provider accepted the message immediately; provider_message_id is present.
  • 202 (status: "pending") - the message was queued to Briq’s async engine; provider_message_id is null and is filled in later.
Rely on delivery webhooks for the final outcome. The data.message_id returned by the send is the same id that appears in every webhook event - use it to correlate.

​
Two response shapes

Know which shape each endpoint uses so you parse correctly:
  • Messages endpoints (/v1/whatsapp/messages/*) return an envelope: { "success", "data", "errors", "request_id" }. Read errors[].code on failure.
  • Read endpoints (senders, conversations, templates) return the bare resource - a JSON array or object with no envelope. Errors use { "detail": "..." }.
Treat any non-2xx status as a failure regardless of body shape.

​
End-to-end flow

A typical first-contact notification flow:
  1. Find your sender. Call GET /v1/whatsapp/senders to get a sender_id. -> Senders & conversations
  2. Register a webhook for service_type: "whatsapp" and fetch its signing secret. -> Delivery events
  3. Open the conversation with a template (first contact is always outside the window). -> Templates
  4. Continue with freeform messages (text/media/interactive) while the window is open. -> Sending messages
  5. Track delivery via whatsapp.sent -> whatsapp.delivered -> whatsapp.read (or whatsapp.failed) on your webhook.
  6. Read inbound replies by polling the Conversations API (inbound webhooks are upcoming).

​
Quick start

# 1. Find a sender.
curl -s https://karibu.briq.tz/v1/whatsapp/senders -H "X-API-Key: YOUR_API_KEY"

# 2. Open the conversation with an approved template.
curl -s -X POST https://karibu.briq.tz/v1/whatsapp/messages/send-template \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sender_id": "SENDER_UUID", "template_name": "order_update", "recipient": "255712345678", "variables": { "1": "Asha" } }'

# 3. Inside the window, send freeform text.
curl -s -X POST https://karibu.briq.tz/v1/whatsapp/messages/send-text \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sender_id": "SENDER_UUID", "recipient": "255712345678", "body": "Thanks! Your order ships today." }'
For complete payload tables, error matrices, and copy-pasteable client snippets in cURL, Python, Node.js, and PHP, see the Karibu WhatsApp API reference.