List conversations

GET

/api/v1/conversations

const url = 'https://api.inside.chat/api/v1/conversations?website_id=example&status=unassigned';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.inside.chat/api/v1/conversations?website_id=example&status=unassigned' \
  --header 'Authorization: Bearer <token>'

Required scopes: conversation_read
Data access: –
MCP tool: conversations_list
Note: contact_id adds contact_read, contact_read_pii
Note: query adds message_content_read, contact_read_pii

Page stored conversations, including non-AI chats. Visitor/status/cursor and channel/team/subsite restrictions intersect before paging. query searches a literal subject prefix and needs content/PII scopes and flags. contact_id uses stored links and additionally needs contact_read/contact_read_pii, PII and unrestricted policy. Excludes unsaved live state; subjects need content/PII.

Authorizations

installation_token
oauth_client_credentials
conversation_read

Parameters

Query Parameters

website_id

required

string

/^web_[0-9]{1,20}_[1-9][0-9]{0,18}$/

An explicitly granted website.

visitor_id

string

<= 100 characters /^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

contact_id

Filter by stored website-owned contact/visitor links. Requires contact_read, contact_read_pii, PII data access and unrestricted installation policy. Intersects visitor/status/cursor; missing or erased contact associations yield an empty page.

string

<= 100 characters /^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

status

string

Allowed values: unassigned open pending closed resolved onhold

query

Literal trimmed prefix over stored conversation subject using native database collation. Requires message_content_read and contact_read_pii scopes plus both data flags. Intersects all current filters before paging; no transcript-body or remote search.

string

>= 1 characters <= 200 characters

limit

integer

>= 1 <= 100

cursor

Continue at the last delivered owned resource ID. Existing canonical base64 positive signed-64-bit numeric history cursors are also accepted for transcript and visitor history.

string

<= 100 characters /^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

Responses

200

Authorized result. Projection depends on current scopes and data policy.

application/json

object

data

required

object

data

required

Array<object>

<= 100 items

object

required

string

<= 100 characters /^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

visitor_id

required

string

<= 100 characters /^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

operator_id

required

Any of:

string
null

string

<= 100 characters /^opr_[0-9]{1,20}_[1-9][0-9]{0,9}$/

status

required

string

Allowed values: unassigned open pending closed resolved onhold unknown

platform

required

string

Allowed values: chat email voice sms messenger salesforce zendesk facebook line whatsapp twitter wechat apple_messages qr_code google_business_messages instagram kakao_talk viber unknown

started_at

required

string format: date-time

<= 40 characters

active

required

boolean

subject

required

Any of:

string
null

string

<= 4000 characters

next_cursor

required

Any of:

string
null

string

<= 100 characters /^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

coverage

required

Allowed value: persisted_conversations

Example

{
  "data": {
    "data": [
      {
        "status": "unassigned",
        "platform": "chat"
      }
    ],
    "coverage": "persisted_conversations"
  }
}

400

Invalid, duplicate or unsupported request parameters.

401

Missing, expired or revoked installation credential.

404

Resource not found or not permitted by current authority.

422

The requested capability is not available for application installations.

429

Per-app quota exceeded.

Headers

Retry-After

integer

>= 1

503

Enrollment, native service or required authority is unavailable.