Справочник API

Труконф02.10.2026Около 16 мин

Справочник API

Envelope

Каждое сообщение, полученное в виде события (уведомление sendMessage), загруженное по идентификатору сообщения (getMessageById) или полученное в истории сообщений чата (getChatHistory), соответствует объекту Envelope.

Поле payload уведомления sendMessage и является объектом Envelope — в примерах ниже показан именно он, без обёртки запроса.

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

ПараметрТипОбяз.Описание
chatChatДаИнформация о чате, в котором находится сообщение. Подробнее см. Chat
chatIdstringНетDeprecated in 5.5.6 Уникальный идентификатор чата, в котором находится сообщение. Используйте поле chat.chatId
messageIdstringДаУникальный идентификатор сообщения
timestampuint64ДаВременная метка отправки сообщения в формате UNIX timestamp с точностью до миллисекунд
replyMessageEnvelopeНетИсходное сообщение, если текущее сообщение является ответом. По структуре аналогично обычному сообщению. Примеры см. в разделе «Примеры Envelope»
replyMessageIdstringНетИдентификатор исходного сообщения, если текущее сообщение является ответом
isEditedbooleanДаБыло ли сообщение когда-либо отредактировано
typeuint32ДаТип сообщения. Подробнее см. EnvelopeContentType
author.idstringДаУникальный идентификатор автора сообщения: TrueConf ID пользователя или имя сервера, с которого получено сообщение. Формат идентификатора определяется полем author.type
author.typeuint32ДаТип автора сообщения. Подробнее см. EnvelopeAuthorTypeEnum
box.idnumberДаПорядковый номер «коробки», в которой находится сообщение. Подробнее — в соответствующем разделе
box.positionstringДаПорядковый номер сообщения в «коробке». Подробнее — в соответствующем разделе
contentAbstractEnvelopeContentДаКонтент сообщения. Состав полей зависит от значения type. Подробнее см. AbstractEnvelopeContent и примеры

Chat

Объект содержит информацию о чате, в котором находится сообщение:

interface Chat {
  chatId: string;
  chatTitle: string | null;
  chatType: ChatTypeEnum;
}
ПараметрТипОбяз.Описание
chatIdstringДаУникальный идентификатор чата
chatTitlestring | nullДаНазвание чата или канала. Для личного чата указывается TrueConf ID собеседника, для чата «Избранное» — null
chatTypeChatTypeEnumДаТип чата. Подробнее см. ChatTypeEnum

EnvelopeAuthor

Объект содержит информацию об авторе сообщения:

ПараметрТипОбяз.Описание
idstringДаУникальный идентификатор автора сообщения. Это может быть либо TrueConf ID пользователя, отправившего сообщение, либо имя сервера, с которого оно пришло. Тип идентификатора зависит от значения поля type
typeuint32ДаТип автора сообщения. Подробнее см. EnvelopeAuthorTypeEnum

EnvelopeBox

Данный объект применяется для сортировки сообщений:

ПараметрТипОбяз.Описание
idnumberДаПорядковый номер «коробки», в которой находится сообщение
positionstringДаПорядковый номер сообщения в «коробке»

О том, как работать с данным объектом, вы можете узнать в соответствующем разделе.

AbstractEnvelopeContent

Базовый интерфейс для содержимого сообщения:

interface AbstractEnvelopeContent {}

Интерфейс не содержит собственных полей. Фактический состав объекта content определяется значением поля Envelope.type из перечисления EnvelopeContentType. Для каждого типа сообщения используется отдельный интерфейс:

Значение Envelope.typeИнтерфейс содержимого
Системные сообщения
ADD_PARTICIPANTAddParticipantContent
REMOVE_PARTICIPANTRemoveParticipantContent
EDIT_CHAT_TITLEEditChatTitleContent
EDIT_CHAT_AVATAREditChatAvatarContent
CLEAR_CHAT_HISTORYClearChatHistoryContent
PARTICIPANT_ROLEParticipantRoleContent
Пользовательские сообщения
PLAIN_MESSAGEPlainMessageContent
FORWARDED_MESSAGEForwardMessageContent
ATTACHMENTAttachmentContent
GEOLOCATIONGeolocationContent
SURVEYSurveyContent
VOICEVoiceContent

