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

URL	Requires Auth	HTTP Method
`/api/v1/chat.sendMessage`	`yes`	`POST`

/api/v1/chat.sendMessage

yes

POST

Payload

Argument Example Required Description

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.

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

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.

_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

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	An array of Attachment Field Objects.

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

An array of Attachment Field Objects.

Attachment Field Objects

The field property of the attachments allows for "tables" or "columns" to be displayed on messages.

Property Example Required Description

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.

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": {
      "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 updated 7 months ago