# 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>

# User mention (mention)

5.5.3+ You can mention any server user using the following format:

Markdown:

[John Doe](trueconf:john_doe@video.example.com)

HTML:

<a href="trueconf:john_doe@video.example.com">John Doe</a>

If a user is a member of a group chat or channel, they will receive a notification via mention (@) even in a muted chat.

# 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)

Response:

{
  "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 the event 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)

Response:

{
    "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 the event 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

Response:

{
    "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 the event 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

Response:

{
  "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 the event 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

Response:

{
    "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	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 containing the message
messageId	string	Yes	Unique identifier of the message
timestamp	uint64	Yes	Timestamp of the message sending in UNIX timestamp format with millisecond precision
replyMessageId	string	No	If this is a response to a message, it contains the identifier of that message
isEdited	boolean	Yes	Indicates whether the message has been edited
payload.type	uint32	Yes	Type of embedded message. See more in EnvelopeContentType
author.id	string	Yes	Unique identifier of the message author. This is either the user's TrueConf ID or the server name from which the message originates. The type of identifier depends on the `type` field
author.type	uint32	Yes	Type of message author. See more in EnvelopeAuthorTypeEnum
box.id	number	Yes	Sequence number of the "box" containing the message. More details in the relevant section
box.position	string	Yes	Sequence number of the message within the "box". More details 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

# Geolocation

5.5.3+

Parameter	Type	Req.	Description
latitude	number	Yes	Latitude
longitude	number	Yes	Longitude
title	string	Yes	Text description of the location, typically an address

# 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 the event 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

Response:

{
    "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 the event 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

A message with the type 200 is a text message. The content field contains the text of the message, and the parseMode parameter determines how it is interpreted (e.g., Markdown or HTML).

Notification 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": "Текст",
          "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)

# Reply to message

When replying to a message, you will receive a payload with the replyMessageId parameter.

Notification 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
      },
      "replyMessageId": "0c4dc725-ee33-4b91-9543-e4149e5d3ad3",
      "isEdited": false,
      "box": {
          "id": 4,
          "position": "0"
      },
      "type": 200,
      "content": {
          "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)

# Forwarded message

A message with type 201 is identified as forwarded. The content field contains the original message object.

Notification from the server:

{
  "method": "sendMessage",
  "type": 1,
  "id": 8,
  "payload": {
      "chatId": "d0b99ed24d6fb440a99fb12c4face5e5b28c3863",
      "messageId": "b5feca9f-460b-43a4-8ae0-5f908544b16b",
      "timestamp": 1776460454738,
      "author": {
          "id": "echo_bot@video.example.net",
          "type": 1
      },
      "isEdited": false,
      "box": {
          "id": 14,
          "position": "0"
      },
      "type": 201,
      "content": {
          "chatId": "e2cf0a56f8f8e4d263fec8536ea7b63c946939d9",
          "messageId": "73cc1e8b-b38b-4d3d-b6f1-c55682466d84",
          "author": {
              "id": "echo_bot@video.example.net",
              "type": 1
          },
          "type": 202,
          "isEdited": false,
          "timestamp": 1776460454738,
          "content": {
              "name": "bot.log",
              "mimeType": "text/plain",
              "fileId": "c324bb1313fcc50099fbd2bfbb7251f79d473ed6",
              "size": 186543
          },
          "box": {
              "id": 14,
              "position": "0"
          }
      }
  }
}

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

Notification from the server:

{
    "method": "editMessage",
    "type": 1,
    "id": 12,
    "payload": {
        "chatId": "d0b99ed24d6fb440a99fb12c4face5e5b28c3863",
        "messageId": "d4d20b4f-e4a4-4abc-8e66-ff2e17f483b7",
        "timestamp": 1746029430000,
        "content": {
            "text": "🤝",
            "parseMode": "html"
        }
    }
}

Parameter	Type	Req.	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 incremented value assigned by the sender, mandatory in each request to link with the response. Learn more here
chatId	string	Yes	Unique chat identifier where the message is located
messageId	string	Yes	Identifier of the edited message. This identifier can be used later for copying, forwarding, or deleting the message
timestamp	uint64	Yes	Message modification timestamp in UNIX timestamp format with millisecond precision
text	string	Yes	Text of the edited message
parseMode	string	Yes	Formatting mode (see 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

Notification 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)

← Working with Address Book Working with Files →