Skip to content
API Docs
LinqCopy agent prompt
API Reference
Chats

Get a chat by ID

client.chats.retrieve(stringchatID, RequestOptionsoptions?): Chat { id, created_at, display_name, 7 more }
GET/v3/chats/{chatId}

Retrieve a chat by its unique identifier.

ParametersExpand Collapse
chatID: string
formatuuid
ReturnsExpand Collapse
Chat { id, created_at, display_name, 7 more }
id: string

Unique identifier for the chat

formatuuid
created_at: string

When the chat was created

formatdate-time
display_name: string | null

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

handles: Array<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?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
health_status: HealthStatus { doc_url, status, updated_at }

[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 surface chat and 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. To gate a send, act on the response rather than the status: a 403 is the authoritative answer.

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

doc_url: string

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

formaturi
status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

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.

OPTED_OUT — the recipient sent STOP, UNSUBSCRIBE, OPTOUT, CANCEL, END, or QUIT. The keyword must be the whole trimmed message, never part of a longer one: STOP counts, please stop does not. Most keywords must match exactly, including case. OPT OUT is the exception — it matches in any casing, with or without the space or a hyphen, so opt out, Opt-Out and optout all count. It clears as soon as they reply again: any later message from them that is not itself an opt-out keyword opts them back in immediately — a reply in any conversation with you counts, the same way the block does.

OPTED_OUT marks only the conversation the keyword arrived in. The block below is wider than the mark, so a conversation still reading HEALTHY can be blocked as well — gate on the 403, not on the status. Group threads are never marked and are never blocked.

Linq enforces this: while a recipient is opted out, every send to them is rejected with 403 (error code 2024) before the message is queued, across every chat and every line on your account. Nothing is delivered, including a final courtesy message — to send one, set override_optout: true on that single request.

One of the following:
"HEALTHY"
"AT_RISK"
"CRITICAL"
"OPTED_OUT"
updated_at: string

When this status last changed.

formatdate-time
Deprecatedis_archived: boolean
is_archived is no longer a useful signal

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

is_group: boolean

Whether this is a group chat

updated_at: string

When the chat was last updated

formatdate-time
group_chat_icon?: string | null

URL of the group chat icon. Only set for group chats that have an icon; null otherwise.

formaturi
service?: ServiceType | null

Messaging service type

One of the following:
"iMessage"
"SMS"
"RCS"

Get a chat by ID

import LinqAPIV3 from '@linqapp/sdk';

const client = new LinqAPIV3({
  apiKey: process.env['LINQ_API_V3_API_KEY'], // This is the default and can be omitted
});

const chat = await client.chats.retrieve('550e8400-e29b-41d4-a716-446655440000');

console.log(chat.id);
{
  "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",
  "group_chat_icon": "https://example.com/group-icon.png",
  "service": "iMessage"
}
{
  "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": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2001/"
  },
  "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
{
  "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",
  "group_chat_icon": "https://example.com/group-icon.png",
  "service": "iMessage"
}
{
  "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": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2001/"
  },
  "success": false
}
{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}
© 2026 Linq, Inc. · linqapp.com