API Reference Guide

TrueConfAbout 17 min

API Reference Guide

Envelope

Each message received as an event (notification sendMessage), loaded by message ID (getMessageById), or obtained from the chat message history (getChatHistory), corresponds to an Envelope object.

The payload field of the sendMessage notification is an Envelope object — the examples below show it without the request wrapper.

interface Envelope {
  chat: Chat;
  chatId?: string;
  messageId: string;
  timestamp: number;
  replyMessage?: Envelope;
  replyMessageId?: string;
  isEdited: boolean;
  type: EnvelopeContentType;
  author: EnvelopeAuthor;
  box: EnvelopeBox;
  content: AbstractEnvelopeContent;
}

Envelope Fields

ParameterTypeMandatoryDescription
chatChatYesInformation about the chat where the message is located. For more details, see Chat.
chatIdstringNoDeprecated in 5.5.6 Unique chat identifier where the message is located. Use the chat.chatId field.
messageIdstringYesUnique message identifier
timestampuint64YesTimestamp of message sent in UNIX timestamp format with millisecond precision
replyMessageEnvelopeNoThe original message if the current message is a reply. It is structured similarly to a regular message. For examples, see the section “Envelope Examples”.
replyMessageIdstringNoThe identifier of the original message, if the current message is a reply.
isEditedbooleanYesHas the message ever been edited
typeuint32YesMessage type. See more at EnvelopeContentType
author.idstringYesUnique message author's identifier: the user's TrueConf ID or the name of the server from which the message was received. The identifier format is determined by the author.type field.
author.typeuint32YesMessage author type. For more details, see EnvelopeAuthorTypeEnum.
box.idnumberYesThe serial number of the "box" containing the message. For more details, see the relevant section.
box.positionstringYesMessage sequence number in the "box". For more details, see the relevant section.
contentAbstractEnvelopeContentYesMessage content. The set of fields depends on the type value. See AbstractEnvelopeContent and examples for more details.

Chat

The object contains information about the chat where the message is located:

interface Chat {
  chatId: string;
  chatTitle: string | null;
  chatType: ChatTypeEnum;
}
ParameterTypeMandatoryDescription
chatIdstringYesUnique chat ID
chatTitle*строкаnull*Yes
chatTypeChatTypeEnumYesChat type. See ChatTypeEnum for more details.

EnvelopeAuthor

The object contains information about the message author:

ParameterTypeMandatoryDescription
idstringYesUnique identifier of the message author. This can be either the TrueConf ID of the user who sent the message or the name of the server from which it was sent. The type of identifier depends on the value of the type field.
typeuint32YesMessage author type. For more details, see EnvelopeAuthorTypeEnum.

EnvelopeBox

This object is used for sorting messages.

ParameterTypeMandatoryDescription
idnumberYesThe serial number of the "box" containing the message
positionstringYesSequential message number in the "box"

You can learn how to work with this object in the corresponding section.

AbstractEnvelopeContent

Basic interface for message content:

interface AbstractEnvelopeContent {}

The interface does not contain any proprietary fields. The actual composition of the content object is determined by the value of the Envelope.type field from the EnvelopeContentType enumeration. A separate interface is used for each message type:

The value of Envelope.typeContent Interface
System messages
ADD_PARTICIPANTAddParticipantContent
REMOVE_PARTICIPANTRemoveParticipantContent
EDIT_CHAT_TITLEEditChatTitleContent
EDIT_CHAT_AVATAREditChatAvatarContent
CLEAR_CHAT_HISTORYClearChatHistoryContent
PARTICIPANT_ROLEParticipantRoleContent
Custom messages
PLAIN_MESSAGEPlainMessageContent
FORWARDED_MESSAGEForwardMessageContent
ATTACHMENTAttachmentContent
GEOLOCATIONGeolocationContent
ОПРОСSurveyContent
VOICEVoiceContent

AddParticipantContent

Content of the system message about adding a participant to the chat (ADD_PARTICIPANT):

interface AddParticipantContent extends AbstractEnvelopeContent {
  userId: string;
  role: ChatParticipantRoleEnum;
}

Example content:

{
  "userId": "user@video.example.net",
  "role": "user"
}

RemoveParticipantContent

Content of the system message about removing a participant from the chat (REMOVE_PARTICIPANT):

interface RemoveParticipantContent extends AbstractEnvelopeContent {
  userId: string;
}

Example content:

{
  "userId": "user@video.example.net"
}

EditChatTitleContent

Content of the system message about changing the chat title (EDIT_CHAT_TITLE):

interface EditChatTitleContent extends AbstractEnvelopeContent {
  title: string;
}

Example content:

{
  "title": "New chat name"
}

EditChatAvatarContent

Content of the system message about changing the chat image (EDIT_CHAT_AVATAR):

interface EditChatAvatarContent extends AbstractEnvelopeContent {
  avatarUrl: string | null;
}

The null value indicates that the chat image has been deleted.

Example content:

