Working with Messages

TrueConfAbout 20 min

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.

Formatting Messages

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	Example of HTML	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 through a mention (@) even if the chat is muted.

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	Mandatory	Description
type	uint32	Yes	Message type (default is `1`). Corresponds to MESSAGE_TYPE.REQUEST
id	uint32	Yes	Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here.
method	string	Yes	The `sendMessage` command
chatId	string	Yes	Chat ID
replyMessageId	string	No	If we are replying to a message, the field must 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	Mandatory	Description
type	uint32	Yes	Message type (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.
chatId	string	Yes	Chat ID to which the message was sent
messageId	string	Yes	Message ID. This identifier can be used later to modify, forward, or delete the message.
timestamp	uint64	Yes	Timestamp of message sent 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 corresponding 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	Mandatory	Description
type	uint32	Yes	Message type (default is `1`). Corresponds to MESSAGE_TYPE.REQUEST
id	uint32	Yes	Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here.
method	string	Yes	Command `editMessage`
messageId	string	Yes	Text message ID
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	Mandatory	Description
type	uint32	Yes	Message type (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.
timestamp	uint64	Yes	Timestamp of the message edit in UNIX timestamp format with millisecond precision.
messageId	string	Yes	Edited message ID

In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding section of the documentation.

Forward message

Request:

{
    "type": 1,
    "id": 1,
    "method": "forwardMessage",
    "payload": {
        "chatId": "4a1f88f1070d2f43d385cde9ff61964bc6b74477",
        "messageId": "8fe61d87-6db0-4792-8f5e-e5960c7d5a06"
    }
}

Parameter	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `1`). Corresponds to MESSAGE_TYPE.REQUEST
id	uint32	Yes	Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here.
method	string	Yes	Command `forwardMessage`
chatId	string	Yes	Chat ID to which you will forward the message
messageId	string	Yes	Forwarded message ID

Response:

{
    "type": 2,
    "id": 1,
    "payload": {
        "chatId": "4a1f88f1070d2f43d385cde9ff61964bc6b74477",
        "messageId": "3e168850-d9ea-45ec-a0f7-21c43e8ba2a8",
        "timestamp": 1735314170572
    }
}

Parameter	Type	Mandatory	Description
type	uint32	Yes	Message type (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.
chatId	string	Yes	Unique identifier of the chat to which the message was forwarded
messageId	string	Yes	Unique identifier of the new message containing your forwarded message
timestamp	uint64	Yes	Message forwarding 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 corresponding section of the documentation.

Delete message

Request:

{
    "type": 1,
    "id": 1,
    "method": "removeMessage",
    "payload": {
        "messageId": "8fe61d87-6db0-4792-8f5e-e5960c7d5a06",
        "forAll": true
    }
}

Parameter	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `1`). Corresponds to MESSAGE_TYPE.REQUEST
id	uint32	Yes	Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here.
method	string	Yes	The `removeMessage` command
messageId	string	Yes	ID of the message to be deleted
forAll	boolean	Yes	If `true`, the message will be deleted for everyone

Response:

{
  "type": 2,
  "id": 1,
  "payload": {}
}

Parameter	Type	Mandatory	Description
type	uint32	Yes	Message type (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 corresponding section of the documentation.

Get message by ID

Request:

{
    "type": 1,
    "id": 1,
    "method": "getMessageById",
    "payload": {
        "messageId": "8fe61d87-6db0-4792-8f5e-e5960c7d5a06"
    }
}

Parameter	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `1`). Corresponds to MESSAGE_TYPE.REQUEST
id	uint32	Yes	Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here.
method	string	Yes	Command `getMessageById`
messageId	string	Yes	Requested message ID

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	Mandatory	Description
type	uint32	Yes	Message type (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.
chatId	string	Yes	Unique identifier of the chat containing the message
messageId	string	Yes	Unique message identifier
timestamp	uint64	Yes	Timestamp of message sent in UNIX timestamp format with millisecond precision
replyMessageId	string	No	If this is a reply to a message, it contains the identifier of that message.
isEdited	boolean	Yes	Has the message ever been edited
payload.type	uint32	Yes	Type of embedded message. For more details, see EnvelopeContentType.
author.id	string	Yes	Unique identifier of the message author. This can either be the TrueConf ID of the user or the name of the server from which the message was sent. The type of identifier depends on the `type` field.
author.type	uint32	Yes	Message author type. For more details, see EnvelopeAuthorTypeEnum.
box.id	number	Yes	Serial number of the "box" containing the message. For more details, refer to the relevant section.
box.position	string	Yes	Sequential number of the message in the "box". For more details, see 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	Mandatory	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	Mandatory	Description
name	string	Yes	Filename
size	number	Yes	File size
mimeType	string	Yes	MIME type of the file
fileId	string	Yes	File ID on the server

Geolocation 5.5.3+

Parameter	Type	Mandatory	Description
latitude	number	Yes	Latitude
longitude	number	Yes	Longitude
title	string	Yes	Text description of the location. Usually, the address

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 corresponding section of the documentation.

Get chat history

Request:

{
    "type": 1,
    "id": 1,
    "method": "getChatHistory",
    "payload": {
        "chatId": "4a1f88f1070d2f43d385cde9ff61964bc6b74477",
        "count": 9999,
        "fromMessageId": "e37cfc52-592f-453f-a3dd-275170b2018d"
    }
}

Parameter	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `1`). Corresponds to MESSAGE_TYPE.REQUEST
id	uint32	Yes	Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here.
method	string	Yes	Command `getChatHistory`
chatId	string	Yes	The chat ID for which the message history is requested.
count	uint32	Yes	Number of messages 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	Mandatory	Description
type	uint32	Yes	Message type (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.
chatId	string	Yes	Chat ID for which the message history was requested
count	uint32	Yes	Number of received messages
messages	Array<Envelope>	No	An array of `Envelope` objects, each representing a single message. See the parameter description above.

In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding section of the documentation.

Server Notifications

New message

A message with type 200 is a text message. The content field contains the message text, 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": "Hello, world!,
          "parseMode": "html"
      }
    }
}

