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 |
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.
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 | |
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 | |
blocks | [{}] | Optional | Add message blocks, see blocks details below. |
A message block is an array of objects with any of the following properties. A Blocks can have many sections:
- type
- text
- fields
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 | |
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 | |
video_url | https://site.com/vid.mp4 | Video | |
fields | [{}] | Fields |
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 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"
}
]
}
]
}
}
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!" }}'
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"
]
}'
{
"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
}
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