Skip to main content

​
Overview

The SendMessage request allows you to send messages to any chat type (users, groups, channels, or saved messages). Messages can include text content, media attachments, reply references, and formatting entities.

​
Proto Definition

// messages.sendMessage -> messages.SentMessage
message SendMessage {
  refs.ChatRef chat_ref = 1;
  string message = 2;
  optional fixed64 reply_to = 3;  // @snowflake<Message>
  repeated media.MediaRef media = 4;
  repeated types.MessageEntity entities = 5;
}

message SentMessage {
  fixed64 message_id = 1;  // @snowflake<Message>
}

​
Request Fields

​
chat_ref
ChatRef
required
The target chat where the message will be sent. Can be a user (DM), channel, group, or self (saved messages). See ChatRef types for details.
​
message
string
required
The text content of the message. Can be empty if media is attached. Supports formatting through entities.
​
reply_to
fixed64
The message ID to reply to. Creates a reply reference in the UI. Must be a valid message ID in the same chat.Type: Snowflake ID representing a Message
​
media
MediaRef[]
Array of media attachments to include with the message. Can contain uploaded files or embed URLs.Each MediaRef can be:
  • uploaded - A file that was uploaded using the media upload API
  • embed - An embed URL that will be previewed
​
entities
MessageEntity[]
Formatting entities that apply styles to portions of the message text. Includes bold, italic, mentions, links, code blocks, and more.See Message Entities for the complete list of supported entities.

​
Response

​
message_id
fixed64
required
The snowflake ID of the newly created message. Use this ID for editing, deleting, or replying to the message.

​
Examples

​
Send a Simple Text Message

{
  "chat_ref": {
    "user": {
      "user_id": "123456789012345678"
    }
  },
  "message": "Hello, world!"
}

​
Send a Message with Reply

{
  "chat_ref": {
    "channel": {
      "community_id": "987654321098765432",
      "channel_id": "111111111111111111"
    }
  },
  "message": "Great point!",
  "reply_to": "555555555555555555"
}

​
Send a Formatted Message

{
  "chat_ref": {
    "group": {
      "group_id": "222222222222222222"
    }
  },
  "message": "Check out this code:",
  "entities": [
    {
      "start_index": 0,
      "length": 9,
      "bold": true
    }
  ]
}

​
Send a Message with Media

{
  "chat_ref": {
    "user": {
      "user_id": "123456789012345678"
    }
  },
  "message": "Check out this image!",
  "media": [
    {
      "uploaded": {
        "file": {
          "id": "12345",
          "name": "image.png",
          "part_count": 1
        },
        "filename": "screenshot.png",
        "mimetype": "image/png",
        "metadata": {
          "image": {
            "width": 1920,
            "height": 1080
          }
        }
      }
    }
  ]
}

​
Send to Saved Messages

{
  "chat_ref": {
    "self": {}
  },
  "message": "Note to self: Remember this!"
}

​
Media Attachments

When including media, you can attach either uploaded files or embeds:

​
Uploaded File

message MediaRefUploadedFile {
  UploadedFileRef file = 1;
  optional string filename = 2;
  string mimetype = 3;
  FileMetadata metadata = 4;
}
Files must be uploaded using the media upload API before being referenced in a message.

​
Embed URL

message MediaRefEmbed {
  string url = 1;
}
Provide a URL that will be automatically previewed (e.g., YouTube videos, images, etc.).

​
Notes

  • The message field can be empty if you’re sending media-only messages
  • Entity indices are 0-based and measured in Unicode code points
  • Multiple entities can overlap (e.g., bold + italic)
  • The server assigns the message ID and returns it in the response
  • Messages are delivered in real-time to all participants in the chat

Build docs developers (and LLMs) love

Get started for freeTalk to us