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.

{% hint style="info" %} 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. {% endhint %}

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.

{% hint style="warning" %} URLs that include the same text as the Site URL are referred to as Internal URLs. {% endhint %}

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	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
`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

{% tabs %} {% tab title="Message with Attachments" %}

{
   "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."
            }]
      }]
  }
}

{% endtab %}

{% tab title="Message with Blocks" %}

{
   "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"
               }
            ]
         }
      ]
   }
}

{% endtab %} {% endtabs %}

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

send-message.md

send-message.md

Send message

Payload

Message Object

Blocks Detail

Attachments Detail

Attachment Field Objects

Message Object Example

Example Call

Example Call with PreviewURLs

Example Result

Change Log

Files

send-message.md

Latest commit

History

send-message.md

File metadata and controls

Send message

Payload

Message Object

Blocks Detail

Attachments Detail

Attachment Field Objects

Message Object Example

Example Call

Example Call with PreviewURLs

Example Result

Change Log