Post Message

IMPORTANT

You only can send alias and avatar properties if your user has the bot role. We implement this rule to avoid users to impersonate other users.

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

Payload

Argument	Example	Required	Description
roomId channel	ByehQjC44FwMeiLbX #general OR @eric	Required	The room id of where the message is to be sent. The channel name with the prefix in front of it. # refers to channel, however @ refers to username
text	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.
emoji	:smirk:	Optional	If provided, this will make the avatar on this message be an emoji. Emoji Cheetsheet
avatar	http://site.com/logo.png	Optional	If provided, this will make the avatar use the provided image url.
attachments	[{}]	Optional	See the below section, Attachments Detail, for details.
tmid	jC9chsFddTvsbFQG7	Optional	The message id of the original message to reply to/create a thread on.
tshow	true	Optional	Defaults to true when tmid is specified. Message will also be shown in the channel/room if value is true.

Attachments Detail

The attachments 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

{
  "alias": "Gruggy",
  "avatar": "http://res.guggy.com/logo_128.png",
  "channel": "#general",
  "emoji": ":smirk:",
  "roomId": "Xnb2kLD2Pnhdwe3RH",
  "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"
    }
  ]
}

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.postMessage \
     -d '{ "channel": "#general", "text": "This is a test!" }'

Example Result

{
  "ts": 1481748965123,
  "channel": "general",
  "message": {
    "alias": "",
    "msg": "This is a test!",
    "parseUrls": true,
    "groupable": false,
    "ts": "2016-12-14T20:56:05.117Z",
    "u": {
      "_id": "y65tAmHs93aDChMWu",
      "username": "graywolf336"
    },
    "rid": "GENERAL",
    "_updatedAt": "2016-12-14T20:56:05.119Z",
    "_id": "jC9chsFddTvsbFQG7"
  },
  "success": true
}

Change Log

Version	Description
2.4.1	Document existing method to post reply/threaded messages
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