Skip to content
API Docs
V2 (Legacy) API ReferenceGet started
API Reference
Chats

List all chats

GET/v3/chats

Retrieves a paginated list of chats for the authenticated partner.

Filtering:

  • If from is provided, returns chats for that specific phone number
  • If from is omitted, returns chats across all phone numbers owned by the partner
  • If to is provided, only returns chats where the specified handle is a participant

Pagination:

  • Use limit to control page size (default: 20, max: 100)
  • The response includes next_cursor for fetching the next page
  • When next_cursor is null, there are no more results to fetch
  • Pass the next_cursor value as the cursor parameter for the next request

Example pagination flow:

  1. First request: GET /v3/chats?from=%2B12223334444&limit=20
  2. Response includes next_cursor: "20" (more results exist)
  3. Next request: GET /v3/chats?from=%2B12223334444&limit=20&cursor=20
  4. Response includes next_cursor: null (no more results)
Query ParametersExpand Collapse
cursor: optional string

Pagination cursor from the previous response’s next_cursor field. Omit this parameter for the first page of results.

from: optional string

Phone number to filter chats by. Returns chats made from this phone number. Must be in E.164 format (e.g., +13343284472). The + is automatically URL-encoded by HTTP clients. If omitted, returns chats across all phone numbers owned by the partner.

limit: optional number

Maximum number of chats to return per page

minimum1
maximum100
to: optional string

Filter chats by a participant handle. Only returns chats where this handle is a participant. Can be an E.164 phone number (e.g., +13343284472) or an email address (e.g., [email protected]). For phone numbers, the + is automatically URL-encoded by HTTP clients.

ReturnsExpand Collapse
chats: array of Chat { id, created_at, display_name, 6 more }

List of chats

id: string

Unique identifier for the chat

formatuuid
created_at: string

When the chat was created

formatdate-time
display_name: string

Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats.

handles: array of ChatHandle { id, handle, joined_at, 4 more }

List of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant).

id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type

One of the following:
"iMessage"
"SMS"
"RCS"
is_me: optional boolean

Whether this handle belongs to the sender (your phone number)

left_at: optional string

When they left (if applicable)

formatdate-time
status: optional "active" or "left" or "removed"

Participant status

One of the following:
"active"
"left"
"removed"
is_archived: boolean

Whether the chat is archived

is_group: boolean

Whether this is a group chat

updated_at: string

When the chat was last updated

formatdate-time
health_score: optional object { reason, score, updated_at }

[BETA] Health assessment for a chat. Higher score is healthier. null when a score isn’t available yet. Scoring may change during beta.

reason: string

Short summary of what’s affecting the score. Empty when the score is 100.

score: number

Health score from 0 to 100. Higher is healthier.

minimum0
maximum100
updated_at: string

When this health score was last computed.

formatdate-time
service: optional ServiceType

Messaging service type

One of the following:
"iMessage"
"SMS"
"RCS"
next_cursor: optional string

Cursor for fetching the next page of results. Null if there are no more results to fetch. Pass this value as the cursor parameter in the next request.

List all chats

curl https://api.linqapp.com/api/partner/v3/chats \
    -H "Authorization: Bearer $LINQ_API_V3_API_KEY"
{
  "chats": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2024-01-15T10:30:00Z",
      "display_name": "+14155551234, +14155559876",
      "handles": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440010",
          "handle": "+14155551234",
          "joined_at": "2025-05-21T15:30:00.000Z",
          "service": "iMessage",
          "is_me": true,
          "left_at": "2019-12-27T18:11:19.117Z",
          "status": "active"
        },
        {
          "id": "550e8400-e29b-41d4-a716-446655440011",
          "handle": "+14155559876",
          "joined_at": "2025-05-21T15:30:00.000Z",
          "service": "iMessage",
          "is_me": false,
          "left_at": "2019-12-27T18:11:19.117Z",
          "status": "active"
        }
      ],
      "is_archived": true,
      "is_group": true,
      "updated_at": "2024-01-15T10:30:00Z",
      "health_score": {
        "reason": "Not enough engagement",
        "score": 35,
        "updated_at": "2026-05-01T18:28:25Z"
      },
      "service": "iMessage"
    }
  ],
  "next_cursor": "next_cursor"
}
{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token"
  },
  "success": false
}
{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error"
  },
  "success": false
}
Returns Examples
{
  "chats": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2024-01-15T10:30:00Z",
      "display_name": "+14155551234, +14155559876",
      "handles": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440010",
          "handle": "+14155551234",
          "joined_at": "2025-05-21T15:30:00.000Z",
          "service": "iMessage",
          "is_me": true,
          "left_at": "2019-12-27T18:11:19.117Z",
          "status": "active"
        },
        {
          "id": "550e8400-e29b-41d4-a716-446655440011",
          "handle": "+14155559876",
          "joined_at": "2025-05-21T15:30:00.000Z",
          "service": "iMessage",
          "is_me": false,
          "left_at": "2019-12-27T18:11:19.117Z",
          "status": "active"
        }
      ],
      "is_archived": true,
      "is_group": true,
      "updated_at": "2024-01-15T10:30:00Z",
      "health_score": {
        "reason": "Not enough engagement",
        "score": 35,
        "updated_at": "2026-05-01T18:28:25Z"
      },
      "service": "iMessage"
    }
  ],
  "next_cursor": "next_cursor"
}
{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token"
  },
  "success": false
}
{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error"
  },
  "success": false
}
© 2026 Linq, Inc. · linqapp.com