AddParticipantContent

Содержимое системного сообщения о добавлении участника в чат (ADD_PARTICIPANT):

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

Пример content:

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

RemoveParticipantContent

Содержимое системного сообщения об удалении участника из чата (REMOVE_PARTICIPANT):

interface RemoveParticipantContent extends AbstractEnvelopeContent {
  userId: string;
}

Пример content:

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

EditChatTitleContent

Содержимое системного сообщения об изменении названия чата (EDIT_CHAT_TITLE):

interface EditChatTitleContent extends AbstractEnvelopeContent {
  title: string;
}

Пример content:

{
  "title": "Новое название чата"
}

EditChatAvatarContent

Содержимое системного сообщения об изменении изображения чата (EDIT_CHAT_AVATAR):

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

Значение null означает, что изображение чата удалено.

Пример content:

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

ClearChatHistoryContent

Содержимое системного сообщения об очистке истории чата (CLEAR_CHAT_HISTORY):

interface ClearChatHistoryContent extends AbstractEnvelopeContent {
  forAll: boolean;
}

Поле forAll указывает, была ли история очищена для всех участников чата.

Пример content:

{
  "forAll": true
}

ParticipantRoleContent

Содержимое системного сообщения об изменении роли участника (PARTICIPANT_ROLE):

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

Пример content:

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

PlainMessageContent

Содержимое текстового сообщения (PLAIN_MESSAGE):

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

Поле buttons содержит ряды inline-кнопок и присутствует только у сообщений с кнопками.

Пример content:

{
  "text": "Новое сообщение",
  "parseMode": "html"
}

ForwardMessageContent

Содержимое пересланного сообщения (FORWARDED_MESSAGE):

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

Интерфейс соответствует объекту Envelope, из которого исключено поле box.

Пример content:

AttachmentContent

Содержимое сообщения с вложенным файлом (ATTACHMENT):

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

Пример content:

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

GeolocationContent

Содержимое сообщения с геопозицией (GEOLOCATION):

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

Пример content:

{
  "latitude": 47.227208,
  "longitude": 39.70418,
  "title": "Ростов-на-Дону"
}

SurveyContent

Содержимое сообщения с опросом (SURVEY):

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

Пример content:

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

VoiceContent

Содержимое голосового сообщения (VOICE):

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

Поле duration содержит длительность голосового сообщения в миллисекундах.

Пример content:

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

Примеры Envelope

Ниже приведены примеры объекта payload (Envelope) для различных типов сообщений. Примеры показаны без обёртки запроса sendMessage.

Текстовое сообщение
{
    "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": "Новое сообщение",
        "parseMode": "html"
    },
    "isEdited": false
}

Перечисления (Enums)

ChatTypeEnum

Перечисление содержит возможные типы чатов.

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

где:

  • UNDEF - неизвестный тип чата
  • P2P - личные сообщения (чат с другим пользователем)
  • GROUP - групповой чат
  • SYSTEM - системный чат
  • FAVORITES - чат "Избранное" (сохраненные сообщения)
  • CHANNEL - канал

EnvelopeContentType

Используя данное перечисление, можно определить тип контента в сообщении.

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
}

Системные сообщения (события)

Системные сообщения используются для логирования и визуального сопровождения событий в истории чата.
Определяются значением type < 200. Подробнее вы можете прочитать в соответствующем разделе документации.

Тип сообщенияЗначениеОписание
ADD_PARTICIPANT1Пользователь добавлен в чат
REMOVE_PARTICIPANT2Пользователь удалён из чата
EDIT_CHAT_TITLE215.5.3+ Изменено название чата
EDIT_CHAT_AVATAR225.5.3+ Изменено изображение чата
CLEAR_CHAT_HISTORY235.5.3+ Удалена история чата

Пользовательские сообщения

Пользовательские сообщения формируются клиентами и передаются в общем потоке сообщений чата.
Определяются значением type ≥ 200.

