Links
Comment on page

Send message

The difference between chat.postMessage and chat.sendMessage is that chat.sendMessage allows for passing a value for _id and the other one doesn't. Also, chat.sendMessage only sends it to one channel whereas the other one allows for sending to more than one channel at a time.
IMPORTANT
You can only send alias and avatar properties if your user has the message-impersonate permission. We implemented this rule to avoid users impersonating other users. By default, only the bot role has this permission, but that can be changed in Administration -> Permissions -> message-impersonate.
URL
Requires Auth
HTTP Method
/api/v1/chat.sendMessage
yes
POST

Payload

Argument
Example
Required
Description
message
{
"rid": "64f0f82c2c26843a68c1f7ba",
"msg": "Sample message"
}
Required
A message object containing all message data.
previewUrls
['https://google.com', 'https://rocket.chat']
Optional
An array to define which URL previews should be retrieved from each message.
Some important things to note about previewUrls include:
  • If the previewUrls array is empty, no URL will be previewed.
  • If the previewUrls parameter isn't sent, all URLs (up to a maximum of five external URLs) will be previewed.
  • If the message contains attachments or quotes, no URL is previewed.
  • Internal URLs are not considered in the previewUrls array.
  • A maximum of five external URLs is previewed per message. If there are more than 5 external URLs, no URL is previewed.
URLs that include the same text as the Site URL are referred to as Internal URLs.

Message Object

Argument
Example
Required
Description
_id
ByehQjC44FwMeiLbX
Optional
The _id of message.
rid
ByehQjC44FwMeiLbX
Required
The room id of where the message is to be sent.
tmid
ByehQCh2435MeiLbX
Optional
The message's id to create a thread.
msg
Sample message
Optional
The text of the message to send, is optional because of attachments.
alias
Some Name
Optional
This will cause the message's name to appear as the given alias, but your username will still display. Require the impersonate-other-user role
emoji
:smirk:
Optional
If provided, this will make the avatar on this message be an emoji. Emoji Cheetsheet​
tshow
true
Optional
Used when replying in a thread. Message will be sent in channel also if value is true
avatar
http://site.com/logo.png
Optional
If provided, this will make the avatar use the provided image url. Require the impersonate-other-user role
attachments
[{}]
Optional
See the below section, Attachments Detail, for details.
blocks
[{}]
Optional
Add message blocks, see blocks details below.

Blocks Detail

A message block is an array of objects with any of the following properties. A Blocks can have many sections:
  • type
  • text
  • fields

Attachments Detail

The attachment is an array of objects with any of the following properties. One attachment can have many sections, including:
  • General
  • Author Information
  • Title Information
  • Image
  • Audio
  • Video
  • Table/Fields
Property
Example
Section
Description
color
#ff0000
General
The color you want the order on the left side to be, any value background-css supports.
text
Sample attachment text
General
The text to display for this attachment, it is different than the message's text.
ts
2016-12-09T16:53:06.761Z
General
Displays the time next to the text portion.
thumb_url
https://site.com/img.png
General
An image that displays to the left of the text, looks better when this is relatively small.
message_link
https://rocket.chat
General
Only applicable if the ts is provided, as it makes the time clickable to this link.
collapsed
false
General
Causes the image, audio, and video sections to be hiding when collapsed is true.
author_name
Bradley Hilton
Author
Name of the author.
author_link
https://bit.ly/
Author
Providing this makes the author name clickable and points to this link.
author_icon
https://site.com/img.png
Author
Displays a tiny icon to the left of the Author's name.
title
Attachment Title
Title
Title to display for this attachment, displays under the author.
title_link
https://youtube.com
Title
Providing this makes the title clickable, pointing to this link.
title_link_download
true
Title
When this is true, a download icon appears and clicking this saves the link to file.
image_url
https://site.com/img.png
Image
The image to display, will be "big" and easy to see.
audio_url
https://site.com/aud.mp3
Audio
Audio file to play, only supports what html audio does.
video_url
https://site.com/vid.mp4
Video
Video file to play, only supports what html video does.
fields
[{}]
Fields

