Send Message

Print
Dark
Light
PDF

Send Message

Print
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Post

/api/v1/chat.sendMessage

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.

Note: 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.

Change Log

Version	Description
2.4.0	Added validation on user's identity
0.60.0	Added
6.4.0	Add `previewUrls` param

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

Some important things to note about the previewUrls parameter 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 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."
          }
        ]
      }
    ]
  }
}

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

Message with PreviewURLs

{
  "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 http://localhost:3000/"
  },
  "previewUrls": [
    "https://google.com",
    "http://localhost:3000/",
    "https://hola.org/",
    "https://www.usepayday.com/",
    "https://www.getbumpa.com/",
    "https://www.atlassian.com/software/jira"
  ]
}

Expand All

object

message

object

rid

string Required

The room ID where the message is to be sent.

msg

string

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

alias

string

This will cause the message's name to appear as the given alias, but your username will still be displayed. Requires the impersonate-other-user permission

emoji

string

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

avatar

string

If provided, the avatar will be displayed as the provided image url. Requires the impersonate-other-user permission.

attachments

Array of object

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

object

audio_url

string

Audio file to attach. See 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 name clickable and points to this 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 format.

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 parameter 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 to create a thread.

tshow

string

Used when replying in a thread. Message will be sent in channel also if value is true

blocks

object

A message block is an array of objects with any of the following properties. Blocks can have many sections:

type
text
fields

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

previewUrls

Array of string

An array to define which URL previews should be retrieved from each message.

string

Responses

200

Example 1

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

Expand All

object

message

object

rid

string

msg

string

object

_id

string

username

string

name

string

unread

boolean

mentions

Array of object

object

channels

Array of object

object

_updatedAt

string

_id

string

success

boolean

400

Bad Request

Example 1

{
  "success": false,
  "error": "The \"message\" parameter must be provided. [error-invalid-params]",
  "errorType": "error-invalid-params"
}

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

Star Message