Skip to main content

Inbox

Manage two-way conversations with your contacts.

📄️List inbox conversations

Returns all two-way conversations for your account. A conversation groups every message exchanged with a single contact on a given channel (WhatsApp, RCS, etc.) into one thread. Conversations are created automatically when a contact sends an inbound message or when you send a reply through the Inbox. Use the filter parameters to narrow results: dateFrom limits to conversations updated after a given ISO date, channelIds restricts to one or more channels, and unreadOnly=true returns only conversations that contain messages you have not yet marked as read. Sorting is controlled by orderBy; prefix the field name with - for descending or + for ascending (e.g. -lastMessageDate for newest first). Each returned conversation includes an unread counter. To clear it, call PATCH /conversations/{chatId}/read. Conversations you no longer need in your default view can be moved out with PATCH /conversations/{chatId}/archive and restored later with PATCH /conversations/{chatId}/unarchive. A 401 response means the API key is missing or invalid.

📄️Send a reply to a conversation

Sends a reply to an existing two-way conversation. The message is delivered on the same channel (WhatsApp, RCS, etc.) that the conversation was originally established on, so you do not need to specify the channel yourself. The reply is accepted asynchronously (202 Accepted) and queued for delivery; the actual delivery status can be tracked through the Webhooks delivery-status callback if you have configured one. The request body must include the conversation ID and the message content. Returns 400 if the request body is malformed or missing required fields. Returns 404 if the conversation does not exist or does not belong to your account. Returns 401 if the API key is missing or invalid. Note: some channels enforce a reply window (e.g. WhatsApp 24-hour window). Attempting to reply outside this window may result in the message failing to deliver.

📄️Archive a conversation

Archives a conversation, moving it out of the default inbox view so it no longer appears in the main conversation list returned by GET /conversations. Archiving is a soft operation: no messages are deleted, and the full conversation history is preserved. Use this to keep your inbox clean by hiding resolved or inactive conversations. If the contact sends a new inbound message to an archived conversation, the conversation will typically reappear in the active inbox. To restore an archived conversation manually, call PATCH /conversations/{chatId}/unarchive. Returns 204 on success with no response body. Returns 404 if the conversation does not exist or does not belong to your account. Returns 401 if the API key is missing or invalid.

📄️Get messages of a conversation

Returns the full message thread of a conversation, ordered chronologically. Each message includes direction (inbound or outbound), timestamp, content, and delivery status. For long threads, paginate by message ID: set idFrom to retrieve messages with an ID greater than or equal to a value, and idTo for messages with an ID less than or equal to a value. A typical pagination workflow is to fetch the first page without parameters, then use the highest message ID from the response as idFrom on subsequent calls to load newer messages. After reading messages, call PATCH /conversations/{chatId}/read to clear the unread counter for this conversation. Returns 404 if the chatId does not exist or does not belong to your account. Returns 401 if the API key is missing or invalid.

📄️Mark a conversation as read

Marks all messages in a conversation as read, resetting the unread counter to zero. Call this after your application has displayed the messages to the user so that the unreadOnly filter on GET /conversations accurately reflects which conversations still need attention. This operation is idempotent: calling it on a conversation that is already fully read has no effect and still returns 204. Returns 204 on success with no response body. Returns 404 if the conversation does not exist or does not belong to your account. Returns 401 if the API key is missing or invalid.

Last updated on