> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
**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 **Manage** -> **Permissions** -> **message-impersonate**.
### Change Log
| Version | Description |
| ------- | ----------------------------------- |
| 6.8.0 | Allow custom fields in messages |
| 6.4.0 | Add `previewUrls` param |
| 2.4.0 | Added validation on user's identity |
| 0.60.0 | Added |
## OpenAPI
````json POST /api/v1/chat.sendMessage
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Messaging"
},
"servers": [
{
"url": "https://apiexplorer.support.rocket.chat"
}
],
"tags": [
{
"name": "Chat"
},
{
"name": "Direct Messages"
},
{
"name": "Auto-Translate"
}
],
"paths": {
"/api/v1/chat.sendMessage": {
"post": {
"tags": [
"Chat"
],
"summary": "Send Message",
"description": "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.\n\n**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 **Manage** -> **Permissions** -> **message-impersonate**.\n\n### Change Log\n| Version | Description |\n| ------- | ----------------------------------- |\n| 6.8.0 | Allow custom fields in messages | \n| 6.4.0 | Add `previewUrls` param |\n| 2.4.0 | Added validation on user's identity |\n| 0.60.0 | Added |",
"operationId": "post-api-v1-chat.sendMessage",
"parameters": [
{
"$ref": "#/components/parameters/Auth-Token"
},
{
"$ref": "#/components/parameters/UserId"
}
],
"requestBody": {
"description": "**Some important things to note about the `previewUrls` parameter include:**\n* If the `previewUrls` array is empty, no URL will be previewed.\n* If the `previewUrls` parameter isn't sent, all URLs (up to a maximum of five external URLs) will be previewed.\n* If the message contains attachments or quotes, no URL is previewed.\n* Internal URLs are not considered in the `previewUrls` array.\n* A maximum of five external URLs is previewed per message. If there are more than 5 external URLs, no URL is previewed.\n> URLs that include the same text as the **Site URL** are referred to as Internal URLs.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "object",
"properties": {
"t": {
"type": "string",
"description": "The message type e.g. e2e"
},
"rid": {
"type": "string",
"description": "The room ID where the message is to be sent."
},
"msg": {
"type": "string",
"description": "The message text to send, it is optional because of attachments."
},
"alias": {
"type": "string",
"description": "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": {
"type": "string",
"description": "If provided, the avatar will be displayed as the emoji. "
},
"avatar": {
"type": "string",
"description": "If provided, the avatar will be displayed as the provided image url. Requires the `impersonate-other-user` permission."
},
"attachments": {
"type": "array",
"description": "The attachment is an array of objects with any of the following properties. One attachment can have many sections, including:\n* General\n* Author Information\n* Title Information\n* Image\n* Audio\n* Video\n* Table/Fields",
"items": {
"type": "object",
"properties": {
"audio_url": {
"type": "string",
"description": "Audio file to attach. See HTML audio element for information."
},
"author_icon": {
"type": "string",
"description": "Displays a tiny icon to the left of the author's name."
},
"author_link": {
"type": "string",
"description": "Providing this makes the author name clickable and points to this link."
},
"author_name": {
"type": "string",
"description": "Name of the author."
},
"collapsed": {
"type": "boolean",
"description": "Causes the image, audio, and video sections to be displayed as collapsed when set to true."
},
"color": {
"type": "string",
"description": "See background-css for the supported format."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"short": {
"type": "boolean",
"description": "Whether this field should be a short field."
},
"title": {
"type": "string",
"description": "The title of this field."
},
"value": {
"type": "string",
"description": "The value of this field, displayed underneath the title value."
}
},
"required": [
"title",
"value"
]
}
},
"image_url": {
"type": "string",
"description": "The image to display, will be big and easy to see."
},
"message_link": {
"type": "string",
"description": "Only applicable if the `ts` parameter is provided, as it makes the time clickable to this link."
},
"text": {
"type": "string",
"description": "The text to display for this attachment, it is different than the message's text."
},
"thumb_url": {
"type": "string",
"description": "An image that displays to the left of the text, looks better when this is relatively small."
},
"title": {
"type": "string",
"description": "Title to display for this attachment, displays under the author."
},
"title_link": {
"type": "string",
"description": "Providing this makes the title clickable, pointing to this link."
},
"title_link_download": {
"type": "boolean",
"description": "When this is true, a download icon appears and clicking this saves the link to file."
},
"ts": {
"type": "string",
"description": "Displays the time next to the text portion."
},
"video_url": {
"type": "string",
"description": "Video file to attach. See the HTML video element for information."
}
}
}
},
"tmid": {
"type": "string",
"description": "The message ID to create a thread."
},
"tshow": {
"type": "string",
"description": "Used when replying in a thread. Message will be sent in channel also if value is true"
},
"blocks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"text": {
"type": "string"
}
}
},
"description": "A message block is an array of objects with any of the following properties. To view the example on how to use this parameter, select **Show example** in this body parameters section. Above the example code block, select the drop-down menu, and select the **Message with Blocks** option. For comprehensive information on blocks, refer to the Apps-Engine UI Blocks documentation.\nBlocks can have many sections:\n- type\n- text\n- fields"
},
"customFields": {
"type": "object",
"description": "You can add custom fields for messages. For example, set priorities for messages.\n\nYou must enable this option and define the validation in the workspace settings. See the Message settings for further information.",
"example": {
"priority": "high"
}
}
},
"required": [
"rid"
]
},
"previewUrls": {
"type": "array",
"description": "An array to define which URL previews should be retrieved from each message.",
"items": {
"type": "string"
}
}
}
},
"examples": {
"Message with Attachments": {
"value": {
"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": {
"value": {
"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": {
"value": {
"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"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "object",
"properties": {
"rid": {
"type": "string"
},
"msg": {
"type": "string"
},
"ts": {
"type": "string"
},
"u": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"username": {
"type": "string"
},
"name": {
"type": "string"
}
}
},
"unread": {
"type": "boolean"
},
"mentions": {
"type": "array",
"items": {
"type": "object"
}
},
"channels": {
"type": "array",
"items": {
"type": "object"
}
},
"_updatedAt": {
"type": "string"
},
"_id": {
"type": "string"
}
}
},
"success": {
"type": "boolean"
}
}
},
"examples": {
"Example 1": {
"value": {
"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
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/authorizationError"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"error": {
"type": "string"
},
"errorType": {
"type": "string"
}
}
},
"examples": {
"Example 1": {
"value": {
"success": false,
"error": "The \"message\" parameter must be provided. [error-invalid-params]",
"errorType": "error-invalid-params"
}
},
"Example 2": {
"value": {
"success": false,
"error": "The 'rid' property on the message object is missing."
}
},
"Example 3": {
"value": {
"success": false,
"error": "error-invalid-room"
}
}
}
}
}
}
}
}
}
},
"components": {
"parameters": {
"Auth-Token": {
"name": "X-Auth-Token",
"in": "header",
"description": "The `authToken` of the authenticated user.",
"required": true,
"schema": {
"type": "string"
},
"example": "RScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f"
},
"UserId": {
"name": "X-User-Id",
"in": "header",
"description": "The `userId` of the authenticated user.",
"required": true,
"schema": {
"type": "string"
},
"example": "rbAXPnMktTFbNpwtJ"
}
},
"responses": {
"authorizationError": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"message": {
"type": "string"
}
}
},
"examples": {
"Authorization Error": {
"value": {
"status": "error",
"message": "You must be logged in to do this."
}
}
}
}
}
}
}
}
}
````