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:

First request: GET /v3/chats?from=%2B12223334444&limit=20
Response includes next_cursor: "20" (more results exist)
Next request: GET /v3/chats?from=%2B12223334444&limit=20&cursor=20
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"

HealthStatus ChatHealthStatus

[BETA] Current health for a chat. Always present — chats start at HEALTHY and may shift based on engagement and delivery signals on the conversation. Many AT_RISK or CRITICAL chats on a single line increase the risk of line flagging.

Switch on status to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a doc_url that deep-links to the relevant section of the Chat Health guide.

See the Chat Health guide for what each status means and how to react.

DocURL string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

Status string

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

const ChatHealthStatusStatusHealthy ChatHealthStatusStatus = "HEALTHY"

const ChatHealthStatusStatusAtRisk ChatHealthStatusStatus = "AT_RISK"

const ChatHealthStatusStatusCritical ChatHealthStatusStatus = "CRITICAL"

const ChatHealthStatusStatusOptedOut ChatHealthStatusStatus = "OPTED_OUT"

UpdatedAt Time

When this status last changed.

formatdate-time

DeprecatedIsArchived bool

is_archived is no longer a useful signal

DEPRECATED: This field is deprecated and will be removed in a future API version.

IsGroup bool

Whether this is a group chat

UpdatedAt Time

When the chat was last updated

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"
        }
      ],
      "health_status": {
        "doc_url": "https://docs.linqapp.com/guides/chats/chat-health#at-risk",
        "status": "AT_RISK",
        "updated_at": "2026-05-01T18:28:25Z"
      },
      "is_archived": true,
      "is_group": true,
      "updated_at": "2024-01-15T10:30:00Z",
      "service": "iMessage"
    }
  ],
  "next_cursor": "next_cursor"
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "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"
        }
      ],
      "health_status": {
        "doc_url": "https://docs.linqapp.com/guides/chats/chat-health#at-risk",
        "status": "AT_RISK",
        "updated_at": "2026-05-01T18:28:25Z"
      },
      "is_archived": true,
      "is_group": true,
      "updated_at": "2024-01-15T10:30:00Z",
      "service": "iMessage"
    }
  ],
  "next_cursor": "next_cursor"
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}