Create a new chat

client.Chats.New(ctx, body) (*ChatNewResponse, error)

POST/v3/chats

Create a new chat with specified participants and send an initial message. The initial message is required when creating a chat.

Message Effects

You can add iMessage effects to make your messages more expressive. Effects are optional and can be either screen effects (full-screen animations) or bubble effects (message bubble animations).

Screen Effects: confetti, fireworks, lasers, sparkles, celebration, hearts, love, balloons, happy_birthday, echo, spotlight

Bubble Effects: slam, loud, gentle, invisible

Only one effect type can be applied per message.

Inline Text Decorations (iMessage only)

Use the text_decorations array on a text part to apply styling and animations to character ranges.

Each decoration specifies a range: [start, end) and exactly one of style or animation.

Styles: bold, italic, strikethrough, underline Animations: big, small, shake, nod, explode, ripple, bloom, jitter

{
  "type": "text",
  "value": "Hello world",
  "text_decorations": [
    { "range": [0, 5], "style": "bold" },
    { "range": [6, 11], "animation": "shake" }
  ]
}

Note: Style ranges (bold, italic, etc.) may overlap, but animation ranges must not overlap with other animations or styles. Text decorations only render for iMessage recipients. For SMS/RCS, text decorations are not applied.

First-Message Link Restriction

To protect sender deliverability, the first outbound message of a new chat cannot be a link. The request is rejected with 400 (error code 1005) when:

The message contains a link part (explicit rich-preview link), or
Any text part contains a URL.

This rule applies only to POST /v3/chats. Follow-up messages on an existing chat (POST /v3/chats/{chatId}/messages) are not subject to this restriction.

ParametersExpand Collapse

body ChatNewParams

From param.Field[string]

Sender phone number in E.164 format. Must be a phone number that the authenticated partner has permission to send from.

Message param.Field[MessageContent]

Message content container. Groups all message-related fields together, separating the “what” (message content) from the “where” (routing fields like from/to).

To param.Field[[]string]

Array of recipient handles (phone numbers in E.164 format or email addresses). For individual chats, provide one recipient. For group chats, provide multiple.

ReturnsExpand Collapse

type ChatNewResponse struct{…}

Response for creating a new chat with an initial message

Chat ChatNewResponseChat

ID string

Unique identifier for the created chat (UUID)

formatuuid

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 participants in the chat. 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"

IsGroup bool

Whether this is a group chat

Message SentMessage

A message that was sent (used in CreateChat and SendMessage responses)

ID string

Message identifier (UUID)

formatuuid

CreatedAt Time

When the message was created

formatdate-time

DeliveryStatus SentMessageDeliveryStatus

Current delivery status of a message

One of the following:

const SentMessageDeliveryStatusPending SentMessageDeliveryStatus = "pending"

const SentMessageDeliveryStatusQueued SentMessageDeliveryStatus = "queued"

const SentMessageDeliveryStatusSent SentMessageDeliveryStatus = "sent"

const SentMessageDeliveryStatusDelivered SentMessageDeliveryStatus = "delivered"

const SentMessageDeliveryStatusFailed SentMessageDeliveryStatus = "failed"

IsRead bool

Whether the message has been read

Parts []SentMessagePartUnion

Message parts in order (text, media, and link)

One of the following:

type TextPartResponse struct{…}

A text message part

Reactions []Reaction

Reactions on this message part

Handle ChatHandle

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"

IsMe bool

Whether this reaction is from the current user

Type ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:

const ReactionTypeLove ReactionType = "love"

const ReactionTypeLike ReactionType = "like"

const ReactionTypeDislike ReactionType = "dislike"

const ReactionTypeLaugh ReactionType = "laugh"

const ReactionTypeEmphasize ReactionType = "emphasize"

const ReactionTypeQuestion ReactionType = "question"

const ReactionTypeCustom ReactionType = "custom"

const ReactionTypeSticker ReactionType = "sticker"

CustomEmoji stringOptional

Custom emoji if type is “custom”, null otherwise

Sticker ReactionStickerOptional

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

FileName stringOptional

Filename of the sticker

Height int64Optional

Sticker image height in pixels

MimeType stringOptional

MIME type of the sticker image

URL stringOptional

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

Width int64Optional

Sticker image width in pixels

Type TextPartResponseType

Indicates this is a text message part

Value string

The text content

TextDecorations []TextDecorationOptional

Text decorations applied to character ranges in the value

Range []int64

Character range [start, end) in the value string where the decoration applies. start is inclusive, end is exclusive. Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.

Animation TextDecorationAnimationOptional

Animated text effect to apply. Mutually exclusive with style.

One of the following:

const TextDecorationAnimationBig TextDecorationAnimation = "big"

const TextDecorationAnimationSmall TextDecorationAnimation = "small"

