Skip to main content
Paths are relative to https://inkbox.ai/api/v1/whatsapp. Use the selected agent_identity_id query parameter where required. History remains tied to the original agent, not whoever later receives a phone number.

​
List conversations

Returns a bare array ordered by recent activity. limit defaults to 50 and accepts 1–200; offset defaults to 0. The optional is_blocked filter is available only within the caller’s authorized visibility.
Python
TypeScript
CLI

​
Find conversations with a person

Use either optional filter:
Filters apply before pagination, include authorized direct and group conversations, and return each matching conversation once. A contact with no applicable phone numbers returns an empty list. Omitting both filters preserves the existing list. Invalid selectors or supplying both returns 422; an unknown or inaccessible contact returns 404. Filters do not expand access to messages or group members.

​
Conversation fields

Every conversation contains id, agent_identity_id, local_number, nullable remote_number, participants, is_group, nullable group_name, unresolved_participant_count, created_at, and updated_at. For direct messages, remote_number is the remote E.164 number and participants remains a singleton array. For groups, remote_number is null and participants contains known remote E.164 numbers; the local number is separate. unresolved_participant_count counts members whose phone number is unavailable. group_name is a display label, not an address or unique identifier. Use the returned id as conversation_id when replying. Groups are joined outside Inkbox and require an incoming message before outbound communication. Names do not grant access; current contact permissions still apply. Groups are included in authorized lists without a separate opt-in. Older strict clients that require non-null phone numbers cannot parse group responses, including an entire list containing even one group; update them to SDK 0.7.29 or later before processing groups. List entries also contain:

​
Get a conversation

Returns a flat conversation object, not embedded message history. Read its messages with GET /messages?conversation_id=.... An inaccessible or unknown conversation returns 404. Use its ID to send another message in the same conversation. Reading a conversation does not enable a disabled channel or transfer its history to another identity.

​
Mark local history read

Provide both UUIDs:
Only visible inbound messages through that message boundary are marked read. Newer arrivals remain unread. The response is { "conversation_id": "...", "updated_count": 1 }. This updates local history only; it does not send a remote read receipt.
Python
TypeScript
CLI

​
Date filters

Both message and conversation lists accept start_datetime, end_datetime, and tz. Bounds filter created_at; start and end instants are inclusive. A bare end date includes the entire calendar day. Zone-less values use the supplied IANA timezone, or UTC by default. Explicit-offset timestamps retain their own timezone. Filtering happens before pagination.