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~~	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>	strikethrough text
<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)