Skip to content
API Docs
Linq
API Reference
Chats
Messages

Send a message to an existing chat

POST/v3/chats/{chatId}/messages

Send a message to an existing chat. Use this endpoint when you already have a chat ID and want to send additional messages to it.

Path ParametersExpand Collapse
chatId: string
formatuuid
Body ParametersJSONExpand Collapse
message: MessageContent { parts, idempotency_key, reply_to }

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

parts: array of TextPart { type, value } or MediaPart { type, attachment_id, url } or LinkPart { type, value }

The message’s one part: text, media, or link. An RCS message carries exactly one part; send text and media as separate messages.

Rich Link Previews:

  • Use a link part to send a URL with a rich preview card
  • A URL inside a text part renders a preview too

Supported Media:

  • Images: .jpg, .jpeg, .png, .gif, .heic, .heif, .tif, .tiff, .bmp
  • Videos: .mp4, .mov, .m4v, .mpeg, .mpg, .3gp
  • Audio: .m4a, .mp3, .aac, .caf, .wav, .aiff, .amr
  • Documents: .pdf, .txt, .rtf, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .pages, .numbers, .key, .epub, .zip, .html, .htm
  • Contact & Calendar: .vcf, .ics

Audio:

  • Audio files (.m4a, .mp3, .aac, .caf, .wav, .aiff, .amr) are fully supported as media parts

Validation Rules:

  • Exactly one part per message.
One of the following:
TextPart object { type, value }
type: "text"

Indicates this is a text message part

value: string

The text content of the message. This value is sent as-is with no parsing or transformation — Markdown syntax will be delivered as plain text.

minLength1
maxLength10000
MediaPart object { type, attachment_id, url }
type: "media"

Indicates this is a media attachment part

attachment_id: optional string

Reference to a file pre-uploaded via POST /v3/attachments (optional). The file is already stored, so sends using this ID skip the download step — useful when sending the same file to many recipients.

Either url or attachment_id must be provided, but not both.

formatuuid
url: optional string

Any publicly accessible HTTPS URL to the media file. The server downloads and sends the file automatically — no pre-upload step required.

Size limit: 10MB maximum for URL-based downloads. For larger files (up to 100MB), use the pre-upload flow: POST /v3/attachments to get a presigned URL, upload directly, then reference by attachment_id.

Requirements:

  • URL must use HTTPS
  • File content must be a supported format (the server validates the actual file content)

Supported formats:

  • Images: .jpg, .jpeg, .png, .gif, .heic, .heif, .tif, .tiff, .bmp
  • Videos: .mp4, .mov, .m4v, .mpeg, .mpg, .3gp
  • Audio: .m4a, .mp3, .aac, .caf, .wav, .aiff, .amr
  • Documents: .pdf, .txt, .rtf, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .pages, .numbers, .key, .epub, .zip, .html, .htm
  • Contact & Calendar: .vcf, .ics

Tip: Audio sent here appears as a regular file attachment. For repeated sends of the same file, use attachment_id to avoid redundant downloads.

Either url or attachment_id must be provided, but not both.

formaturi
idempotency_key: optional string

Optional idempotency key for this message. Use this to prevent duplicate sends of the same message. Reusing a key whose message was deleted returns 404; the message is never resent.

maxLength255
reply_to: optional ReplyTo { message_id, part_index }

Reply to another message to create a threaded conversation

message_id: string

The ID of the message to reply to

formatuuid
part_index: optional number

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
override_optout: optional boolean

Send even though the recipient asked you to stop (403, error code 2024). Applies to this request only: the opt-out stays in place, so the next send without this flag is rejected again. Every override is recorded against your API key.

ReturnsExpand Collapse
chat_id: string

Unique identifier of the chat this message was sent to

formatuuid
message: SentMessage { id, created_at, delivery_status, 7 more }

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

id: string

Message identifier (UUID)

formatuuid
created_at: string

When the message was created

formatdate-time
delivery_status: "pending" or "queued" or "sent" or 4 more

Current delivery status of a message

One of the following:
"pending"
"queued"
"sent"
"delivered"
"received"
"read"
"failed"
Deprecatedis_read: boolean

DEPRECATED: Use delivery_status == "read" instead. Whether the message has been read.

parts: array of TextPartResponse { reactions, type, value } or MediaPartResponse { id, filename, mime_type, 4 more } or LinkPartResponse { reactions, type, value }

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

One of the following:
TextPartResponse object { reactions, type, value }

A text message part

reactions: array of Reaction { handle, is_me, type, 2 more }

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 4 more }
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. Where this names the transport a message used, it is per-message: a chat’s own service can differ from a message in it, and a conversation can fall back from RCS to SMS.

One of the following:
"SMS"
"RCS"
is_me: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time
status: optional "active" or "left" or "removed"

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

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

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
id: optional string

Identifier for this reaction.

formatuuid
custom_emoji: optional string

Custom emoji if type is “custom”, null otherwise

