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

List all chats

client.Chats.ListChats(ctx, query) (*ListChatsPagination[Chat], error)
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)
ParametersExpand Collapse
query ChatListChatsParams
Cursor param.Field[string]Optional

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

From param.Field[string]Optional

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 param.Field[int64]Optional

Maximum number of chats to return per page

minimum1
maximum100
To param.Field[string]Optional

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
type Chat struct{…}
ID string

Unique identifier for the chat

formatuuid
CreatedAt Time

When the chat was created

formatdate-time
DisplayName string

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

Handles []ChatHandle

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

JoinedAt Time

When this participant joined the chat

formatdate-time
Service ServiceType

Messaging service type

One of the following:
const ServiceTypeiMessage ServiceType = "iMessage"
const ServiceTypeSMS ServiceType = "SMS"
const ServiceTypeRCS ServiceType = "RCS"
IsMe boolOptional

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

LeftAt TimeOptional

When they left (if applicable)

formatdate-time
Status ChatHandleStatusOptional

Participant status

One of the following:
const ChatHandleStatusActive ChatHandleStatus = "active"
const ChatHandleStatusLeft ChatHandleStatus = "left"
const ChatHandleStatusRemoved ChatHandleStatus = "removed"
IsArchived bool

Whether the chat is archived

IsGroup bool

Whether this is a group chat

UpdatedAt Time

When the chat was last updated

formatdate-time
HealthScore ChatHealthScoreOptional

[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 int64

Health score from 0 to 100. Higher is healthier.

minimum0
maximum100
UpdatedAt Time

When this health score was last computed.

formatdate-time
Service ServiceTypeOptional

Messaging service type

One of the following:
const ServiceTypeiMessage ServiceType = "iMessage"
const ServiceTypeSMS ServiceType = "SMS"
const ServiceTypeRCS ServiceType = "RCS"

List all chats

package main

import (
  "context"
  "fmt"

  "github.com/linq-team/linq-go"
  "github.com/linq-team/linq-go/option"
)

func main() {
  client := linqgo.NewClient(
    option.WithAPIKey("My API Key"),
  )
  page, err := client.Chats.ListChats(context.TODO(), linqgo.ChatListChatsParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

{
  "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