Attachment Field Objects

The field property of the attachments allows for "tables" or "columns" to be displayed on messages.
Property
Example
Required
Description
short
true
Optional Default: false
Whether this field should be a short field.
title
Status
Required
The title of this field.
value
online
Required
The value of this field, displayed underneath the title value.

Message Object Example

Message with Attachments
Message with Blocks
{
"message": {
"rid": "Xnb2kLD2Pnhdwe3RH",
"msg": "Sample message",
"alias": "Gruggy",
"emoji": ":smirk:",
"avatar": "http://res.guggy.com/logo_128.png",
"attachments": [{
"color": "#ff0000",
"text": "Yay for gruggy!",
"ts": "2016-12-09T16:53:06.761Z",
"thumb_url": "http://res.guggy.com/logo_128.png",
"message_link": "https://google.com",
"collapsed": false,
"author_name": "Bradley Hilton",
"author_link": "https://rocket.chat/",
"author_icon": "https://avatars.githubusercontent.com/u/850391?v=3",
"title": "Attachment Example",
"title_link": "https://youtube.com",
"title_link_download": true,
"image_url": "http://res.guggy.com/logo_128.png",
"audio_url": "http://www.w3schools.com/tags/horse.mp3",
"video_url": "http://www.w3schools.com/tags/movie.mp4",
"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."
}]
}]
}
}
{
"message":{
"rid":"GENERAL",
"blocks":[
{
"type":"section",
"text":{
"type":"mrkdwn",
"text":"*Text example* Normal message `code` here"
}
},
{
"type":"divider"
},
{
"type":"section",
"fields":[
{
"type":"mrkdwn",
"text":"*Field 1*"
},
{
"type":"mrkdwn",
"text":"Field 2"
}
]
}
]
}
}

Example Call

curl -H "X-Auth-Token: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq" \
-H "X-User-Id: aobEdbYhXfu5hkeqG" \
-H "Content-type:application/json" \
http://localhost:3000/api/v1/chat.sendMessage \
-d '{"message": { "rid": "Xnb2kLD2Pnhdwe3RH", "msg": "This is a test!" }}'

Example Call with PreviewURLs

curl -L -X POST 'http://localhost:3000/api/v1/chat.sendMessage' \
-H 'x-auth-token: wrhSO31BO6Zn6G5Aa_bj-kMmImONHDjXrOwGtBpQIPM' \
-H 'x-user-id: rbAXPnMktTFbNpwtJ' \
-H 'Content-Type: application/json' \
-d '{
"message": {
"rid": "64f0f82c2c26843a68c1f7ba",
"msg": "This is a list of links! https://google.com https://hola.org/ https://www.usepayday.com/ https://www.getbumpa.com/ https://www.atlassian.com/software/jira https://writing-demo.dev.rocket.chat"
},
"previewUrls": [
"https://google.com",
"https://writing-demo.dev.rocket.chat",
"https://hola.org/",
"https://www.usepayday.com/",
"https://www.getbumpa.com/",
"https://www.atlassian.com/software/jira"
]
}'

Example Result

{
"message": {
"rid": "GENERAL",
"msg": "123456789",
"ts": "2018-03-01T18:02:26.825Z",
"u": {
"_id": "i5FdM4ssFgAcQP62k",
"username": "rocket.cat",
"name": "test"
},
"unread": true,
"mentions": [],
"channels": [],
"_updatedAt": "2018-03-01T18:02:26.828Z",
"_id": "LnCSJxxNkCy6K9X8X"
},
"success": true
}

Change Log

Version
Description
2.4.0
Added validation on user's identity
0.60.0
Added
6.4.0
Add previewUrls param
​
Last modified 2mo ago
Deprecation for cloud services and apps is now extended to November 20, 2023. Rocket.Chat versions receive support for six months after release.