{
  "avatarUrl": "https://video.example.net/bridge/api/client/v1/message/123/preview"
}

ClearChatHistoryContent

Content of the system message about clearing chat history (CLEAR_CHAT_HISTORY):

interface ClearChatHistoryContent extends AbstractEnvelopeContent {
  forAll: boolean;
}

The forAll field indicates whether the history has been cleared for all chat participants.

Example content:

{
  "forAll": true
}

ParticipantRoleContent

Content of the system message about participant role change (PARTICIPANT_ROLE):

interface ParticipantRoleContent extends AbstractEnvelopeContent {
  userId: string;
  role: ChatParticipantRoleEnum;
}

Example content:

{
  "userId": "user@video.example.net",
  "role": "admin"
}

PlainMessageContent

Text message content (PLAIN_MESSAGE):

interface PlainMessageContent extends AbstractEnvelopeContent {
  text: string;
  parseMode: TextParseModeEnum;
  buttons?: object[][];
}

The buttons field contains rows of inline buttons and is present only in messages with buttons.

Example content:

{
  "text": "New message",
  "parseMode": "html"
}

ForwardMessageContent

Content of the forwarded message (FORWARDED_MESSAGE):

interface ForwardMessageContent
  extends Omit<Envelope, "box">, AbstractEnvelopeContent {}

The interface complies with the Envelope object, excluding the box field.

Example content:

AttachmentContent

Message content with an attached file (ATTACHMENT):

interface AttachmentContent extends AbstractEnvelopeContent {
  name: string;
  mimeType: string;
  fileId: string;
  size: number;
}

Example content:

{
  "name": "image.webp",
  "mimeType": "image/webp",
  "fileId": "8e756a04793267fe75695006d891ec487fe4c685",
  "size": 37856
}

GeolocationContent

Message content with geolocation (GEOLOCATION):

interface GeolocationContent extends AbstractEnvelopeContent {
  latitude: number;
  longitude: number;
  title: string;
}

Example content:

{
  "latitude": 47.227208,
  "longitude": 39.70418,
  "title": "Rostov-on-Don"
}

SurveyContent

Content of the survey message (SURVEY):

interface SurveyContent extends AbstractEnvelopeContent {
  url: string;
  title: string;
  path?: string;
  description?: string;
  buttonText?: string;
  appVersion?: number;
  secret?: string;
  alt?: string;
}

Example content:

{
  "url": "https://video.example.net/webtools/survey?id=FVxLn7LxrVsDh2zCoLkfq7",
  "appVersion": 1,
  "path": "FVxLn7LxrVsDh2zCoLkfq7",
  "title": "📊 Survey",
  "description": "{{Survey}}",
  "buttonText": "{{Go to survey}}",
  "secret": "xPlNHP1Okj",
  "alt": "📊 Survey"
}

VoiceContent

Voice message content (VOICE):

interface VoiceContent extends AbstractEnvelopeContent {
  mimeType: string;
  fileId: string;
  size: number;
  duration: number;
}

The duration field contains the length of the voice message in milliseconds.

Example content:

{
  "mimeType": "voice/m4a",
  "fileId": "afc3cd19a480f22243afda3efe15ca4db0775f52",
  "size": 20277,
  "duration": 5043
}

Examples of Envelope

Below are examples of the payload object (Envelope) for different message types. The examples are shown without the sendMessage request wrapper.

Text message
{
    "chat": {
        "chatId": "55f940ecdc66e2c983f8fbd1f954ba72db7d3e9d",
        "chatTitle": "elisa@video.example.net",
        "chatType": 1
    },
    "chatId": "55f940ecdc66e2c983f8fbd1f954ba72db7d3e9d",
    "messageId": "222598d7-9ef9-4663-87e0-8e30804bdb22",
    "timestamp": 1790779432327,
    "author": {
        "id": "elisa@video.example.net",
        "type": 1
    },
    "box": {
        "id": 114,
        "position": "0"
    },
    "type": 200,
    "content": {
        "text": "New message",
        "parseMode": "html"
    },
    "isEdited": false
}

Enums

ChatTypeEnum

The enumeration contains possible chat types.

enum ChatTypeEnum {
    UNDEF = 0,
    P2P = 1,
    GROUP = 2,
    SYSTEM = 3,
    FAVORITES = 5,
    CHANNEL = 6
}

where:

  • UNDEF - unknown chat type
  • P2P - personal messages (chat with another user)
  • GROUP - group chat
  • SYSTEM - system chat
  • FAVORITES - "Favorites" chat (saved messages)
  • CHANNEL - channel

EnvelopeContentType

Using this enumeration, you can determine the type of content in the message.

enum EnvelopeContentType {
    ADD_PARTICIPANT = 1,
    REMOVE_PARTICIPANT = 2,
    EDIT_CHAT_TITLE = 21,
    EDIT_CHAT_AVATAR = 22,
    CLEAR_CHAT_HISTORY = 23,
    PARTICIPANT_ROLE = 110,
    PLAIN_MESSAGE = 200,
    FORWARDED_MESSAGE = 201,
    ATTACHMENT = 202,
    GEOLOCATION = 203,
    SURVEY = 204,
    VOICE = 205
}

