Post Message

Print
Dark
Light
PDF

Post Message

Print
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Post

/api/v1/chat.postMessage

Send messages to channels. Note: 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.

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

Header parameters

X-Auth-Token

stringRequired

The authToken of the authenticated user.

ExampleRScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f

X-User-Id

stringRequired

The userId of the authenticated user.

ExamplerbAXPnMktTFbNpwtJ

Body parameters

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

Expand All

object

alias

string

This will cause the message's name to appear as the given alias, but your username will still be displayed.

avatar

string

If provided, the avatar will be displayed as the provided image URL.

channel

string

emoji

string

If provided, the avatar will be displayed as an emoji.

Example:smile:

roomId

string Required

The room ID where the message is to be sent. You can use channel name or username. The channel name must have the # prefix. @ refers to username.

Example#general

text

string

The message text to send, it is optional because of attachments.

attachments

Array of object

object

audio_url

string

Audio file to attach. See the HTML audio element for information.

author_icon

string

Displays a tiny icon to the left of the author's name.

author_link

string

Providing this makes the author's name clickable and points to the provided link.

author_name

string

Name of the author.

collapsed

boolean

Causes the image, audio, and video sections to be displayed as collapsed when set to true.

color

string

See background-css for the supported colors.'

fields

Array of object

object

short

boolean

Whether this field should be a short field.

title

string Required

The title of this field.

value

string Required

The value of this field, displayed underneath the title value.

image_url

string

The image to display, will be big and easy to see.

message_link

string

Only applicable if the ts field is provided, as it makes the time clickable to this link.

text

string

The text to display for this attachment, it is different than the message's text.

thumb_url

string

An image that displays to the left of the text, looks better when this is relatively small.

title

string

Title to display for this attachment, displays under the author.

title_link

string

Providing this makes the title clickable, pointing to this link.

title_link_download

boolean

When this is true, a download icon appears and clicking this saves the link to file.

string

Displays the time next to the text portion.

video_url

string

Video file to attach. See the HTML video element for information.

tmid

string

The message ID of the original message to reply to or to create a thread on.

tmshow

boolean

Defaults to true when the tmid parameter is specified. Message will also be shown in the room if the value is true.

customFields

object

You can add custom fields for messages. For example, set priorities for messages.

You must enable this option and define the validation in the workspace settings. See the Message settings for further information.

Example{ "priority": "high" }

Responses

200

Example 1

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

Expand All

object

integer

channel

string

message

object

alias

string

msg

string

parseUrls

boolean

groupable

boolean

string

object

_id

string

username

string

rid

string

_updatedAt

string

_id

string

success

boolean

400

Bad Request

Missing or invalid room ID

{
  "success": false,
  "error": "[invalid-channel]",
  "errorType": "invalid-channel"
}

object

success

boolean

error

string

errorType

string

401

Unauthorized

Authorization Error

{
  "status": "error",
  "message": "You must be logged in to do this."
}

object

status

string

message

string

Was this article helpful?

What's Next

Unpin a message