Skip to main content
A conversation is a thread between one of your WhatsApp senders and a customer number. All endpoints are scoped to the workspace behind your X-API-Key. Full reference and live try-it: Karibu WhatsApp API.
Phone numbers are E.164 digits, optional leading + (e.g. 255712345678). Threads are addressed by their internal conversation_id.

​
List

Most recent first. Filter by status (all/open/unread), sender, recipient, or search.
Each item carries unread_count and window ({open, expires_at}), so one call renders an inbox. Each item also echoes the sender: sender_id (internal UUID), sender (the sender’s phone_number_id), and sender_display_number (the human number).

​
Filter by sender

To see only the threads handled by one of your WhatsApp numbers, pass sender. It accepts any of three forms, so use whichever you have on hand:
If the value matches no sender in your workspace you get 404 SENDER_NOT_FOUND; if a number matches more than one sender you get 409 SENDER_AMBIGUOUS, in which case pass the phone_number_id or sender id instead.
sender_id (the UUID-only query param) still works but is deprecated. Prefer sender.

​
Summary

​
Get one conversation

Fetch one thread by internal id.

​
Find by recipient

Filter the list by the customer number. A number can match more than one thread (one per sender), so this returns a list; pass sender to narrow it.

​
Read a thread’s messages

Messages live on the messages collection. Scope to one thread with conversation_id, and filter with direction, message_type, status, since/until. See the messages guide.

​
Mark read

Clears inbox unread state (not a WhatsApp read receipt). up_to defaults to now.

​
Delete

Soft-delete, one-way; the thread leaves all lists.