System Messages (Events)

System messages are used for logging and visually accompanying events in the chat history. They are defined by a type < 200 value. You can read more in the relevant section of the documentation.

Message TypeValueDescription
ADD_PARTICIPANT1User added to chat
REMOVE_PARTICIPANT2User removed from chat
EDIT_CHAT_TITLE215.5.3+ Chat name changed
EDIT_CHAT_AVATAR225.5.3+ Chat image changed
CLEAR_CHAT_HISTORY235.5.3+ Chat history deleted

User messages

User messages are generated by clients and transmitted in the general chat message stream. They are identified by a type ≥ 200 value.

Message TypeValueDescription
PLAIN_MESSAGE200Text message
FORWARDED_MESSAGE201Forwarded message
ATTACHMENT202Message with information about the attached file
GEOLOCATION2035.5.3+ A message containing the user's geolocation (can be sent from the mobile client application)
SURVEY204Poll message
ГОЛОС2055.5.6+ Voice message

EnvelopeAuthorTypeEnum

enum EnvelopeAuthorTypeEnum {
    SYSTEM,
    USER,
}

  • SYSTEM - the message is authored by the server. In most cases, this indicates that the message is a system message. The server identifier (TrueConf Server Name) will be used as the author's identifier.

  • USER – the author of the message is a server user. The TrueConf ID of this user will be used as the author's identifier.

ChatParticipantRoleEnum

The enumeration contains a list of possible participant roles in a chat:

enum ChatParticipantRoleEnum {
    OWNER = "owner",
    ADMIN = "admin",
    USER = "user",
    CONF_OWNER = "conf_owner",
    CONF_MODERATOR = "conf_moderator",
    FAVORITES_OWNER = "favorites_owner",
    WRITER = "writer"
}

where:

  • OWNER - chat owner;

  • ADMIN - designated chat administrator;

  • USER - regular chat participant;

  • CONF_OWNER - this role is only present in conference chats and indicates that the user is the conference owner;

  • CONF_MODERATOR - this role is present only in conference chats and indicates that the user is a conference moderator;

  • FAVORITES_OWNER - this role is only available in the "Favorites" chat (Saved messages).

  • WRITER - this role is only present in the channel and indicates that the user can write messages in the channel.

You can find a description of the permissions for each role in a separate section.

TextParseModeEnum

This enumeration is used to specify the mode for processing the text content of messages.

enum TextParseModeEnum {
    TEXT = "text",
    MARKDOWN = "markdown",
    HTML = "html",
}

where:

  • TEXT – the message content will be processed as text. All HTML tags will be escaped (converted to HTML entities).

  • MARKDOWN - the content will be processed as markdown. The list of supported markdown rules is provided below.

  • HTML – the content will be processed as HTML. The list of supported HTML tags is provided below.

ChatActivity

This enumeration is used to convey chatbot activity actions.

The provided text is already in English, and no localization is required.

where:

  • TYPING – "Typing";
  • CHOOSING_STICKER – "Choosing a sticker";
  • RECORDING_AUDIO – "Recording audio message";
  • RECORDING_VIDEO – "Recording a video message";
  • UPLOADING_FILE – "Uploads a file".

FileReadyStateEnum

This enumeration is used to indicate the status of a file on the server.

enum FileReadyStateEnum {
    NOT_AVAILABLE = 0,
    UPLOADING = 1,
    READY = 2
}

where:

  • NOT_AVAILABLE – the file has been removed due to quota restrictions, storage time, etc.;
  • UPLOADING – the file is being uploaded;
  • READY – file uploaded.

MESSAGE_TYPE

There are three types of messages:

enum MESSAGE_TYPE {
  RESERVED = 0,
  REQUEST = 1,
  RESPONSE = 2
}

Only REQUEST and RESPONSE are applicable.

OAUTH_ERROR

Error codes, according to the OAuth 2.0 specification, are presented as ASCII strings from the list specified in the specification. The following error codes are supported:

enum OAUTH_ERROR {
  INVALID_REQUEST = "invalid_request",
  INVALID_CLIENT = "invalid_client",
  INVALID_GRANT = "invalid_grant",
  UNSUPORTED_GRANT_TYPE = "unsupported_grant_type"
}
Error codeValueDescription
invalid_requestBad RequestThe request headers or body are incorrectly formatted. For instance, required fields might be missing or the Content-Type header might be incorrect.
invalid_clientInvalid clientThe value of the client_id field differs from the acceptable one (for example, it is not equal to chat_bot).
invalid_grantInvalid authentication dataThe user with the specified login was not found, or the password is incorrect.
unsupported_grant_typeIncorrect authentication typeThe value of the grant_type field differs from the allowed one (e.g., it is not equal to password).