Workspace data

Conversations

A conversation is the thread between one contact and one channel. It is created by the first inbound message and is what an inbox is built on — listing threads, reading their messages, and replying without repeating who the recipient is.

The conversation

A conversation is open or closed, and closing it is a workflow state rather than anything the recipient sees.

Field	Description
id	The thread's public id.
status	open or closed.
channel_id	The channel the thread runs on.
contact	The other party: id, phone, name and tag names.
assignee	Who owns the thread, if anyone. Its user id is a workspace MEMBER id, not a user id.
unread_count	How many inbound messages have not been marked read.
last_message_at	When anything last happened on the thread.
last_inbound_at, last_outbound_at	The last inbound and last outbound timestamps separately.
closed_at	When it was closed, if it is.

Endpoints

Available to an API key

GET/v1/conversationsGET/v1/conversations/{conversationId}GET/v1/conversations/{conversationId}/messagesPOST/v1/conversations/{conversationId}/messagesPOST/v1/conversations/{conversationId}/closePOST/v1/conversations/{conversationId}/reopen

Session credentials only

These are the human workflow endpoints. They require a user access token, because assignment, read state and internal notes are all about a person — a machine credential has no member to assign to.

POST/v1/conversations/{conversationId}/assignPOST/v1/conversations/{conversationId}/unassignGET/v1/conversations/{conversationId}/assignmentsPOST/v1/conversations/{conversationId}/readGET/v1/conversations/{conversationId}/notesPOST/v1/conversations/{conversationId}/notesDELETE/v1/conversations/{conversationId}/notes/{noteId}

Replying

The reply endpoint takes no recipient and no channel: both come from the conversation, which removes a whole class of mistake. It returns the same shape a direct send does.

curl

# The recipient and the channel come from the conversation, never the body.
curl -X POST https://whats.azzamkh.sa/api/v1/conversations/cnv_.../messages \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "تم شحن طلبك اليوم." }'

# 201 Created
# { "id": "msg_...", "status": "queued", "category": "utility", ... }

# Exactly one of "text" or "template" must be present.

Send exactly one of text or template. Sending both, or neither, is a 422.
A reply is always classified as utility. You cannot raise or lower its priority.
There is no media field. Attaching a file to a reply is not yet available.
A successful reply also marks the thread read.

Filters

Parameter	Values	Description
status	open, closed	Open or closed threads.
channel_id	ch_…	Threads on one channel.
assigned	me, unassigned, none, team, user:mem_…, team:tm_…	Who owns the thread. `me` and `team` are relative to the caller, so they mean nothing to an API key.
unread	true	Only the exact string `true` enables this filter.
q	string	Searches the CONTACT — their name or their number — not the message text.
tag	slug	A contact tag slug. Unlike the contact list, an id is not accepted here.
limit, after	—	Cursor pagination.

Unknown filter values are ignored

An unrecognised value is dropped rather than rejected. The reasoning is that a filter is a view preference, and failing a stale bookmark with a 422 is the worse outcome — but it does mean a typo silently widens your results.

Ordering

This list is not ordered by recent activity

Conversations come back ordered by id descending, which is stable for cursor pagination but is not the same as newest-activity-first. A thread whose last message is recent but whose id is old will not be hoisted to the front. If you need an activity-ordered inbox, sort what you have fetched, and be aware that a thread on an unfetched page will not appear.

Team scoping

A workspace can restrict which channels a team can see. Where that is configured, conversation access is filtered by it — on reads and writes alike.

An API key is never scoped. A machine credential has no team membership, so it sees every conversation in the workspace.
For a user, the visible set is every channel except those restricted to teams they are not in.
A thread on a channel outside your scope is a 403 CONVERSATION_ACCESS_DENIED, with the reason in details.
A thread in another workspace is a 404. The two are deliberately different answers: one tells you the thread exists and you may not see it, the other tells you nothing at all.