const TextDecorationAnimationShake TextDecorationAnimation = "shake"

const TextDecorationAnimationNod TextDecorationAnimation = "nod"

const TextDecorationAnimationExplode TextDecorationAnimation = "explode"

const TextDecorationAnimationRipple TextDecorationAnimation = "ripple"

const TextDecorationAnimationBloom TextDecorationAnimation = "bloom"

const TextDecorationAnimationJitter TextDecorationAnimation = "jitter"

Style TextDecorationStyleOptional

Text style to apply. Mutually exclusive with animation.

One of the following:

const TextDecorationStyleBold TextDecorationStyle = "bold"

const TextDecorationStyleItalic TextDecorationStyle = "italic"

const TextDecorationStyleStrikethrough TextDecorationStyle = "strikethrough"

const TextDecorationStyleUnderline TextDecorationStyle = "underline"

type MediaPartResponse struct{…}

A media attachment part

ID string

Unique attachment identifier

formatuuid

Filename string

Original filename

MimeType string

MIME type of the file

Reactions []Reaction

Reactions on this message part

Handle ChatHandle

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"

IsMe bool

Whether this reaction is from the current user

Type ReactionType

One of the following:

const ReactionTypeLove ReactionType = "love"

const ReactionTypeLike ReactionType = "like"

const ReactionTypeDislike ReactionType = "dislike"

const ReactionTypeLaugh ReactionType = "laugh"

const ReactionTypeEmphasize ReactionType = "emphasize"

const ReactionTypeQuestion ReactionType = "question"

const ReactionTypeCustom ReactionType = "custom"

const ReactionTypeSticker ReactionType = "sticker"

CustomEmoji stringOptional

Custom emoji if type is “custom”, null otherwise

Sticker ReactionStickerOptional

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

FileName stringOptional

Filename of the sticker

Height int64Optional

Sticker image height in pixels

MimeType stringOptional

MIME type of the sticker image

URL stringOptional

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

Width int64Optional

Sticker image width in pixels

SizeBytes int64

File size in bytes

Type MediaPartResponseType

Indicates this is a media attachment part

URL string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

type LinkPartResponse struct{…}

A rich link preview part

Reactions []Reaction

Reactions on this message part

Handle ChatHandle

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"

IsMe bool

Whether this reaction is from the current user

Type ReactionType

One of the following:

const ReactionTypeLove ReactionType = "love"

const ReactionTypeLike ReactionType = "like"

const ReactionTypeDislike ReactionType = "dislike"

const ReactionTypeLaugh ReactionType = "laugh"

const ReactionTypeEmphasize ReactionType = "emphasize"

const ReactionTypeQuestion ReactionType = "question"

const ReactionTypeCustom ReactionType = "custom"

const ReactionTypeSticker ReactionType = "sticker"

CustomEmoji stringOptional

Custom emoji if type is “custom”, null otherwise

Sticker ReactionStickerOptional

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

FileName stringOptional

Filename of the sticker

Height int64Optional

Sticker image height in pixels

MimeType stringOptional

MIME type of the sticker image

URL stringOptional

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

Width int64Optional

Sticker image width in pixels

Type LinkPartResponseType

Indicates this is a rich link preview part

Value string

The URL

SentAt Time

When the message was actually sent (null if still queued)

formatdate-time

DeliveredAt TimeOptional

When the message was delivered

formatdate-time

Effect MessageEffectOptional

iMessage effect applied to a message (screen or bubble effect)

Name stringOptional

Name of the effect. Common values:

Screen effects: confetti, fireworks, lasers, sparkles, celebration, hearts, love, balloons, happy_birthday, echo, spotlight
Bubble effects: slam, loud, gentle, invisible

Type MessageEffectTypeOptional

Type of effect

One of the following:

const MessageEffectTypeScreen MessageEffectType = "screen"

const MessageEffectTypeBubble MessageEffectType = "bubble"

FromHandle ChatHandleOptional

The sender of this message as a full handle object

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"

PreferredService ServiceTypeOptional

Messaging service type

One of the following:

const ServiceTypeiMessage ServiceType = "iMessage"

const ServiceTypeSMS ServiceType = "SMS"

const ServiceTypeRCS ServiceType = "RCS"

ReplyTo ReplyToOptional

Indicates this message is a threaded reply to another message

MessageID string

The ID of the message to reply to

formatuuid

PartIndex int64Optional

The specific message part to reply to (0-based index). Defaults to 0 (first part) if not provided. Use this when replying to a specific part of a multipart message.

formatint32

minimum0

Service ServiceTypeOptional

Messaging service type

One of the following:

const ServiceTypeiMessage ServiceType = "iMessage"

const ServiceTypeSMS ServiceType = "SMS"

const ServiceTypeRCS ServiceType = "RCS"

