Karibu WhatsApp API - Karibu Docs

Read and manage WhatsApp conversation threads, send messages, and look up senders and templates. Base path https://karibu.briq.tz/v1/whatsapp/*. Every endpoint is workspace-scoped (resolved from your X-API-Key).

Conversations (/conversations/*) read and manage threads. Messages (/messages/*) send and track. Senders (/senders/*) and Templates (/templates/*) are read-only lookups. Sends are async: 202 with { message_id, status: "pending" }, then poll or webhook.

Conversations and Messages use the envelope below. Senders and Templates are older reads that return the data shape directly (no envelope) and a plain 404 { "detail": "..." }.

Try any endpoint live from its page under Karibu WhatsApp in the API reference — add your X-API-Key and send.

Envelope

{ "success": true, "data": { }, "errors": null, "request_id": "uuid" }

On failure: success: false, errors: [{ code, message, field }].

Conversations

Method	Path	Does
`GET`	`/conversations`	List/search threads (`status`, `sender`, `recipient`, `search`).
`GET`	`/conversations/summary`	Inbox counts (total/open/unread/unassigned).
`GET`	`/conversations/{id}`	One thread.
`POST`	`/conversations/{id}/read`	Clear unread state.
`DELETE`	`/conversations/{id}`	Soft-delete (one-way).

To read a thread’s messages, filter the messages collection: GET /messages?conversation_id={id}. To find a thread by customer number: GET /conversations?recipient={phone}.

Messages

Each message type has its own send endpoint with a payload scoped to exactly its fields. Open any page and use Try it to send a live request. Send messages

Type	Page	Notes
`text`	Send a text message	Plain text, ≤4096 chars. Needs an open window.
`template`	Send a template message	Approved template; always allowed, reopens the window.
`media` IMAGE	Send an image	JPEG/PNG, ≤5MB, optional caption.
`media` VIDEO	Send a video	MP4/3GPP, ≤16MB, optional caption.
`media` DOCUMENT	Send a document	PDF/Office/text, ≤100MB, caption + filename.
`media` AUDIO	Send an audio message	AAC/MP3/M4A/OGG-OPUS/AMR, ≤16MB, no caption.
`interactive`	Send an interactive message	Buttons or list. Needs an open window.

Track messages

Method	Path	Page
`GET`	`/messages`	List messages — poll messages and inbound replies.
`GET`	`/messages/{id}`	Get message status — status, derived error, paired reply.
`POST`	`/messages/{id}/read`	Send read receipt — blue ticks for an inbound message.

Senders

Method	Path	Does
`GET`	`/senders`	List sender numbers (`is_active`, `is_default`).
`GET`	`/senders/{sender_id}`	One sender. Use its number, `phone_number_id`, or `id` as the `sender` value when sending or filtering.

Templates

Method	Path	Does
`GET`	`/templates`	List templates, cursor-paginated (`status`, `category`, `language`, `name_or_content`, `cursor`, `limit`, `sort`).
`GET`	`/templates/{template_id}`	One template. Send by `name`, not id; only `APPROVED` templates send.

Rules

One send endpoint, one send shape. POST /messages, discriminated by type (text / template / media / interactive). Provide exactly one target: to for first contact, or conversation_id to reply (recipient and sender then come from the thread). Sending both, or neither, is 422 VALIDATION_ERROR.
Async sends. A send returns 202 { message_id, status: "pending" }. Track via GET /messages/{id} or a webhook.
Window. Templates always go and reopen the 24h window; text / media / interactive need an open window or return 422 WINDOW_CLOSED. First contact should be a template.
Friendly sender. Filter conversations or pick a send sender with sender: its WhatsApp number, its phone_number_id, or its sender id (UUID). The UUID-only sender_id still works but is deprecated. Conversations and sends echo sender (the phone_number_id) back.
Internal ids everywhere. Endpoints take your internal message_id / conversation_id (not provider wamids). The read receipt resolves the provider id for you.
Phone format: E.164 digits, optional leading + (e.g. 255712000000). The send to and the ?recipient= filter are validated/normalised the same way.
window ({open, expires_at}) reflects the 24-hour service window.
Mark-read on a conversation clears inbox unread state; /messages/{id}/read is the WhatsApp read receipt.
Delete is soft and one-way; the thread leaves all lists.

Errors

Code	HTTP	Meaning
`WORKSPACE_REQUIRED`	403	Key not linked to a workspace.
`VALIDATION_ERROR`	422	Missing content for the `type`, or not exactly one of `to` / `conversation_id`.
`CONVERSATION_NOT_FOUND`	404	Not in your workspace (or deleted).
`MESSAGE_NOT_FOUND`	404	Message not in your workspace.
`INVALID_MESSAGE`	422	Read receipt target is outbound or has no provider id.
`WINDOW_CLOSED`	422	24h window closed; send a template.
`TEMPLATE_NOT_APPROVED` / `TEMPLATE_NOT_FOUND_OR_UNAPPROVED`	422 / 404	Template not approved or unknown.
`TEMPLATE_PARAM_COUNT_MISMATCH`	400	`variables` count does not match the template.
`NO_TEMPLATE_LINK`	404	Sender does not own the named template.
`NO_SENDER` / `NO_ACTIVE_SENDER`	400	No usable sender resolved.
`SENDER_NOT_FOUND` / `SENDER_INACTIVE`	404 / 400	Given `sender` is not in the workspace or not active.
`SENDER_AMBIGUOUS`	409	The `sender` number matches more than one sender. Pass the `phone_number_id` or sender id instead.
`RECIPIENT_UNDELIVERABLE` / `PHONE_NOT_REGISTERED`	422	Recipient unreachable or not on WhatsApp.
`PROVIDER_UNAVAILABLE`	422	Upstream provider could not process the send. No message was sent; retry shortly. `data.message_id` is present and pollable.
`WHATSAPP_REAUTH_REQUIRED`	422	WhatsApp account credentials expired; reconnect the account, then retry.
`SEND_FAILED`	422	The send could not be processed. Retry shortly.

This API never returns a 5xx. Every failure mode is a stable 4xx code above, so your integration can branch on errors[0].code without special-casing server faults. Transient provider problems surface as 422 PROVIDER_UNAVAILABLE (retry), and when a record was created the response still carries a pollable data.message_id. Walkthroughs with examples: conversations guide · messages guide · senders and templates guide.

Webhook events

Sends are async, so delivery status arrives by webhook (poll GET /messages/{id} as the pull alternative). Register a whatsapp webhook for your developer app (see Karibu Webhooks); Briq POSTs each event to it.

Event	When
`whatsapp.sent`	Accepted by the provider.
`whatsapp.delivered`	Delivered to the recipient device.
`whatsapp.read`	Read by the recipient.
`whatsapp.failed`	Send failed (adds `error_code`, `error_message`).
`whatsapp.received`	Inbound message from a customer.

Every callback is an HTTP POST with this envelope:

{
  "event": "whatsapp.delivered",
  "event_id": "evt_...",
  "app_id": "your-app-id",
  "service_type": "whatsapp",
  "timestamp": "2026-06-24T09:12:00Z",
  "data": {
    "message_id": "uuid",
    "conversation_id": "uuid",
    "provider_message_id": "wamid....",
    "recipient": "255712345678"
  }
}

data.message_id matches the message_id from your send response and GET /messages/{id} — use it to correlate.
whatsapp.failed adds data.error_code and data.error_message.
whatsapp.received carries from, message_type, content, and profile_name instead of recipient.
Status events for messages you sent via the API are routed to your webhook automatically (correlated by your API key); inbound events are routed by workspace.

Events are at-least-once — the same event_id may arrive more than once. Deduplicate on event_id (or event + data.message_id).

Verifying the signature

When your webhook has a signing secret, each request carries X-Briq-Signature plus X-Briq-Service-Type and X-Briq-App-ID. The signature is the HMAC-SHA256 hex digest of the JSON body re-serialized with sorted keys, keyed by your secret:

import hashlib, hmac, json

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    payload = json.loads(raw_body)
    expected = hmac.new(
        secret.encode(),
        json.dumps(payload, sort_keys=True).encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Sign over json.dumps(payload, sort_keys=True), not the raw bytes — key order is normalized before signing. Reveal or rotate the secret from Karibu Webhooks.

​Envelope

​Conversations

​Messages

​Senders

​Templates

​Rules

​Errors

​Webhook events

​Verifying the signature

Envelope

Conversations

Messages

Senders

Templates

Rules

Errors

Webhook events

Verifying the signature