# Working with messages
For each server notification (request), the client should respond as follows:
{
"type": 2,
"id": 123456
}
Once the response is sent, the user’s message is marked as read by the bot and a check mark appears in the TrueConf client application.
# 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>
# Client requests
# Send message
Request:
{
"type": 1,
"id": 1,
"method": "sendMessage",
"payload": {
"chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
"content": {
"text": "Hello, world!",
"parseMode": "text"
}
}
}
Parameter | Type | Required | 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 to link it with the response. More details here |
method | string | Yes | The command sendMessage |
chatId | string | Yes | Chat identifier |
replyMessageId | string | No | If replying to a message, this field should contain the identifier of that message (see example below) |
text | string | Yes | Message text |
parseMode | string | Yes | Formatting mode (see above) |
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.
# Reply to 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"
}
}
}
# Edit 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.
# Forward message
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.
# Delete 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.
# Retrieve message by 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.
# Retrieve 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.
# Server notifications
# New message
Message from the server:
{
"method": "sendMessage",
"type": 1,
"id": 11,
"payload": {
"chatId": "bd05af54347e04a1c44e70033d35834d4428bb5d",
"messageId": "d66254de-9d89-4130-8027-c5378f042800",
"timestamp": 1746029007569,
"author": {
"id": "brown@video.example.com",
"type": 1
},
"isEdited": false,
"box": {
"id": 4,
"position": "0"
},
"type": 200,
"content": {
"text": "Text",
"parseMode": "html"
}
}
}
The notification of a new message includes fields corresponding to the Envelope object. Detailed descriptions of these fields can be found in the section on working with messages.
Response from client:
{
"type": 2,
"id": 123456
}
Field | Type | Req. | Description |
---|---|---|---|
type | uint32 | Yes | Message type (default is 2 ). Corresponds to MESSAGE_TYPE.RESPONSE |
id | uint32 | Yes | Identifier of the message being responded to (see details) |
# The message has been modified
Message from the server:
{
"method": "editMessage",
"type": 1,
"id": 12,
"payload": {
"messageId": "d4d20b4f-e4a4-4abc-8e66-ff2e17f483b7",
"timestamp": 1746029430000,
"content": {
"text": "🤝",
"parseMode": "text"
}
}
}
Parameter | Type | Required | Description |
---|---|---|---|
method | string | Yes | Command editMessage |
type | uint32 | Yes |
Message type (default 1 ). Corresponds to
MESSAGE_TYPE.REQUEST |
id | uint32 | Yes | Unique request identifier. An incrementing value assigned by the sender, mandatory in each request to link with the response. More details read here |
messageId | string | Yes | Identifier of the edited message. This identifier can be used later for copying, forwarding, or deleting the message |
timestamp | uint64 | Yes | Timestamp of the message modification in UNIX timestamp format with millisecond precision |
text | string | Yes | Text of the edited message |
parseMode | string | Yes | Formatting mode (see more details) |
Response from client:
{
"type": 2,
"id": 123456
}
Field | Type | Req. | Description |
---|---|---|---|
type | uint32 | Yes | Message type (default is 2 ). Corresponds to MESSAGE_TYPE.RESPONSE |
id | uint32 | Yes | Identifier of the message being responded to (see details) |
# The message has been deleted
Message from the server:
{
"method": "removeMessage",
"type": 1,
"id": 12,
"payload": {
"chatId": "bd05af54347e04a1c44e70033d35834d4428bb5d",
"messageId": "d4d20b4f-e4a4-4abc-8e66-ff2e17f483b7",
"removedBy": {
"id": "brown@video.example.com",
"type": 1
}
}
}
Parameter | Type | Required | Description |
---|---|---|---|
method | string | Yes | Command removeMessage |
type | uint32 | Yes |
Message type (default is 1 ). Corresponds to
MESSAGE_TYPE.REQUEST |
id | uint32 | Yes | Unique request identifier. Incremental value assigned by the sender, required in each request for subsequent linking with the response. Read more here |
chatId | string | Yes | Identifier of the chat where the message was removed |
messageId | string | Yes | Identifier of the removed message. This identifier can be used later for copying, forwarding, or deleting the message |
removedBy.id | string | Yes |
Unique identifier of the user who removed the message. This is either the TrueConf ID or the name of the server from which the message originated.
The type of identifier depends on the removedBy.type field
|
removedBy.type | uint32 | Yes | Type of user who removed the message. For more details, see EnvelopeAuthorTypeEnum |
Response from client:
{
"type": 2,
"id": 123456
}
Field | Type | Req. | Description |
---|---|---|---|
type | uint32 | Yes | Message type (default is 2 ). Corresponds to MESSAGE_TYPE.RESPONSE |
id | uint32 | Yes | Identifier of the message being responded to (see details) |