Service ServiceType

Messaging service type

One of the following:

const ServiceTypeiMessage ServiceType = "iMessage"

const ServiceTypeSMS ServiceType = "SMS"

const ServiceTypeRCS ServiceType = "RCS"

HealthScore ChatNewResponseChatHealthScoreOptional

[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

Create a new chat

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"),
  )
  chat, err := client.Chats.New(context.TODO(), linqgo.ChatNewParams{
    From: "+12052535597",
    Message: linqgo.MessageContentParam{
      Parts: []linqgo.MessageContentPartUnionParam{linqgo.MessageContentPartUnionParam{
        OfText: &linqgo.TextPartParam{
          Type: linqgo.TextPartTypeText,
          Value: "Hello! How can I help you today?",
        },
      }},
    },
    To: []string{"+12052532136"},
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", chat.Chat)
}

{
  "chat": {
    "id": "94c6bf33-31d9-40e3-a0e9-f94250ecedb9",
    "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_group": false,
    "message": {
      "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
      "created_at": "2025-10-23T13:07:55.019-05:00",
      "delivery_status": "pending",
      "is_read": false,
      "parts": [
        {
          "reactions": [
            {
              "handle": {
                "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
                "handle": "+15551234567",
                "joined_at": "2025-05-21T15:30:00.000-05:00",
                "service": "iMessage",
                "is_me": false,
                "left_at": "2019-12-27T18:11:19.117Z",
                "status": "active"
              },
              "is_me": false,
              "type": "love",
              "custom_emoji": null,
              "sticker": {
                "file_name": "sticker.png",
                "height": 420,
                "mime_type": "image/png",
                "url": "https://cdn.linqapp.com/attachments/a1b2c3d4/sticker.png?signature=...",
                "width": 420
              }
            }
          ],
          "type": "text",
          "value": "Hello!",
          "text_decorations": [
            {
              "range": [
                0,
                5
              ],
              "animation": "shake",
              "style": "bold"
            }
          ]
        }
      ],
      "sent_at": null,
      "delivered_at": null,
      "effect": {
        "name": "confetti",
        "type": "screen"
      },
      "from_handle": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "handle": "+15551234567",
        "joined_at": "2025-05-21T15:30:00.000-05:00",
        "service": "iMessage",
        "is_me": false,
        "left_at": "2019-12-27T18:11:19.117Z",
        "status": "active"
      },
      "preferred_service": "iMessage",
      "reply_to": {
        "message_id": "550e8400-e29b-41d4-a716-446655440000",
        "part_index": 0
      },
      "service": "iMessage"
    },
    "service": "iMessage",
    "health_score": {
      "reason": "Not enough engagement",
      "score": 35,
      "updated_at": "2026-05-01T18:28:25Z"
    }
  }
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format"
  },
  "success": false
}

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

{
  "chat": {
    "id": "94c6bf33-31d9-40e3-a0e9-f94250ecedb9",
    "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_group": false,
    "message": {
      "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
      "created_at": "2025-10-23T13:07:55.019-05:00",
      "delivery_status": "pending",
      "is_read": false,
      "parts": [
        {
          "reactions": [
            {
              "handle": {
                "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
                "handle": "+15551234567",
                "joined_at": "2025-05-21T15:30:00.000-05:00",
                "service": "iMessage",
                "is_me": false,
                "left_at": "2019-12-27T18:11:19.117Z",
                "status": "active"
              },
              "is_me": false,
              "type": "love",
              "custom_emoji": null,
              "sticker": {
                "file_name": "sticker.png",
                "height": 420,
                "mime_type": "image/png",
                "url": "https://cdn.linqapp.com/attachments/a1b2c3d4/sticker.png?signature=...",
                "width": 420
              }
            }
          ],
          "type": "text",
          "value": "Hello!",
          "text_decorations": [
            {
              "range": [
                0,
                5
              ],
              "animation": "shake",
              "style": "bold"
            }
          ]
        }
      ],
      "sent_at": null,
      "delivered_at": null,
      "effect": {
        "name": "confetti",
        "type": "screen"
      },
      "from_handle": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "handle": "+15551234567",
        "joined_at": "2025-05-21T15:30:00.000-05:00",
        "service": "iMessage",
        "is_me": false,
        "left_at": "2019-12-27T18:11:19.117Z",
        "status": "active"
      },
      "preferred_service": "iMessage",
      "reply_to": {
        "message_id": "550e8400-e29b-41d4-a716-446655440000",
        "part_index": 0
      },
      "service": "iMessage"
    },
    "service": "iMessage",
    "health_score": {
      "reason": "Not enough engagement",
      "score": 35,
      "updated_at": "2026-05-01T18:28:25Z"
    }
  }
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format"
  },
  "success": false
}

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