Тип сообщенияЗначениеОписание
PLAIN_MESSAGE200Текстовое сообщение
FORWARDED_MESSAGE201Пересланное сообщение
ATTACHMENT202Сообщение с информацией о вложенном файле
GEOLOCATION2035.5.3+ Сообщение, содержащее геопозицию пользователя (может быть отправлено с клиентского приложения для мобильных устройств)
SURVEY204Сообщение-опрос
VOICE2055.5.6+ Голосовое сообщение

EnvelopeAuthorTypeEnum

enum EnvelopeAuthorTypeEnum {
    SYSTEM,
    USER,
}

  • SYSTEM – автором сообщения является сервер. В большинстве случаев это будет обозначать то, что сообщение является системны сообщением. В качестве идентификатора автора будет использоваться идентификатор сервера (TrueConf Server Name).

  • USER – автором сообщения является пользователь сервера. В качестве идентификатора автора будет использоваться TrueConf ID этого пользователя.

ChatParticipantRoleEnum

Перечисление содержит список возможных ролей участника чата:

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

где:

  • OWNER - владелец чата;

  • ADMIN - назначенный администратор чата;

  • USER - обычный участник чата;

  • CONF_OWNER - данная роль присутствует только в чатах конференциях, и означает что пользователь является владельцем конференции;

  • CONF_MODERATOR - данная роль присутствует только в чатах конференциях, и означает что пользователь является модератором конференции;

  • FAVORITES_OWNER - данная роль присутствует только в чате "Избранное" (Сохраненные сообщения).

  • WRITER - данная роль присутствует только в канале и означает, что пользователь может писать сообщения в канал.

С описанием прав для каждой роли вы можете ознакомиться в отдельном разделе.

TextParseModeEnum

Данное перечисление используется для указания режима обработки текстового контента сообщений.

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

где:

  • TEXT – контент сообщения будет обработан как текст. Все html-теги будут экранированы (преобразованы в HTML-сущности).

  • MARKDOWN – контент будет обработан как markdown. Список поддерживаемых правил Markdown приведен ниже.

  • HTML – контент будет обработан как HTML. Список поддерживаемых тегов HTML приведен ниже.

ChatActivity

Данное перечисление используется для передачи действий активности чат-бота.

enum ChatActivity {
   TYPING = "typing",
   CHOOSING_STICKER = "choosing_sticker",
   RECORDING_AUDIO = "recording_audio",
   RECORDING_VIDEO = "recording_video",
   UPLOADING_FILE = "uploading_file",
}

где:

  • TYPING – «Печатает»;
  • CHOOSING_STICKER – «Выбирает стикер»;
  • RECORDING_AUDIO – «Записывает аудиосообщение»;
  • RECORDING_VIDEO – «Записывает видеосообщение»;
  • UPLOADING_FILE – «Загружает файл».

FileReadyStateEnum

Данное перечисление используется для указания состояния файла на сервере.

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

где:

  • NOT_AVAILABLE – файл удален из-за ограничений квоты, времени хранения, и т.д.;
  • UPLOADING – файл в процессе загрузки;
  • READY – файл загружен.

MESSAGE_TYPE

Есть три типа сообщений:

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

Применяются только REQUEST и RESPONSE.

OAUTH_ERROR

Коды ошибок, согласно спецификации OAuth 2.0, представлены в виде ASCII-строк из указанного в спецификации перечня. Поддерживаются следующие коды ошибок:

enum OAUTH_ERROR {
  INVALID_REQUEST = "invalid_request",
  INVALID_CLIENT = "invalid_client",
  INVALID_GRANT = "invalid_grant",
  UNSUPORTED_GRANT_TYPE = "unsupported_grant_type"
}
Код ошибкиЗначениеОписание
invalid_requestНеправильный запросЗаголовки или тело запроса имеют неправильный формат. Например, отсутствуют обязательные поля или указан некорректный заголовок Content-Type.
invalid_clientНеправильный клиентЗначение поля client_id отличается от допустимого (например, не равно chat_bot).
invalid_grantНеправильные авторизационные данныеПользователь с указанным логином не найден, либо пароль неверен.
unsupported_grant_typeНеправильный тип авторизацииЗначение поля grant_type отличается от допустимого (например, не равно password).
Последнее обновление: