> ## 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.
# Post Message
> Send messages to channels or users on your workspace.
**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 |
| 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 |
## OpenAPI
````json POST /api/v1/chat.postMessage
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Messaging"
},
"servers": [
{
"url": "https://apiexplorer.support.rocket.chat"
}
],
"tags": [
{
"name": "Chat"
},
{
"name": "DM"
},
{
"name": "Auto-Translate"
}
],
"paths": {
"/api/v1/chat.postMessage": {
"post": {
"tags": [
"Chat"
],
"summary": "Post Message",
"description": "Send messages to channels or users on your workspace.\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| 2.4.1 | Document existing method to post reply/threaded messages |\n| 2.4.0 | Added validation on user's identity |\n| 0.49.0 | The `channel` can now be a room's id. |\n| 0.48.0 | Information about the sent message is now returned. |\n| 0.17.0 | Messages aren't always processed as from BOT and urls are parsed by default. |\n| 0.14.0 | Internally using `processWebhookMessage` which enabled more features. |\n| 0.13.0 | Added |",
"operationId": "post-api-v1-chat.postMessage",
"parameters": [
{
"$ref": "#/components/parameters/Auth-Token"
},
{
"$ref": "#/components/parameters/UserId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"required": [
"roomId"
],
"properties": {
"alias": {
"type": "string",
"description": "This will cause the message's name to appear as the given alias, but your username will still be displayed."
},
"avatar": {
"type": "string",
"description": "If provided, the avatar will be displayed as the provided image URL."
},
"emoji": {
"type": "string",
"description": "If provided, the avatar will be displayed as an emoji.",
"example": ":smile:"
},
"roomId": {
"type": "string",
"description": "The room ID or an array of room IDs 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": {
"type": "string",
"description": "The message text to send, it is optional because of attachments."
},
"parseUrls": {
"type": "boolean",
"description": "Set `parseUrls` to `false` to prevent Rocket.Chat from generating link previews when the message in `text` contains a URL."
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"audio_url": {
"type": "string",
"description": "Audio file to attach. See the 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's name clickable and points to the provided 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 colors.'"
},
"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` field 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 of the original message to reply to or to create a thread on."
},
"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"
}
}
}
},
{
"type": "object",
"required": [
"channel"
],
"properties": {
"alias": {
"type": "string",
"description": "This will cause the message's name to appear as the given alias, but your username will still be displayed."
},
"avatar": {
"type": "string",
"description": "If provided, the avatar will be displayed as the provided image URL."
},
"channel": {
"type": "string",
"description": "The channel ID or an array of channel IDs 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": "#test-room"
},
"emoji": {
"type": "string",
"description": "If provided, the avatar will be displayed as an emoji.",
"example": ":smile:"
},
"text": {
"type": "string",
"description": "The message text to send, it is optional because of attachments."
},
"parseUrls": {
"type": "boolean",
"description": "Set `parseUrls` to `false` to prevent Rocket.Chat from generating link previews when the message in `text` contains a URL."
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"audio_url": {
"type": "string",
"description": "Audio file to attach. See the 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's name clickable and points to the provided 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 colors.'"
},
"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` field 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."
}
}
}
},
"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"
}
}
}
}
]
},
"examples": {
"Example": {
"value": {
"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"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ts": {
"type": "integer"
},
"channel": {
"type": "string"
},
"message": {
"type": "object",
"properties": {
"alias": {
"type": "string"
},
"msg": {
"type": "string"
},
"parseUrls": {
"type": "boolean"
},
"groupable": {
"type": "boolean"
},
"ts": {
"type": "string"
},
"u": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"username": {
"type": "string"
}
}
},
"rid": {
"type": "string"
},
"_updatedAt": {
"type": "string"
},
"_id": {
"type": "string"
}
}
},
"success": {
"type": "boolean"
}
}
},
"examples": {
"Example": {
"value": {
"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"
}
}
}
}
}
},
"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": {
"Missing or invalid room ID": {
"value": {
"success": "false",
"error": "[invalid-channel]",
"errorType": "invalid-channel"
}
}
}
}
}
}
}
}
}
},
"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."
}
}
}
}
}
}
}
}
}
````