# Working with messages
# Sending a text message in chat
Request:
{
"type": 1,
"id": 1,
"method": "sendMessage",
"payload": {
"chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
"content": {
"text": "Hello, world!",
"parseMode": "text"
}
}
}
| Parameter | Type | Req. | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremented value assigned by the sender, required in each request for subsequent binding with the response. Read more here |
| method | string | Yes | Command sendMessage |
| chatId | string | Yes | Chat identifier |
| replyMessageId | string | No | If replying to a message, the field should contain the identifier of that message (see example below) |
| text | string | Yes | Message text |
| parseMode | string | Yes | Formatting mode (see below) |
Answer:
{
"type": 2,
"id": 1,
"payload": {
"chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
"messageId": "8fe61d87-6db0-4792-8f5e-e5960c7d5a06",
"timestamp": 1735314170572
}
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | uint32 | Yes |
Message type (default is 2). Corresponds to
MESSAGE_TYPE.RESPONSE |
| id | uint32 | Yes | Identifier matching the number sent in the original request, used for linking the request and response |
| chatId | string | Yes | Identifier of the chat to which the message was sent |
| messageId | string | Yes | Message identifier. This identifier can be used later for editing, forwarding, or deleting the message |
| timestamp | uint64 | Yes | Message sending timestamp in UNIX timestamp format with millisecond precision |
In case of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the relevant section of the documentation.
# Message formatting
The chat bot API supports three message formatting types:
text– plain text. All characters will be preserved and displayed.markdown- basic Markdown formatting is supported. Special characters are converted into formatted text (bold, italic, links, etc.);html- HTML tags will be interpreted and displayed as formatted text.
# Markdown
Supported Markdown syntax:
| Style | Syntax | Example | Displayed Text |
|---|---|---|---|
| Bold | ** or __ | **bold text** | bold text |
| Italic | * or _ | _italic text_ | italic text |
| Strikethrough | ~~ | ~~strikethrough text~~ | |
| Link | [Text](https://url) | [Website](https://example.com) | Website |
# HTML
Supported HTML markup syntax:
| Tag | HTML Example | Displayed Text |
|---|---|---|
<b> | <b>bold text</b> | bold text |
<i> | <i>italic text</i> | italic text |
<s> | <s>strikethrough text</s> | |
<u> | <u>underlined text</u> | underlined text |
<a> | <a href="https://example.com">Website</a> | Website |
All additional tag attributes will be removed. For example, the HTML code:
<i style="position: fixed; top:0">Hacked!</i>
will be converted to:
<i>Hacked!</i>
# Reply to an existing message
To reply to an existing message, you need to fill in the replyMessageId field with the identifier of the message you are responding to:
{
"type": 1,
"id": 1,
"method": "sendMessage",
"payload": {
"chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
"replyMessageId": "3d968a21-543c-4fb2-9d8e-e31e3fbb35eb",
"content": {
"text": "Hello, world!",
"parseMode": "text"
}
}
}
# Editing an existing message
Request:
{
"type": 1,
"id": 1,
"method": "editMessage",
"payload": {
"messageId": "8fe61d87-6db0-4792-8f5e-e5960c7d5a06",
"content": {
"text": "Hello, world (edited)!",
"parseMode": "text"
}
}
}
| Parameter | Type | Req. | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. It is an incrementing value assigned by the sender and is mandatory in every request for subsequent response association. Read more here |
| method | string | Yes | Command editMessage |
| messageId | string | Yes | Text message identifier |
| text | string | Yes | Message text |
| parseMode | string | Yes | Formatting mode (see above) |
Answer:
{
"type": 2,
"id": 1,
"payload": {
"messageId": "8fe61d87-6db0-4792-8f5e-e5960c7d5a06",
"timestamp": 1735314170572
}
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE |
| id | uint32 | Yes | Identifier matching the number sent in the original request, used to link the request and response |
| timestamp | uint64 | Yes | Message edit timestamp in UNIX timestamp format with millisecond precision |
| messageId | string | Yes | Identifier of the edited message |
In case of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the relevant section of the documentation.
# Forwarding a message to another chat
Request:
{
"type": 1,
"id": 1,
"method": "forwardMessage",
"payload": {
"chatId": "4a1f88f1070d2f43d385cde9ff61964bc6b74477",
"messageId": "8fe61d87-6db0-4792-8f5e-e5960c7d5a06"
}
}
| Parameter | Type | Req. | Description |
|---|---|---|---|
| type | uint32 | Yes |
Message type (default is 1). Corresponds to
MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremented value assigned by the sender, required in each request to subsequently correlate with the response. More details read here |
| method | string | Yes | Command forwardMessage |
| chatId | string | Yes | Identifier of the chat where you will forward the message |
| messageId | string | Yes | Identifier of the forwarded message |
Answer:
{
"type": 2,
"id": 1,
"payload": {
"chatId": "4a1f88f1070d2f43d385cde9ff61964bc6b74477",
"messageId": "3e168850-d9ea-45ec-a0f7-21c43e8ba2a8",
"timestamp": 1735314170572
}
}
| Parameter | Type | Req. | Description |
|---|---|---|---|
| type | uint32 | Yes |
Message type (default is 2). Corresponds to
MESSAGE_TYPE.RESPONSE |
| id | uint32 | Yes | Identifier matching the number sent in the original request, used to link the request and response |
| chatId | string | Yes | Unique identifier of the chat to which we forwarded the message |
| messageId | string | Yes | Unique identifier of the new message containing your forwarded message |
| timestamp | uint64 | Yes | Timestamp of the message forwarding in UNIX timestamp format with millisecond precision |
In case of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the relevant section of the documentation.
# Retrieving a message by its ID
Request:
{
"type": 1,
"id": 1,
"method": "getMessageById",
"payload": {
"messageId": "8fe61d87-6db0-4792-8f5e-e5960c7d5a06"
}
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | uint32 | Yes |
Type of message (default is 1). Corresponds to
MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique identifier for the request. An incremented value assigned by the sender, required for each request to link with the response. Read more here |
| method | string | Yes | Command getMessageById |
| messageId | string | Yes | Identifier of the requested message |
Answer:
{
"type": 2,
"id": 1,
"payload": {
"chatId": "2b896a6ef210d6b2dcaebc2186c9a7974d616054",
"messageId": "8fe61d87-6db0-4792-8f5e-e5960c7d5a06",
"timestamp": 1234567890,
"author": {
"id": "user@video.example.com",
"type": 1
},
"replyMessageId": null,
"isEdited": true,
"box": {
"id": 123456,
"position": "0"
},
"type": 0,
"content": {
"text": "Hello, chat bot!",
"parseMode": "html"
}
}
}
| Parameter | Type | Req. | Description |
|---|---|---|---|
| type | uint32 | Yes | Type of message (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE |
| id | uint32 | Yes | Identifier matching the number sent in the original request, used to link the request and response |
| chatId | string | Yes | Unique identifier of the chat where the message is located |
| messageId | string | Yes | Unique identifier of the message |
| timestamp | uint64 | Yes | Message send timestamp in UNIX timestamp format with millisecond precision |
| replyMessageId | string | No | If this is a reply to a message, contains the ID of that message |
| isEdited | boolean | Yes | Indicates whether the message has ever been edited |
| payload.type | uint32 | Yes | Type of the nested message. See more at EnvelopeTypeEnum |
| author.id | string | Yes | Unique identifier of the message author. This is either the TrueConf ID of the user or the server name from which the message came. The type of identifier depends on the type field |
| author.type | uint32 | Yes | Type of the message author. See more at EnvelopeAuthorTypeEnum |
| box.id | number | Yes | Sequential number of the "box" containing the message. See more in the relevant section |
| box.position | string | Yes | Sequential number of the message in the "box". See more in the relevant section |
Depending on the value of payload.type, the payload.content object may contain data in one of the following formats:
# Text message
Used when the message contains only text information.
| Parameter | Type | Required | Description |
|---|---|---|---|
| text | string | Yes | Message text |
| parseMode | string | Yes | Formatting mode (see above) |
# Attachment (file)
Used when the message contains a file (document, image, etc.).
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | File name |
| size | number | Yes | File size |
| mimeType | string | Yes | File MIME type |
| fileId | string | Yes | File identifier on the server |
# Forwarded message
Represents an embedded message containing one of the structures described above (text, attachment, etc.) along with additional fields containing metadata. Structurally similar to a regular message, it includes author, timestamp, content, and other fields.
In case of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the relevant section of the documentation.
# Retrieving chat history
Request:
{
"type": 1,
"id": 1,
"method": "getChatHistory",
"payload": {
"chatId": "4a1f88f1070d2f43d385cde9ff61964bc6b74477",
"count": 9999,
"fromMessageId": "e37cfc52-592f-453f-a3dd-275170b2018d"
}
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incrementing value assigned by the sender, required in each request to link it with a response. More details here |
| method | string | Yes | Command getChatHistory |
| chatId | string | Yes | Chat identifier for which the message history is requested |
| count | uint32 | Yes | Number of messages to be returned in the response |
| fromMessageId | string | No | Chat message identifier from which the history will be returned |
Answer:
{
"type": 2,
"id": 1,
"payload": {
"chatId": "4a1f88f1070d2f43d385cde9ff61964bc6b74477",
"count": 1,
"messages": [
{
"messageId": "8fe61d87-6db0-4792-8f5e-e5960c7d5a06",
"timestamp": 1234567890,
"author": {
"id": "user@video.example.com",
"type": 1
},
"replyMessageId": null,
"isEdited": true,
"box": {
"id": 123456,
"position": ""
},
"type": 0,
"content": {
"text": "Hello, chat bot!",
"parseMode": "html"
}
}
]
}
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE |
| id | uint32 | Yes | Identifier matching the number sent in the original request, used to link the request and response |
| chatId | string | Yes | Chat ID for which the message history was requested |
| count | uint32 | Yes | Number of messages received |
| messages | Array<Envelope> | No | An array of Envelope objects, each representing a single message. See parameter descriptions above |
In case of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the relevant section of the documentation.
# Deleting a message
Request:
{
"type": 1,
"id": 1,
"method": "removeMessage",
"payload": {
"messageId": "8fe61d87-6db0-4792-8f5e-e5960c7d5a06",
"forAll": true
}
}
| Parameter | Type | Req. | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incrementing value assigned by the sender, required in each request for subsequent binding with the response. Read more here |
| method | string | Yes | Command removeMessage |
| messageId | string | Yes | Identifier of the message to be removed |
| forAll | boolean | Yes | If true, the message will be removed for everyone |
Answer:
{
"type": 2,
"id": 1,
"payload": {}
}
| Parameter | Type | Req. | Description |
|---|---|---|---|
| type | uint32 | Yes | Type of message (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE |
| id | uint32 | Yes | An identifier matching the number sent in the original request, used to link the request and response |
| payload | object | Yes | In case of success, you will receive an empty object |
In case of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the relevant section of the documentation.