type: "text"

Indicates this is a text message part

value: string

The text content

MediaPartResponse object { id, filename, mime_type, 4 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid
filename: string

Original filename

mime_type: string

MIME type of the file

reactions: array of Reaction { handle, is_me, type, 2 more }

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 4 more }
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. Where this names the transport a message used, it is per-message: a chat’s own service can differ from a message in it, and a conversation can fall back from RCS to SMS.

One of the following:
"SMS"
"RCS"
is_me: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time
status: optional "active" or "left" or "removed"

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

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

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
id: optional string

Identifier for this reaction.

formatuuid
custom_emoji: optional string

Custom emoji if type is “custom”, null otherwise

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

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

formaturi
handle: ChatHandle { id, handle, joined_at, 4 more }
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. Where this names the transport a message used, it is per-message: a chat’s own service can differ from a message in it, and a conversation can fall back from RCS to SMS.

One of the following:
"SMS"
"RCS"
is_me: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time
status: optional "active" or "left" or "removed"

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

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

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
id: optional string

Identifier for this reaction.

formatuuid
custom_emoji: optional string

Custom emoji if type is “custom”, null otherwise

sent_at: string

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

formatdate-time
delivered_at: optional string

When the message was delivered

formatdate-time
from_handle: optional ChatHandle { id, handle, joined_at, 4 more }

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

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. Where this names the transport a message used, it is per-message: a chat’s own service can differ from a message in it, and a conversation can fall back from RCS to SMS.

One of the following:
"SMS"
"RCS"
is_me: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time
status: optional "active" or "left" or "removed"

Participant status

One of the following:
"active"
"left"
"removed"
reply_to: optional ReplyTo { message_id, part_index }

Indicates this message is a threaded reply to another message

message_id: string

The ID of the message to reply to

formatuuid
part_index: optional number

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: optional ServiceType

Messaging service type. Where this names the transport a message used, it is per-message: a chat’s own service can differ from a message in it, and a conversation can fall back from RCS to SMS.

One of the following:
"SMS"
"RCS"

Send a message to an existing chat

curl https://api.linqapp.com/api/partner/v3/chats/$CHAT_ID/messages \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LINQ_API_V3_API_KEY" \
    -d '{
          "message": {
            "parts": [
              {
                "type": "text",
                "value": "Hello, world!"
              }
            ]
          }
        }'
{
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "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": "RCS",
              "is_me": false,
              "left_at": "2019-12-27T18:11:19.117Z",
              "status": "active"
            },
            "is_me": false,
            "type": "love",
            "id": "9f8b1c2d-3e4f-5061-7283-94a5b6c7d8e9",
            "custom_emoji": null
          }
        ],
        "type": "text",
        "value": "Hello!"
      }
    ],
    "sent_at": null,
    "delivered_at": null,
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "handle": "+15551234567",
      "joined_at": "2025-05-21T15:30:00.000-05:00",
      "service": "RCS",
      "is_me": false,
      "left_at": "2019-12-27T18:11:19.117Z",
      "status": "active"
    },
    "reply_to": {
      "message_id": "550e8400-e29b-41d4-a716-446655440000",
      "part_index": 0
    },
    "service": "RCS"
  }
}
{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/1xxx/1002/"
  },
  "success": false
}
{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2004/"
  },
  "success": false
}
{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2005/"
  },
  "success": false
}
{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2001/"
  },
  "success": false
}
{
  "error": {
    "status": 409,
    "code": 2013,
    "message": "cannot interact with a chat you have left",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2013/"
  },
  "success": false
}
{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/3xxx/3006/"
  },
  "success": false
}
Returns Examples
{
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "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": "RCS",
              "is_me": false,
              "left_at": "2019-12-27T18:11:19.117Z",
              "status": "active"
            },
            "is_me": false,
            "type": "love",
            "id": "9f8b1c2d-3e4f-5061-7283-94a5b6c7d8e9",
            "custom_emoji": null
          }
        ],
        "type": "text",
        "value": "Hello!"
      }
    ],
    "sent_at": null,
    "delivered_at": null,
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "handle": "+15551234567",
      "joined_at": "2025-05-21T15:30:00.000-05:00",
      "service": "RCS",
      "is_me": false,
      "left_at": "2019-12-27T18:11:19.117Z",
      "status": "active"
    },
    "reply_to": {
      "message_id": "550e8400-e29b-41d4-a716-446655440000",
      "part_index": 0
    },
    "service": "RCS"
  }
}
{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/1xxx/1002/"
  },
  "success": false
}
{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2004/"
  },
  "success": false
}
{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2005/"
  },
  "success": false
}
{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2001/"
  },
  "success": false
}
{
  "error": {
    "status": 409,
    "code": 2013,
    "message": "cannot interact with a chat you have left",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2013/"
  },
  "success": false
}
{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/3xxx/3006/"
  },
  "success": false
}
© 2026 Linq, Inc. · linqapp.com