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. Decorations render per recipient, not per message: in a group with both iMessage and SMS/RCS participants, iMessage recipients see the decorations and SMS/RCS recipients receive the same message as plain text.

Inline Stickers (iMessage only)

Use the inline_stickers array on a text part to place stickers inside the text. Each sticker replaces the characters in its range: [start, end) and takes its image from exactly one of url or attachment_id — an image uploaded with POST /v3/attachments.

{
  "type": "text",
  "value": "Happy birthday 🎂! 🎉🎉",
  "inline_stickers": [
    { "range": [15, 17], "attachment_id": "550e8400-e29b-41d4-a716-446655440000" },
    { "range": [19, 21], "attachment_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" },
    { "range": [21, 23], "attachment_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }
  ]
}

Note: A sticker takes the place of the characters it covers, so they are hidden on iMessage: "Sip cup" with a sticker on cup reads "Sip [sticker]". Those characters are what SMS and RCS recipients receive (the stickers are dropped and value is sent as written) and what VoiceOver reads. To keep a word visible, give the sticker its own placeholder: "Sip cup 🥤" with the range on 🥤. Up to 100 stickers and 10 different images per part; copies of one image count as one.

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.

Reusing an Existing Chat

Chats are keyed on the from line plus the exact set of to handles. Repeating this request with the same from and to returns the existing chat and sends the message into it instead of starting a second conversation.

A group chat that has a display_name is excluded from that matching. To run several parallel groups over the same participants, name each one with PUT /v3/chats/{chatId} before creating the next: the following POST /v3/chats with the same to then returns a new, separate chat_id. Two other cases also produce a new chat instead of reusing one — the participant set changed (a participant was added or removed), or the from line left the group.

Whenever the response is a new chat, the first-message rules above apply to that request: no link in the first message, and no reply_to or message effect. To send into a chat you already know, use POST /v3/chats/{chatId}/messages with its chat_id.

{
  "from": "+12052535597",
  "to": [
    "+14155559876",
    "+14155550123"
  ],
  "message": {
    "experience": {
      "name": "agentcard",
      "action": "attach_card"
    },
    "parts": [
      {
        "type": "text",
        "value": "Check this out!"
      },
      {
        "type": "media",
        "url": "https://cdn.linqapp.com/attachments/example/photo.jpg"
      }
    ],
    "effect": {
      "type": "screen",
      "name": "confetti"
    },
    "reply_to": {
      "message_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "idempotency_key": "msg-abc123xyz",
    "preferred_service": "iMessage"
  }
}

{
  "chat": {
    "id": "94c6bf33-31d9-40e3-a0e9-f94250ecedb9",
    "display_name": "+14155551234, +14155559876",
    "service": "iMessage",
    "handles": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "handle": "+14155551234",
        "service": "iMessage",
        "status": "active",
        "joined_at": "2025-05-21T15:30:00.000Z",
        "is_me": true
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440011",
        "handle": "+14155559876",
        "service": "iMessage",
        "status": "active",
        "joined_at": "2025-05-21T15:30:00.000Z",
        "is_me": false
      }
    ],
    "message": {
      "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
      "service": "iMessage",
      "preferred_service": "iMessage",
      "parts": [
        {
          "type": "text",
          "value": "Hello!"
        }
      ],
      "created_at": "2025-10-23T13:07:55.019-05:00",
      "delivery_status": "pending",
      "effect": {
        "type": "screen",
        "name": "confetti"
      },
      "from_handle": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "handle": "+15551234567",
        "service": "iMessage",
        "joined_at": "2025-05-21T15:30:00.000-05:00",
        "line_type": "iMessage"
      },
      "reply_to": {
        "message_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    },
    "health_status": {
      "status": "AT_RISK",
      "doc_url": "https://docs.linqapp.com/channel/imessage/guides/chats/chat-health#at-risk",
      "updated_at": "2026-05-01T18:28:25Z"
    }
  }
}