Skip to content
Dashboard

List conversations (inbox)

GET
/conversations
curl --request GET \
--url 'https://app.whatsetter.com/api/v1/conversations?channel=whatsapp&needs_reply=true&triage=prospect&limit=25' \
--header 'Authorization: Bearer <token>'

Leads with message activity, most recent first (your WhatSetter inbox), on WhatsApp, Instagram and Messenger. Each one says its channel, whether the agent answers it now (agent_active; a person’s reply pauses it until agent_paused_until), whether a person owes it an answer (needs_reply: the dashboard’s « To do » view, a message nobody answered within 48 hours or a next action overdue) and, on Instagram and Messenger, what the triage (« What the agent leaves aside » in the dashboard) read the last message as (triage_verdict).

Like GET /leads, participants of group-purpose campaigns are left out unless you filter on that campaign_id. Requires scope conversations:read.

campaign_id
string

Filter by campaign. Accepts the campaign’s campaign_id slug or its document id (both returned by GET /campaigns).

channel
string
Allowed values: whatsapp instagram facebook

One channel. whatsapp also returns the conversations from before the channel was recorded.

needs_reply
boolean

true: only the conversations a person owes an answer (the dashboard’s « To do » view). Leave it out for every conversation.

triage
string
Allowed values: prospect collab support personal spam friend no_text blocked unread

Instagram and Messenger: only the conversations whose last message the triage read this way. collab and support are left for the owner; personal, spam, friend, no_text and blocked get no reply.

limit
integer
default: 25 >= 1 <= 100
cursor
string

Opaque cursor from the previous page’s pagination.next_cursor.

Page of conversation summaries

Media typeapplication/json
object
data
Array<object>
object
lead_id
string
channel

facebook = Messenger, through a Facebook Page.

string
Allowed values: whatsapp instagram facebook
phone

Null on Instagram and Messenger.

string | null
whatsapp_id
string | null
ig_username

Instagram handle, without the @ (Instagram only).

string | null
account_id

Instagram and Messenger: the Instagram account the thread lives on (GET /instagram/accounts; for Messenger, the account its Page is linked to). Null when two accounts answer with the same agent.

string | null
name
string | null
status
string | null
qualified
boolean
replied
boolean
campaign_id
string | null
agent_active

The agent answers this conversation now: nobody took it over (/leads/{id}/handoff) and no person’s reply pauses it.

boolean
agent_paused_until

Instagram and Messenger: a person’s reply pauses the agent until then.

string | null format: date-time
needs_reply

A person owes it an answer (the dashboard’s « To do » view): a message nobody answered (within 48 hours, after 30 minutes), or a next action overdue. A message the triage left aside on purpose does not count.

boolean
triage_verdict

Instagram and Messenger: what the triage (« What the agent leaves aside » in the dashboard) read the last message as, when the agent answers every private message. Null elsewhere, and once the agent has answered.

string | null
Allowed values: prospect collab support personal spam friend no_text blocked unread
messages_count
integer
last_message_at
string | null format: date-time
last_message_direction
string | null
pagination
object
has_more
boolean
next_cursor
string | null
Example
{
"data": [
{
"channel": "whatsapp",
"triage_verdict": "prospect"
}
]
}

Missing, unknown or revoked API key

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

The key lacks the required scope (insufficient_scope), the plan does not have this part of the API (not_in_plan), or Instagram is not enabled on the workspace (instagram_not_enabled, Instagram routes)

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

Invalid parameter or body (also an invalid or expired cursor)

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}