Send messages to channels or users on your workspace.
Note: You can only send the alias and avatar properties if your user has the message-impersonate (Impersonate other users) permission. By default, only the bot and app roles have this permission.
The server removes markdown trees (md and descriptionMd) from attachments before it saves the message. It does not generate a new md for the attachment.
The request body accepts only the top-level properties listed here. Any other property, such as blocks or a message field that only the server sets (for example pinned, u, or ts), fails. To send blocks, use chat.sendMessage.
Change Log
| Version | Description |
|---|---|
| 9.0.0 | Stripped md and descriptionMd from attachments before saving the message. |
| 6.8.0 | Added custom fields to messages. |
| 6.2.0 | Rejected request body properties that are not listed. |
| 2.4.0 | Added validation on user's identity |
| 0.49.0 | The channel can now be a room's id. |
| 0.48.0 | Information about the sent message is now returned. |
| 0.17.0 | Messages aren't always processed as from BOT and urls are parsed by default. |
| 0.14.0 | Internally using processWebhookMessage which enabled more features. |
| 0.13.0 | Added |
The authToken of the authenticated user.
The userId of the authenticated user.
{
"channel": "#general",
"emoji": ":smirk:",
"text": "Sample message",
"attachments": [
{
"audio_url": "http://www.w3schools.com/tags/horse.mp3",
"author_icon": "https://avatars.githubusercontent.com/u/850391?v=3",
"author_link": "https://rocket.chat/",
"author_name": "Bradley Hilton",
"collapsed": false,
"color": "#ff0000",
"fields": [
{
"short": true,
"title": "Test",
"value": "Testing out something or other"
},
{
"short": true,
"title": "Another Test",
"value": "[Link](https://google.com/) something and this and that."
}
],
"image_url": "http://res.guggy.com/logo_128.png",
"message_link": "https://google.com",
"text": "Yay for gruggy!",
"thumb_url": "http://res.guggy.com/logo_128.png",
"title": "Attachment Example",
"title_link": "https://youtube.com",
"title_link_download": true,
"ts": "2016-12-09T16:53:06.761Z",
"video_url": "http://www.w3schools.com/tags/movie.mp4"
}
]
}The name to display on the message instead of your name. Your username is still displayed.
The URL of an image to display as the message avatar.
An emoji to display as the message avatar.
The room ID or an array of room IDs where the message is to be sent. You can also use a room name, with or without the # prefix, or a username with the @ prefix. Cannot be combined with channel. With an array, the message is posted to each room, and the response describes only the first one.
The message text to send.
Set to false to stop the server from extracting URLs from text. The message is saved with no urls and no link preview. When the message has attachments, the default is false, and no link preview is generated even with true.
Displays a tiny icon to the left of the author's name.
Providing this makes the author's name clickable and points to the provided link.
Name of the author.
Causes the image, audio, and video sections to be displayed as collapsed when set to true.
Whether this field should be a short field.
The title of this field.
The value of this field, displayed underneath the title value.
The URL of the image to display in the attachment.
Only applicable if the ts field is provided, as it makes the time clickable to this link.
The text to display in the attachment.
The URL of a thumbnail image to display to the left of the attachment text.
Title to display for this attachment, displays under the author.
Providing this makes the title clickable, pointing to this link.
When this is true, a download icon appears and clicking this saves the link to file.
Displays the time next to the text portion.
The message ID of the original message to reply to or to create a thread on. Only available with roomId.
Custom fields for the message, such as a priority. Custom fields must be enabled, and the value must match the validation defined in the Message settings.
The name to display on the message instead of your name. Your username is still displayed.
The URL of an image to display as the message avatar.
The room ID or an array of room IDs where the message is to be sent. You can also use a room name, with or without the # prefix, or a username with the @ prefix. Cannot be combined with roomId. With an array, the message is posted to each room, and the response describes only the first one.
An emoji to display as the message avatar.
The message text to send.
Set to false to stop the server from extracting URLs from text. The message is saved with no urls and no link preview. When the message has attachments, the default is false, and no link preview is generated even with true.
Displays a tiny icon to the left of the author's name.
Providing this makes the author's name clickable and points to the provided link.
Name of the author.
Causes the image, audio, and video sections to be displayed as collapsed when set to true.
Whether this field should be a short field.
The title of this field.
The value of this field, displayed underneath the title value.
The URL of the image to display in the attachment.
Only applicable if the ts field is provided, as it makes the time clickable to this link.
The text to display in the attachment.
The URL of a thumbnail image to display to the left of the attachment text.
Title to display for this attachment, displays under the author.
Providing this makes the title clickable, pointing to this link.
When this is true, a download icon appears and clicking this saves the link to file.
Displays the time next to the text portion.
Custom fields for the message, such as a priority. Custom fields must be enabled, and the value must match the validation defined in the Message settings.
OK
{
"ts": 1793706003432,
"channel": "#general",
"message": {
"alias": "",
"msg": "This is a test!",
"attachments": [],
"parseUrls": true,
"groupable": false,
"ts": "2026-11-03T11:40:03.388Z",
"u": {
"_id": "y65tAmHs93aDChMWu",
"username": "graywolf336",
"name": "Gray Wolf"
},
"rid": "GENERAL",
"_id": "jC9chsFddTvsbFQG7",
"_updatedAt": "2026-11-03T11:40:03.392Z",
"md": [
{
"type": "PARAGRAPH",
"value": [
{
"type": "PLAIN_TEXT",
"value": "This is a test!"
}
]
}
],
"mentions": [],
"channels": [],
"urls": []
},
"success": true
}Bad Request
{
"success": false,
"error": "[invalid-channel]",
"errorType": "invalid-channel"
}{
"success": false,
"error": "must have required property 'roomId'\n must have required property 'channel'\n must match exactly one schema in oneOf",
"errorType": "error-invalid-params"
}{
"success": false,
"error": "must NOT have additional properties\n must have required property 'channel'\n must match exactly one schema in oneOf",
"errorType": "error-invalid-params"
}{
"success": false,
"error": "must NOT have additional properties\n must NOT have additional properties\n must match exactly one schema in oneOf",
"errorType": "error-invalid-params"
}{
"success": false,
"error": "Not enough permission"
}{
"success": false,
"error": "Invalid attachment field, title and value is required"
}{
"success": false,
"error": "Custom fields not enabled"
}{
"success": false,
"error": "Invalid custom fields"
}Unauthorized
{
"success": false,
"error": "You must be logged in to do this."
}