Conversations

List conversations

Lists conversations in real time. limit accepts 1..100 and defaults to 20. type is a comma-separated list of exact user, group, or channel values with no trimming. On WhatsApp, omitting label_id returns only starred / “特别关注” conversations. Invalid or expired cursors may be rejected or may restart pagination depending on the provider.

GEThttps://api.unifyport.ai/v1/accounts/{account_id}/conversations

Before you call

Use a server-side X-Api-Key for the workspace that owns the resource. Replace every placeholder before running a sample.

Prepare your parameters

account_id: Use data.id from account creation or an account query. Account identifiers belong to the workspace selected by X-Api-Key. Get account

Request parameters

Headers

X-Api-Key

stringrequired

Workspace API key. The workspace is resolved from this header.

Path parameters

account_id

stringrequired

Identifier used in the conversations route.

Query parameters

type

string

Comma-separated exact values: user, group, or channel. Values are not trimmed or normalized, and empty entries are not ignored. Invalid values return 400 invalid_conversation_type. WhatsApp group includes community announcement groups; all WhatsApp group conversations return type=group.

cursor

string

Opaque provider cursor. Pass the previous next_cursor unchanged; omit or leave empty for the first page. Forged, expired, or cross-query cursors may be ignored, reset to the first page, or cause a provider error. Do not rely on a uniform 400 response.

limit

integer

Page size from 1 to 100. Endpoint descriptions state the endpoint-specific default.

minimum: 1 · maximum: 100

label_id

string

Exact provider label identifier. On WhatsApp, omitting it returns starred / “特别关注” conversations.

Request body

This endpoint does not require a JSON request body.

Understand the result

Use the documented response fields and HTTP status. Successful 204 responses have no body; use X-Request-Id for diagnosis. Follow the related operations for the next step.

Response 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "items": [
      {
        "conversation_id": "peer_example",
        "type": "user",
        "title": "Display name",
        "avatar_url": "",
        "unread_count": 3,
        "last_message_at": "2026-05-13T10:00:00Z"
      }
    ],
    "next_cursor": "",
    "has_more": false
  }
}

Response body

conversation_id

string

Conversation identifier. Use it as the target when sending messages or calling conversation routes.

type

string

Standard conversation type: user, group, or channel. WhatsApp community announcement groups continue to use group.

enum: user, group, channel

title

string

Display title of the conversation.

username

string

Provider username for the conversation, when available.

avatar_url

string

Avatar URL, or an empty string when none is set.

description

string

Group or channel description, when available.

last_message_at

string

RFC3339 timestamp of the most recent message.

format: date-time

last_message_text

string

Text preview of the most recent message, when available.

unread_count

integer

Number of unread messages in the conversation.

format: int64

members_count

integer

Number of members; returned for group conversations.

format: int64

subscribers_count

integer

Subscriber count for channel-style conversations, when available.

format: int64

is_pinned

boolean

Whether the connected account pinned the conversation.

is_muted

boolean

Whether the connected account muted the conversation.

created_at

string

Provider-reported conversation creation time, when available.

format: date-time

extra

object

Provider-specific fields. WhatsApp group conversations may include announcement-group classification; conversation lists do not guarantee that classification is available.

is_announcement_group

boolean

Only for WhatsApp groups. true confirms a community announcement group; false means the current data confirms the announcement-group criteria are not met. Missing means unknown; null is never returned. This classification does not indicate that the current account can send messages.

next_cursor

string

Opaque cursor for the next page. Pass it back as cursor; an empty string means there are no more pages.

has_more

boolean

true when more results are available beyond this page.

Responses

200

200 OK

Request succeeded. See the example response body.

400

Bad Request

The request body, path, or parameters are invalid.

401

Unauthorized

The X-Api-Key header is missing or invalid.

409

Conflict

The requested operation conflicts with an existing provider account or resource.

500

Internal Server Error

The service encountered an unexpected error.

501

Not Implemented

The selected provider does not implement this operation.

502

Bad Gateway

The provider adapter or upstream provider could not complete the operation.

If the request fails

Inspect HTTP status and error.code/numeric_code, and keep request_id for diagnosis. Correct invalid parameters, complete required authorization or check runtime state as appropriate. Confirm the outcome before retrying a send or another write. Error reference

invalid_request · 10000 · 400: Check required fields, formats and channel conditions, then correct the request.
invalid_api_key · 11001 · 401: Check X-Api-Key and whether the workspace is active.