The new message notification contains fields corresponding to the Envelope object. A detailed description of these fields can be found in the section dedicated to message handling.

Response from client:

{
    "type": 2,
    "id": 123456
}

Field	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `2`). Corresponds to MESSAGE_TYPE.RESPONSE
id	uint32	Yes	Message ID being replied to (see more)

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": "Hello., world!,
          "parseMode": "html"
      }
  }
}

The new message notification contains fields corresponding to the Envelope object. A detailed description of these fields can be found in the section dedicated to message handling.

Response from client:

{
    "type": 2,
    "id": 123456
}

Field	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `2`). Corresponds to MESSAGE_TYPE.RESPONSE
id	uint32	Yes	Message ID being replied to (see more)

Forwarded message

A message with type 201 is identified as a forwarded message. 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 new message notification contains fields corresponding to the Envelope object. A detailed description of these fields can be found in the section dedicated to message handling.

Response from client:

{
    "type": 2,
    "id": 123456
}

Field	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `2`). Corresponds to MESSAGE_TYPE.RESPONSE
id	uint32	Yes	Message ID being replied to (see more)

The message has been edited

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	Mandatory	Description
method	string	Yes	Command `editMessage`
type	uint32	Yes	Message type (default is `1`). Corresponds to MESSAGE_TYPE.REQUEST
id	uint32	Yes	Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here.
chatId	string	Yes	Unique identifier of the chat containing the message
messageId	string	Yes	The identifier of the edited message. This identifier can be used later for copying, forwarding, or deleting the message.
timestamp	uint64	Yes	Timestamp of message modification in UNIX timestamp format with millisecond precision
text	string	Yes	Edited message text
parseMode	string	Yes	Formatting mode (see details)

Response from client:

{
    "type": 2,
    "id": 123456
}

Field	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `2`). Corresponds to MESSAGE_TYPE.RESPONSE
id	uint32	Yes	Message ID being replied to (see more)

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	Mandatory	Description
method	string	Yes	The `removeMessage` command
type	uint32	Yes	Message type (default is `1`). Corresponds to MESSAGE_TYPE.REQUEST
id	uint32	Yes	Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here.
chatId	string	Yes	Chat ID where the message was deleted
messageId	string	Yes	Remote message ID. This ID can be used for copying, forwarding, or deleting the message in the future.
removedBy.id	string	Yes	Unique identifier of the user who deleted the message. This could be either a 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 deleted the message. For more details, see EnvelopeAuthorTypeEnum

Response from client:

{
    "type": 2,
    "id": 123456
}

Field	Type	Mandatory	Description
type	uint32	Yes	Message type (default is `2`). Corresponds to MESSAGE_TYPE.RESPONSE
id	uint32	Yes	Message ID being replied to (see more)