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.

📄️List users assignable to conversations

Returns the list of team members of your company that can be assigned to a conversation. Use this to populate an assignee picker in your application before calling the assign endpoint. Each entry includes the user ID required as input by POST /conversations/{chatId}/assignee, the display name, and an optional avatar URL. Returns 401 if the API key is missing or invalid. Returns 502 if the upstream user-profile service is temporarily unavailable; this is a transient condition and the request can be safely retried after a short delay.

📄️Assign a conversation to a team member

Assigns the specified conversation to a user of your company. The assignee becomes the primary owner of the conversation and will receive notifications for new inbound messages on it. A conversation can have at most one assignee — calling this endpoint replaces any existing assignment. To remove the assignee without replacing it, use DELETE on the same resource. The user being assigned must belong to your company; cross-company assignment is not supported and results in a 404. Returns 400 if the request body is missing or `userId` is null. Returns 404 if the conversation or the target user does not exist or does not belong to your account. Returns 401 if the API key is missing or invalid.

📄️Remove the assignee from a conversation

Clears the current assignee of the conversation, leaving it unassigned. The conversation itself remains active and continues to appear in the inbox; only the ownership link to a specific team member is removed. This operation is idempotent: calling it on a conversation that has no assignee succeeds and still returns 204. 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