# API Objects

This section presents the main data structures used for message exchange via the WebSocket protocol.

TrueConf Server API for Chat Bots is built on a messaging model where each entity is described in TypeScript using interfaces (interface) and enumerations (enum). This allows for a strict structure for both client requests and server responses and events.

Interfaces define the format of messages and their payload.
Enums describe the permissible values for message fields (e.g., message types, error codes, etc.).

These definitions form the basis for the serialization and processing of messages on the client and server.

# Enums

# ChatParticipantRoleEnum

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

enum ChatParticipantRoleEnum {
    OWNER = 0,
    ADMIN = 1,
    USER = 2,
    CONF_OWNER = 3,
    CONF_MODERATOR = 4,
    FAVORITES_OWNER = 5,
    WRITER = 6
}

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 review the description of the rights for each role in the dedicated section.

# 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 (opens new window) specification, are presented as ASCII strings from the list specified in the specification (opens new window). 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 Code	Value	Description
`invalid_request`	Invalid Request	The request headers or body are improperly formatted. For instance, required fields are missing or the Content-Type header is incorrect.
`invalid_client`	Invalid Client	The value of the client_id field differs from the allowed value (e.g., it is not equal to `chat_bot`).
`invalid_grant`	Invalid Authorization Data	The user with the specified login is not found, or the password is incorrect.
`unsupported_grant_type`	Invalid Authorization Type	The value of the grant_type field differs from the allowed value (e.g., it is not equal to `password`).

# 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

# EnvelopeTypeEnum

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

enum EnvelopeTypeEnum {
    ADD_PARTICIPANT = 1,
    REMOVE_PARTICIPANT = 2,
    PLAIN_MESSAGE = 200,
    FORWARDED_MESSAGE = 201,
    ATTACHMENT = 202,
    SURVEY = 204,
}

where:

ADD_PARTICIPANT – system message for adding a user to the chat.
REMOVE_PARTICIPANT – system message for removing a user from the chat.
PLAIN_MESSAGE – a regular text message from the server user.
FORWARDED_MESSAGE – forwarded message.
ATTACHMENT – a message containing information about an attachment (file).
SURVEY - poll message

It should be noted that system messages, such as ADD_PARTICIPANT or REMOVE_PARTICIPANT, do not confirm the occurrence of an action, like a participant appearing in the chat. They are used solely for logging purposes. Separate commands and events exist for each action, for instance, adding a new participant to the chat.

To determine if a message is a system message, simply check that the value of the type parameter is less than 200.

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

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

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

# Structures (Interfaces)

# AbstractEnvelopeContent

This object serves as a basic structure for storing message data. Currently, the object does not contain any specific fields, but they may be added in the future:

interface AbstractEnvelopeContent {}

# AddParticipantEnvelopeContent

This object is used as the content of a message with the type EnvelopeTypeEnum.ADD_PARTICIPANT, which is sent when a participant is added to the chat, and has the following interface:

interface AddParticipantEnvelopeContent extends ChatParticipant, AbstractEnvelopeContent {}

The object does not have its own fields and inherits fields from the ChatParticipant object.

Example:

{
  "chatId": "51ffe1b1-1515-498e-8501-233116adf9da",
  "messageId": "2913538a-90e3-4323-9048-b599e4248796",
  "timestamp": 1735330912,
  "author": {
    "id": "trueconf.server.name",
    "type": 0 //0 - server, 1 - user
  },
  "replyMessageId": null, //string if this message is a reply
  "isEdited": false, //true if edited
  "box": {
    "id": 2,
    "position": "" //for sorting undelivered messages
  },
  "type": 1, //1 - ADD_PARTICIPANT
  "content": {
    "userId": "user@video.example.com",
    "role": "owner"
  }
}

# AuthRequest

The authorization request message is as follows:

interface AuthRequest extends RequestMessage<"auth", AuthRequestPayload> {}

The AuthRequest interface inherits fields from the AuthRequestPayload object, essentially serving as the message body, so the description of the fields will be provided there.

# AuthRequestPayload

The message body (payload) for the authorization request object is structured as follows:

interface AuthRequestPayload {
  token: string;
  tokenType: "JWE";
}

Parameter	Type	Required	Default Value	Description
token	string	Yes	auth	Authorization token, obtained via HTTP request
tokenType	string	Yes	JWE	String “JWE”

# SuccessAuthResponse

Response from the server upon successful authorization:

interface SuccessAuthResponse extends ResponseMessage<SuccessAuthResponsePayload> {}

The SuccessAuthResponse interface inherits fields from the SuccessAuthResponsePayload object and essentially serves as the message body. Therefore, the field descriptions will be provided there.

# SuccessAuthResponsePayload

The message body (payload) for a successful authorization object is as follows:

interface SuccessAuthResponsePayload {
  userId: string;
}

Parameter	Type	Required	Description
userId	string	Yes	TrueConf ID of the authorized bot (server user)

# ErrorAuthResponse

Response in case of authorization error:

interface ErrorAuthResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorAuthResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# UnathorizedErrorResponse

Response when attempting to send messages without authorization.

interface UnathorizedErrorResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The UnathorizedErrorResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# CreateGroupChatRequest

Interface for creating a group chat:

interface CreateGroupChatRequest extends RequestMessage<"createGroupChat",CreateGroupChatRequestPayload> {}

The CreateGroupChatRequest interface inherits fields from CreateGroupChatRequestPayload, so the field descriptions are provided there.

# CreateGroupChatRequestPayload

interface CreateGroupChatRequestPayload {
  title: string;
}

Parameter	Type	Required	Description
title	string	Yes	Name of the group chat

# SuccessCreateGroupChatResponse

Response upon successful creation of a group chat:

interface SuccessCreateGroupChatResponse extends ResponseMessage<SuccessCreateGroupChatResponsePayload> {}

The SuccessCreateGroupChatResponse interface inherits fields from SuccessCreateGroupChatResponsePayload, so the field descriptions are provided there.

# SuccessCreateGroupChatResponsePayload

interface SuccessCreateGroupChatResponse extends ResponseMessage<SuccessCreateGroupChatResponsePayload> {}

Parameter	Type	Required	Description
chatId	string	Yes	Chat identifier

# ErrorCreateGroupChatResponse

Response in case of an error creating a group chat:

interface ErrorCreateGroupChatResponse
extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorCreateGroupChatResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# RemoveChatRequest

Outgoing command to delete chat:

interface RemoveChatRequest extends RequestMessage<"removeChat", RemoveChatRequestPayload> {}

The RemoveChatRequest interface inherits fields from RemoveChatRequestPayload, so the field descriptions are provided there.

# RemoveChatRequestPayload

The message body (payload) for the remove chat request is as follows:

interface RemoveChatRequestPayload {
  chatId: string;
}

Parameter	Type	Required	Description
chatId	string	Yes	Chat identifier

# SuccessRemoveChatResponse

Response upon successful chat deletion:

interface SuccessRemoveChatResponse
  extends ResponseMessage<SuccessRemoveChatResponsePayload> {}

The SuccessRemoveChatResponse interface inherits fields from the SuccessRemoveChatResponsePayload object, essentially serving as the message body, so the field descriptions will be provided there.

# SuccessRemoveChatResponsePayload

interface SuccessRemoveChatResponsePayload {
  chatId: string;
}

Parameter	Type	Required	Description
chatId	string	Yes	Chat identifier

# ErrorRemoveChatResponse

interface ErrorRemoveChatResponse extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorRemoveChatResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# AddChatParticipantRequest

Command to add a participant to the chat:

interface AddChatParticipantRequest extends RequestMessage<"addChatParticipant",AddChatParticipantRequestPayload> {}

The AddChatParticipantRequest interface inherits fields from the AddChatParticipantRequestPayload object. Essentially, it serves as the message body, so the field descriptions will be provided there.

# AddChatParticipantRequestPayload

interface AddChatParticipantRequestPayload {
  chatId: string;
  userId: string;
}

Parameter	Type	Required	Description
chatId	string	Yes	Identifier of the chat to which the user is being added
userId	string	Yes	TrueConf ID of the user being added to the chat

# SuccessAddChatParticipantResponse

Response upon successful addition of a participant to the chat:

interface SuccessAddChatParticipantResponse
  extends ResponseMessage<SuccessAddChatParticipantResponsePayload> {}

The SuccessAddChatParticipantResponse interface inherits fields from SuccessAddChatParticipantResponsePayload, so the field descriptions are provided there.

# SuccessAddChatParticipantResponsePayload

The message body (payload) for the successful addition of a participant to the chat object is as follows:

interface SuccessAddChatParticipantResponsePayload {}

# ErrorAddChatParticipantResponse

Response in case of an error when removing a participant from the chat:

interface ErrorAddChatParticipantResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorAddChatParticipantResponse interface inherits fields from GenericErrorResponse, so the description of the fields is provided there.

# CreateP2PChatRequest

Command to create a personal chat (peer-to-peer):

interface CreateP2PChatRequest extends RequestMessage<"createP2PChat",CreateP2PChatRequestPayload> {}

The CreateP2PChatRequest interface inherits fields from the CreateP2PChatRequestPayload object, essentially serving as the message body, so the field descriptions will be provided there.

# CreateP2PChatRequestPayload

interface CreateP2PChatRequestPayload {
  userId : string;
}

Parameter	Type	Required	Description
userId	string	Yes	TrueConf ID of the user with whom we want to create a chat

If the bot has never messaged this user before, a new chat will be created. If the bot has previously sent messages to this user, an existing chat will be returned.

# SuccessCreateP2PChatResponse

Response upon successful creation of a personal (peer-to-peer) chat:

interface SuccessCreateP2PChatResponse
  extends ResponseMessage<SuccessCreateP2PChatResponsePayload> {}

The SuccessCreateP2PChatResponse interface inherits fields from the CreateP2PChatRequestPayload object. Essentially, it serves as the message body, so the field descriptions will be provided there.

# SuccessCreateP2PChatResponsePayload

interface SuccessCreateP2PChatResponsePayload {
  chatId : string;
}

Parameter	Type	Req.	Description
chatId	string	Yes	Identifier of the created chat

# ErrorCreateP2PChatResponse

interface ErrorCreateP2PChatResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorCreateP2PChatResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# RemoveChatParticipantRequest

Command to remove a participant from the chat:

interface RemoveChatParticipantRequest
  extends RequestMessage<"removeChatParticipant",RemoveChatParticipantRequestPayload> {}

The RemoveChatParticipantRequest interface inherits fields from the RemoveChatParticipantRequestPayload object, essentially serving as the message body, so the field descriptions will be provided there.

# RemoveChatParticipantRequestPayload

interface RemoveChatParticipantRequestPayload {
  chatId : string;
  userId : string;
}

Parameter	Type	Required	Description
chatId	string	Yes	Identifier of the chat from which the user is being removed
userId	string	Yes	TrueConf ID of the user being removed

# SuccessRemoveChatParticipantResponse

Response upon successful removal of a participant from the chat:

interface SuccessRemoveChatParticipantResponse
  extends ResponseMessage<SuccessRemoveChatParticipantResponsePayload> {}

The SuccessRemoveChatParticipantResponse interface inherits fields from the SuccessRemoveChatParticipantResponsePayload object, essentially serving as the message body, so the field descriptions will be provided there.

# SuccessRemoveChatParticipantResponsePayload

interface SuccessRemoveChatParticipantResponsePayload {}

# ErrorRemoveChatParticipantResponse

interface ErrorRemoveChatParticipantResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorRemoveChatParticipantResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# HasChatParticipantRequest

Command to check for a participant in the chat:

interface HasChatParticipantRequest extends RequestMessage<"hasChatParticipant",HasChatParticipantRequestPayload> {}

The HasChatParticipantRequest interface inherits fields from the HasChatParticipantRequestPayload object. Essentially, it serves as the message body, so the field descriptions will be provided there.

# HasChatParticipantRequestPayload

interface HasChatParticipantRequestPayload {
  chatId: string;
  userId: string;
}

Parameter	Type	Req.	Description
chatId	string	Yes	The chat identifier where the user's presence is checked
userId	string	Yes	The TrueConf ID of the user being checked

# SuccessHasChatParticipantResponse

Response upon successfully retrieving information about a participant's presence in the chat:

interface SuccessHasChatParticipantResponse
  extends ResponseMessage<SuccessHasChatParticipantResponsePayload> {}

The SuccessHasChatParticipantResponse interface inherits fields from the SuccessHasChatParticipantResponsePayload object, essentially serving as the message body, so the field descriptions will be provided there.

# SuccessHasChatParticipantResponsePayload

interface SuccessHasChatParticipantResponsePayload {
  result: boolean;
}

Parameter	Type	Req.	Description
result	boolean	Yes	A flag indicating the presence of a participant in the chat. If `true` – the participant is present in the chat

# ErrorHasChatParticipantResponse

Response in case of an error when removing a participant from the chat:

interface ErrorHasChatParticipantResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorHasChatParticipantResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# GetChatParticipantListRequest

Command to retrieve the list of chat participants:

interface GetChatParticipantListRequest extends RequestMessage<"getChatParticipants", GetChatParticipantListRequestPayload> {}

The GetChatParticipantListRequest interface inherits fields from the GetChatParticipantListRequestPayload object. Essentially, it serves as the message body, so the field descriptions will be provided there.

# GetChatParticipantListRequestPayload

interface GetChatParticipantListRequestPayload {
  chatId: string;
  pageSize: uint32;
  pageNumber: uint32;
}

Parameter	Type	Required	Description
chatId	string	Yes	Chat identifier
pageSize	uint32	Yes	Number of records with participant information in the response to the request
pageNumber	uint32	Yes	The offset with which the list of participants will be returned. The offset is calculated using the formula `startOffset = pageSize * pageNumber`

# SuccessGetChatParticipantListResponse

Response upon successful retrieval of the participant list in the chat:

interface SuccessGetChatParticipantListResponse
  extends ResponseMessage<SuccessGetChatParticipantListResponsePayload> {}

The SuccessGetChatParticipantListResponse interface inherits fields from the SuccessGetChatParticipantListResponsePayload object, essentially serving as the message body. Therefore, the field descriptions will be provided there.

# SuccessGetChatParticipantListResponsePayload

interface SuccessGetChatParticipantListResponsePayload {
  participants: Array<ChatParticipant>;
}

Parameter	Type	Required	Description
participants	Array<ChatParticipant>	Yes	An array of objects containing information about all chat participants

# ErrorGetChatParticipantListResponse

Response in case of an error retrieving the list of chat participants:

interface ErrorGetChatParticipantListResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorGetChatParticipantListResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# AddChatParticipantIncomingRequest

Incoming message with information about the new chat participant:

interface AddChatParticipantIncomingRequest extends RequestMessage<"addChatParticipant",AddChatParticipantIncomingRequestPayload> {}

The AddChatParticipantIncomingRequest interface inherits fields from the AddChatParticipantIncomingRequestPayload object. Essentially, it serves as the message body, so the description of the fields will be provided there.

# AddChatParticipantIncomingRequestPayload

interface AddChatParticipantIncomingRequestPayload {
  chatId: string;
  userId: string;
  addedBy: MessageAuthor;
  timestamp: uint64;
}

Parameter	Type	Required	Description
chatId	string	Yes	Chat identifier
userId	string	Yes	TrueConf ID of the user added to the chat
addedBy	MessageAuthor	Yes	Who added the participant. See the MessageAuthor object for details
timestamp	uint64	Yes	Timestamp of when the participant was added to the chat in UNIX timestamp format with millisecond precision

# SuccessProceedAddChatParticipantResponse

The response from the client does not contain any payload.

interface SuccessProceedAddChatParticipantResponse extends ResponseMessage<{}> {}

# RemoveChatParticipantIncomingRequest

Incoming message with information about the participant's removal from the chat:

interface RemoveChatParticipantIncomingRequest
  extends RequestMessage<"removeChatParticipant", RemoveChatParticipantIncomingRequestPayload> {}

The RemoveChatParticipantIncomingRequest interface inherits fields from the RemoveChatParticipantIncomingRequestPayload object. Essentially, it serves as the message body, so the field descriptions will be provided there.

# RemoveChatParticipantIncomingRequestPayload

interface RemoveChatParticipantIncomingRequestPayload {
  chatId: string;
  userId: string;
  removedBy: MessageAuthor;
  timestamp: uint64;
}

Parameter	Type	Required	Description
chatId	string	Yes	Chat identifier
userId	string	Yes	TrueConf ID of the user removed from the chat
addedBy	MessageAuthor	Yes	Who removed the participant. See the MessageAuthor object for details
timestamp	uint64	Yes	Timestamp of when the participant was removed from the chat in UNIX timestamp format with millisecond precision

# SuccessProceedRemoveChatParticipantResponse

The response from the client does not contain any payload.

interface SuccessProceedRemoveChatParticipantResponse
  extends ResponseMessage<{}> {}

# SendChatMessageRequest

Command to send a message:

interface SendChatMessageRequest extends RequestMessage<"sendMessage", SendChatMessageRequestPayload> {}

The SendChatMessageRequest interface inherits fields from the SendChatMessageRequestPayload object, essentially serving as the message body, so the field descriptions will be provided there.

# SendChatMessageRequestPayload

interface SendChatMessageRequestPayload {
  chatId: string;
  replyMessageId?: string;
  content: TextMessageContent;
}

Parameter	Type	Required	Description
chatId	string	Yes	Chat identifier
replyMessageId	string	No	If replying to a message, this field should contain the ID of that message. Optional field
content	TextMessageContent	Yes	Message data

# TextMessageContent

interface TextMessageContent {
  text: string;
  parseMode: TextParseModeEnum;
}

Parameter	Type	Required	Description
text	string	Yes	Message text
parseMode	TextParseModeEnum	Yes	Message text parsing mode

# SuccessSendChatMessageResponse

Response in case of successful message delivery:

interface SuccessSendChatMessageResponse extends ResponseMessage<SuccessSendChatMessageResponsePayload> {}

The SuccessSendChatMessageResponse interface inherits fields from the SuccessSendChatMessageResponsePayload object, essentially serving as the message body, so the field descriptions will be provided there.

# SuccessSendChatMessageResponsePayload

interface SuccessSendChatMessageResponsePayload {
  chatId: string;
  messageId: string;
  timestamp: uint64;
}

Parameter	Type	Required	Description
chatId	string	Yes	The identifier of the chat where the message was sent
messageId	string	Yes	The identifier of the message. This identifier can be used later to modify, forward, or delete the message
timestamp	uint64	Yes	The timestamp of when the message was sent, in UNIX timestamp format, with millisecond precision

# ErrorSendChatMessageResponse

Response in case of a chat message sending error:

interface ErrorSendChatMessageResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorSendChatMessageResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# EditChatMessageRequest

Command to edit the message:

interface EditChatMessageRequest extends RequestMessage<"editMessage",EditChatMessageRequestPayload> {}

The EditChatMessageRequest interface inherits fields from the EditChatMessageRequestPayload object, as it essentially serves as the message body. Therefore, the field descriptions will be provided there.

# EditChatMessageRequestPayload

interface EditChatMessageRequestPayload {
  messageId: string;
  content: TextMessageContent;
}

Parameter	Type	Required	Description
chatId	string	Yes	Chat identifier
content	TextMessageContent	Yes	Message data

# SuccessEditChatMessageResponse

Response in case of a successful message update:

interface SuccessEditChatMessageResponse
  extends ResponseMessage<SuccessEditChatMessageResponsePayload> {}

The SuccessEditChatMessageResponse interface inherits fields from the SuccessSendChatMessageResponsePayload object, as it essentially serves as the message body. Therefore, the field descriptions will be provided there.

# SuccessEditChatMessageResponsePayload

interface SuccessSendChatMessageResponsePayload {
  timestamp: uint64;
}

Parameter	Type	Req.	Description
timestamp	uint64	Yes	Message editing timestamp in UNIX timestamp format with millisecond precision

# ErrorEditChatMessageResponse

Response in case of message modification error:

interface ErrorEditChatMessageResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The interface ErrorEditChatMessageResponse inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# ForwardChatMessageRequest

Command to forward a message:

interface ForwardChatMessageRequest
  extends RequestMessage<"forwardMessage", ForwardChatMessageRequestPayload> {}

The ForwardChatMessageRequest interface inherits fields from the ForwardChatMessageRequestPayload object, essentially serving as the message body. Therefore, the field descriptions will be provided there.

# ForwardChatMessageRequestPayload

interface ForwardChatMessageRequestPayload {  
  chatId: string;  
  messageId: string;
}

Parameter	Type	Required	Description
chatId	string	Yes	Identifier of the chat to which you will forward the message
messageId	string	Yes	Identifier of the message being forwarded

# SuccessForwardChatMessageResponse

Response in case of successful message forwarding:

interface SuccessForwardChatMessageResponse
  extends ResponseMessage<SuccessForwardChatMessageResponsePayload> {}

The SuccessForwardChatMessageResponse interface inherits fields from the SuccessForwardChatMessageResponsePayload object; essentially, it constitutes the message body, so the field descriptions will be provided there.

# SuccessForwardChatMessageResponsePayload

interface SuccessForwardChatMessageResponsePayload {
  chatId: string;
  messageId: string;
  timestamp: uint64;
}

Parameter	Type	Required	Description
chatId	string	Yes	The unique identifier of the chat to which the message was forwarded
messageId	string	Yes	The unique identifier of the new message containing your forwarded message
timestamp	uint64	Yes	The timestamp of the message forwarding in UNIX timestamp format accurate to milliseconds

# ErrorForwardChatMessageResponse

Response in case of message forwarding error:

interface ErrorForwardChatMessageResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorForwardChatMessageResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# GetChatMessageRequest

Command to receive a message:

interface GetChatMessageRequest
  extends RequestMessage<"getMessageById", GetChatMessageRequestPayload> {}

The GetChatMessageRequest interface inherits fields from the GetChatMessageRequestPayload object. Essentially, it serves as the message body, so the description of the fields will be provided there.

# GetChatMessageRequestPayload

interface GetChatMessageRequestPayload {
  messageId: string;
}

Parameter	Type	Required	Description
messageId	string	Yes	Identifier of the requested message

# SuccessGetChatMessageResponse

Response upon successful receipt of the message:

interface SuccessGetChatMessageResponse
  extends ResponseMessage<SuccessGetChatMessageResponsePayload> {}

The SuccessGetChatMessageResponse interface inherits fields from the SuccessGetChatMessageResponsePayload object, as it essentially serves as the message body. Therefore, the field descriptions will be provided there.

# SuccessGetChatMessageResponsePayload

interface SuccessGetChatMessageResponsePayload extends Envelope {}

The SuccessGetChatMessageResponsePayload object does not contain its own fields and is inherited from the Envelope object.

# ErrorGetChatMessageResponse

Response in case of an error retrieving the message:

interface ErrorGetChatMessageResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorGetChatMessageResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# GetChatHistoryRequest

Command to retrieve chat history:

interface GetChatHistoryRequest
  extends RequestMessage<"getChatHistory", GetChatHistoryRequestPayload> {}

The GetChatHistoryRequest interface inherits fields from the GetChatHistoryRequestPayload object, essentially serving as the message body, so the description of the fields will be provided there.

# GetChatHistoryRequestPayload

interface GetChatHistoryRequestPayload {
  chatId: string;
  count: uint32;
  fromMessageId?: string;
}

Parameter	Type	Req.	Description
chatId	string	Yes	The chat ID for which the message history is requested
count	uint32	Yes	The number of messages returned in the response
fromMessageId	string	No	The chat message ID from which the chat history will be returned

Messages are returned in order from the newest message (or from fromMessageId) to the oldest based on the date they were added to the chat.

# SuccessGetChatHistoryResponse

interface SuccessGetChatHistoryResponse
  extends ResponseMessage<SuccessGetChatHistoryResponsePayload> {}

The SuccessGetChatHistoryResponse interface inherits fields from the SuccessGetChatHistoryResponsePayload object, essentially serving as the message body, so the field descriptions will be provided there.

# SuccessGetChatHistoryResponsePayload

Response upon successful retrieval of chat history:

interface SuccessGetChatMessageResponsePayload {
  chatId: string;
  count: uint32;
  messages: Array<Envelope>;
}

Parameter	Type	Required	Description
chatId	string	Yes	The chat identifier for which the message history was requested
count	uint32	Yes	The number of received messages
messages	Array<Envelope>	No	An array with Envelope objects

# ErrorGetChatHistoryResponse

Error response when retrieving chat history:

interface ErrorGetChatHistoryResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorGetChatHistoryResponse interface inherits fields from GenericErrorResponse, therefore the description of the fields is provided there.

# RemoveChatMessageRequest

Command to delete a message:

interface RemoveChatMessageRequest extends RequestMessage<"removeMessage", RemoveChatMessageRequestPayload> {}

The interface RemoveChatMessageRequest inherits fields from the RemoveChatMessageRequestPayload object, essentially serving as the message body, so the field descriptions will be provided there.

# RemoveChatMessageRequestPayload

interface RemoveChatMessageRequestPayload {
  messageId: string;
  forAll: boolean;
}

Parameter	Type	Required	Description
messageId	string	Yes	Identifier of the message to be deleted
forAll	boolean	Yes	Message deletion flag. If set to `true`, the message will be deleted for all users

# SuccessRemoveChatMessageResponse

Response upon successful message deletion:

interface SuccessRemoveChatMessageResponse
  extends ResponseMessage<SuccessRemoveChatMessageResponsePayload> {}

The SuccessRemoveChatMessageResponse interface inherits fields from the SuccessRemoveChatMessageResponsePayload object, essentially serving as the message body, so the field descriptions will be provided there.

# SuccessRemoveChatMessageResponsePayload

interface SuccessRemoveChatMessageResponsePayload {}

# ErrorRemoveChatMessageResponse

Response in case of message deletion error:

interface ErrorRemoveChatMessageResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorRemoveChatMessageResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# UploadFileRequest

Command to create a file upload task:

interface UploadFileRequest
  extends RequestMessage<"uploadFile", UploadFileRequestPayload> {}

The UploadFileRequest interface inherits fields from the UploadFileRequestPayload object. Essentially, it serves as the body of the message, so the field descriptions will be provided there.

# UploadFileRequestPayload

interface UploadFileRequestPayload {
  fileName: string;
  fileSize: number;
  mimeType: string;
}

Parameter	Type	Required	Description
fileName	string	Yes	File name
fileSize	number	Yes	File size
mimeType	string	Yes	File MIME type

# SuccessUploadFileResponse

Response when a file upload task is successfully created:

interface SuccessUploadFileResponse
  extends ResponseMessage<SuccessUploadFileResponsePayload> {}

The SuccessUploadFileResponse interface inherits fields from the SuccessUploadFileResponsePayload object, essentially serving as the message body. Therefore, the field descriptions will be provided there.

# SuccessUploadFileResponsePayload

interface SuccessUploadFileResponsePayload {
  uploadTaskId: string;
}

Parameter	Type	Required	Description
uploadTaskId	string	Yes	File upload task identifier

# ErrorUploadFileResponse

Response in case of an error creating a file upload task:

interface ErrorUploadFileResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorUploadFileResponse interface inherits fields from GenericErrorResponse, so the description of the fields can be found there.

# SendFileRequest

command for sending a file in a message:

interface SendFileRequest
  extends RequestMessage<"sendFile", SendFileRequestPayload> {}

The SendFileRequest interface inherits fields from the SendFileRequestPayload object. Essentially, it is the body of the message, so the field descriptions will be provided there.

# SendFileRequestPayload

interface SendFileRequestPayload {
  chatId: string;
  content: {
    fileId: string,
  };
}

Parameter	Type	Required	Description
chatId	string	Yes	Chat identifier for sending a message
fileId	string	Yes	File identifier obtained in the HTTP request response

# SuccessSendFileResponse

Response in case of successful file upload:

interface SuccessSendFileResponse
  extends ResponseMessage<SuccessSendFileResponsePayload> {}

The SuccessSendFileResponse interface inherits fields from the SuccessSendFileResponsePayload object, essentially serving as the message body, so the field descriptions will be provided there.

# SuccessSendFileResponsePayload

interface SuccessSendFileResponsePayload {
  chatId: string;
  timestamp: number;
  messageId: string;
}

Parameter	Type	Required	Description
chatId	string	Yes	Chat identifier
timestamp	number	Yes	Message send time
messageId	string	Yes	Message identifier

# ErrorSendFileResponse

interface ErrorSendFileResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorSendFileResponse interface inherits fields from GenericErrorResponse, so the field descriptions can be found there.

# FileMessageContent

Receiving file transfer notification:

interface FileMessageContent {
  name: string;
  mimeType: string;
  size: number;
  fileId: string;
}

Parameter	Type	Required	Description
name	string	Yes	File name
size	number	Yes	File size
mimeType	string	Yes	MIME type of the file
fileId	string	Yes	File ID on the server

# GetFileInfoRequest

Command to obtain file information and download it:

interface GetFileInfoRequest
  extends RequestMessage<"getFileInfo", GetFileInfoRequestPayload> {}

The GetFileInfoRequest interface inherits fields from the GetFileInfoRequestPayload object, as it essentially serves as the message body. Therefore, the field descriptions will be provided there.

# GetFileInfoRequestPayload

interface GetFileInfoRequestPayload {  
  fileId: string;
}

Parameter	Type	Required	Description
fileId	string	Yes	File identifier obtained from the message sending event

# SuccessGetFileInfoResponse

Response when the file is found:

interface SuccessGetFileInfoResponse
  extends ResponseMessage<SuccessGetFileInfoResponsePayload> {}

The SuccessGetFileInfoResponse interface inherits fields from the SuccessGetFileInfoResponsePayload object, essentially serving as the message body, so the field descriptions will be provided there.

# SuccessGetFileInfoResponsePayload

interface SuccessGetFileInfoResponsePayload {
    name: string,
    size: number,
    mimeType: string,
    downloadUrl: string | null,
    readyState: FileReadyStateEnum,
    infoHash: string,
    previews: null | Array<{
      name: string,
      mimeType: string,
      size: number,
      downloadUrl: string,
    }>,
  }

Parameter	Type	Req.	Description
name	string	Yes	File name
size	number	Yes	File size in bytes
mimeType	string	Yes	File MIME type
downloadUrl	string	Yes	URL for file download
readyState	FileReadyStateEnum	Yes	File status on server
infoHash	string	Yes	File identifier on server
previews	Array	Yes	Array of file previews

To download the file, you need to send a GET request to the address specified in downloadUrl.

# ErrorGetFileInfoResponse

Response if the file is not found on the server:

interface ErrorGetFileInfoResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorGetFileInfoResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# SubscribeFileProgressRequest

Command to subscribe to file upload progress on the server:

interface SubscribeFileProgressRequest extends RequestMessage<"subscribeFileProgress", SubscribeFileProgressRequestPayload> {}

The SubscribeFileProgressRequest interface inherits fields from the SubscribeFileProgressRequestPayload object, essentially forming the message body. Therefore, the field descriptions will be provided there.

# SubscribeFileProgressRequestPayload

interface SubscribeFileProgressRequestPayload {
  fileId: string;
}

Parameter	Type	Required	Description
fileId	string	Yes	File identifier on the server

# SuccessSubscribeFileProgressResponse

Response in case of a successful subscription:

interface SuccessSubscribeFileProgressResponse
  extends ResponseMessage<SuccessSubscribeFileProgressResponsePayload> {}

The SuccessSubscribeFileProgressResponse interface inherits fields from the SuccessSubscribeFileProgressResponsePayload object, essentially serving as the message body. Therefore, the field descriptions will be provided there.

# SuccessSubscribeFileProgressResponsePayload

interface SuccessSubscribeFileProgressResponsePayload {
  result: boolean;
}

Parameter	Type	Req.	Description
result	boolean	Yes	Whether the subscription to download was successful

# ErrorSubscribeFileProgressResponse

Response in case of a failed file upload subscription:

interface ErrorSubscribeFileProgressResponse extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorSubscribeFileProgressResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# UploadProgressContent

File upload event message interface:

interface UploadProgressContent {
  fileId: string;
  progress: number;
}

Parameter	Type	Required	Description
fileId	string	Yes	File identifier on the server
progress	number	Yes	Number of bytes uploaded to the server

# UnsubscribeFileProgressRequest

Command to unsubscribe from receiving file upload events to the server.

interface UnsubscribeFileProgressRequest extends RequestMessage<"unsubscribeFileProgress", UnsubscribeFileProgressRequestPayload> {}

The UnsubscribeFileProgressRequest interface inherits fields from the UnsubscribeFileProgressRequestPayload object, essentially serving as the message body, so the field descriptions will be provided there.

# UnsubscribeFileProgressRequestPayload

interface UnsubscribeFileProgressRequestPayload {
  fileId: string;
}

Parameter	Type	Required	Description
id	string	Yes	File identifier on the server

# SuccessUnsubscribeFileProgressResponse

Response upon successful unsubscription from receiving file upload events to the server:

interface SuccessUnsubscribeFileProgressResponse extends ResponseMessage<SuccessUnsubscribeFileProgressResponsePayload> {}

The SuccessUnsubscribeFileProgressResponse interface inherits fields from the SuccessUnsubscribeFileProgressResponsePayload object, essentially serving as the body of the message. Therefore, the field descriptions will be provided there.

# SuccessUnsubscribeFileProgressResponsePayload

interface SuccessUnsubscribeFileProgressResponsePayload {
  result: boolean;
}

Parameter	Type	Required	Description
result	boolean	Yes	Indicates if unsubscribing from receiving events was successful

# ErrorUnsubscribeFileProgressResponse

Response in case of an error when unsubscribing from receiving file upload events on the server:

interface ErrorUnsubscribeFileProgressResponse
  extends GenericErrorResponse<GenericErrorPayload<uint32>> {}

The ErrorUnubscribeFileProgressResponse interface inherits fields from GenericErrorResponse, so the field descriptions are provided there.

# Envelope

Each message received as an event, loaded by message ID, or retrieved from the chat message history conforms to the Envelope interface:

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

Parameter	Type	Required	Description
messageId	string	Yes	Unique identifier of the message
chatId	string	Yes	Unique identifier of the chat containing the message
timestamp	uint64	Yes	Message sending timestamp in UNIX timestamp format with millisecond precision
replyMessageId	string	No	If it's a reply to a message, contains the identifier of that message
isEdited	boolean	Yes	Whether the message has ever been edited
type	EnvelopeTypeEnum	Yes	Type of message
author	EnvelopeAuthor	Yes	Message author
box	EnvelopeBox	Yes	Sequential numbers of the message
content	AbstractEnvelopeContent	Yes	Message content. It can be text, a file, or another type of data, depending on the `type` field.

# EnvelopeAuthor

The object contains information about the message author.

interface EnvelopeAuthor {
  id: string;
  type: EnvelopeAuthorTypeEnum;
}

Parameter	Type	Required	Description
id	string	Yes	A unique identifier for the message author. This can be either the TrueConf ID of the user who sent the message or the server name from which it was sent. The type of identifier depends on the value of the `type` field.
type	EnvelopeAuthorTypeEnum	Yes	Type of message author

# EnvelopeBox

This object is used for sorting messages and has the following interface:

interface EnvelopeBox {
  id: number;
  position: string;
}

Parameter	Type	Req.	Description
id	number	Yes	Sequential number of the "box" containing the message
position	string	Yes	Sequential number of the message in the "box"

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

# GenericErrorResponse

For most requests, in case of an error, a response will be sent in the following format:

interface GenericErrorResponse<T extends GenericErrorPayload> extends ResponseMessage<T> { }

The GenericErrorResponse interface inherits fields from GenericErrorPayload and ResponseMessage, so refer to their field descriptions there.

# GenericErrorPayload

interface GenericErrorPayload<ErrorCodeEnum extends uint32> {
    errorCode: ErrorCodeEnum ;
}

Parameter	Type	Required	Description
errorCode	uint32	Yes	Error code

# Message

Basic message format. Any message (both incoming and outgoing) will have the following fields:

interface Message {
  type: MESSAGE_TYPE;
  id: uint64;
}

Parameter	Type	Required	Description
type	enum MESSAGE_TYPE	Yes	Message type from the `MESSAGE_TYPE` enumeration
id	uint32	Yes	Unique message identifier, represented as an incrementing number (in some protocols, such as TCP, this number is called a sequence id). The identifier can be identical for outgoing and incoming messages. The identifier value may increment by more than one at a time. See details below.

# RequestMessage

A message of type Request.

interface RequestMessage<Method extends string, Payload extends JSONObject> extends Message {  
  type: MESSAGE_TYPE.REQUEST;  
  method: Method;  
  payload: Payload;
}

Parameter	Type	Required	Description
type	MESSAGE_TYPE.REQUEST	Yes	Message type (default is `1`).
method	string	Yes	Type of command being sent
payload	JSONObject	No	Any JSON-formatted object applicable for this *method. This field may be omitted if no additional parameters are specified for the method*.

Example:

{
  "type": 1,
  "id": 1,
  "method": "ping",
  "payload": {
    "data": "Hello, World!",
    "some_additional_data": {
      "internal_additional_field_124": [true, false, 1234]
    }
  }
}

# ResponseMessage

Message with the type Response.

interface ResponseMessage<Payload extends JSONObject> extends Message {
  type: MESSAGE_TYPE.RESPONSE;
  payload: Payload;
}

Parameter	Type	Req.	Description
type	MESSAGE_TYPE.RESPONSE	Yes	Message type (default is `2`).
payload	JSONObject	No	Any JSON-formatted object applicable as payload data for the request response. This field may be omitted if the response does not contain any payload data.

Example:

{
  "type": 2,
  "id": 123456,
  "payload": {
    "data": "Hello, World!"
  }
}

# JSONObject

The JSONObject object passed in the payload should match the following type:

type JSONValue = null | string | number | boolean | JSONArray | JSONObject;
interface JSONArray extends Array<JSONValue> {}

type JSONObject = {
    [key: string] ?: JSONValue;
    [key: number] ?: JSONValue;
}

# OAuthTokenRequest

Request structure for obtaining an identification token.

interface OAuthTokenRequest {
  client_id: string;
  grant_type: string;
  username: string;
  password: string;
}

Parameter	Type	Required	Default	Description
client_id	string	Yes	"chat_bot"	Constant string "chat_bot"
grant_type	string	Yes	"password"	Constant string "password"
username	string	Yes		User login (see below)
password	string	Yes		User password

TrueConf server user login. The following formats are supported:

Simple login — the username of the current server user, for example: vasya or alex_smith
With the TrueConf server specified — for example: vasya@server1.local
With LDAP domain specification — for example: web-department.mycompany\\alex_smith
With server and LDAP domain specified — for example: web-department.mycompany\\alex_smith@server1.local

# OAuthTokenSuccessResponse

Response structure upon successful authorization when receiving an access token.

interface OAuthTokenSuccessResponse {
  access_token: string;
  token_type: string;
  expires_in: uint32;
}

Parameter	Type	Required	Default	Description
access_token	string	Yes		The identification token used for WebSocket connection authorization.
token_type	string	Yes	"JWE"	Constant string "JWE"
expires_in	uint32	Yes		The token's lifespan in seconds from the moment it is issued is one year. After this period, re-authorization is required.

# OAuthTokenErrorResponse

Response structure in case of an authorization error when retrieving the access token.

interface OAuthTokenErrorResponse {
  error: "OAUTH_ERROR";
  error_description: string;
}

Parameter	Type	Required	Description
error	enum OAUTH_ERROR	Yes	A value from the OAUTH_ERROR enumeration
error_description	string	Yes	Human-readable text of the authorization error

# RemoveParticipantEnvelopeContent

This object is used as the content of a message with the type EnvelopeTypeEnum.REMOVE_PARTICIPANT, which is sent when a participant is removed from the chat, and has the following interface:

interface RemoveParticipantEnvelopeContent extends AbstractEnvelopeContent {
  userId: string;
}

Parameter	Type	Required	Description
userId	string	Yes	TrueConf ID of the user removed from the chat.

# PlainMessageEnvelopeContent

This object is used as the content of a message with the type EnvelopeTypeEnum.PLAIN_MESSAGE and has the following interface:

interface RemoveParticipantEnvelopeContent extends AbstractEnvelopeContent {
  text: string;
  parseMode: TextParseModeEnum;
}

Parameter	Type	Required	Description
text	string	Yes	Message text
parseMode	TextParseModeEnum	Yes	Message text parsing mode. See the enumeration description for details

Example:

{
  "chatId": "51ffe1b1-1515-498e-8501-233116adf9da",
  "messageId": "fdfa8fd6-b4f5-4ecc-8c7e-11e420105056",
  "timestamp": 1735330910,
  "author": {
    "id": "user@video.example.com",
    "type": 1 //0 - server, 1 - user
  },
  "replyMessageId": null, //string if this message is a reply
  "isEdited": false, //true if edited
  "box": {
    "id": 1,
    "position": "" //for sorting undelivered messages
  },
  "type": 200, //200 - PLAIN_MESSAGE
  "content": {
    "text": "Hello, chat bot!",
    "parseMode": "text"
  }
}

# ForwardMessageEnvelopeContent

This object is used as message content with the type EnvelopeTypeEnum.FORWARD_MESSAGE and has the following interface:

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

A distinctive feature of the interface for the object with the content of a forwarded message is that it contains the forwarded message object (Envelope) as its content, except for the data in the "box" field.

Theoretically, the chain of nested forwarded messages can be infinite, but currently, the nesting is limited to one message (Envelope).

Example:

{
  "chatId": "51ffe1b1-1515-498e-8501-233116adf9da",
  "messageId": "552a5a7c-02fd-4c30-a4f1-60c9cfff649c",
  "timestamp": 1735330914,
  "author": {
    "id": "user@video.example.com",
    "type": 1 //0 - server, 1 - user
  },
  "replyMessageId": null, //string if this message is reply
  "isEdited": false, //true if edited
  "box": {
    "id": 5677289,
    "position": "COFFEE" //for sorting undelivered messages
  },
  "type": 201, //201 - FORWARD_MESSAGE
  "content": {
    "chatId": "51ffe1b1-1515-498e-8501-233116adf9da",
    "messageId": "fdfa8fd6-b4f5-4ecc-8c7e-11e420105056",
    "timestamp": 1735330910,
    "author": {
      "id": "user@video.example.com",
      "type": 1 //0 - server, 1 - user
    },
    "replyMessageId": null, //string if this message is reply
    "isEdited": false, //true if edited
    "type": 200, //200 - PLAIN_MESSAGE
    "content": {
      "text": "Hello, chat bot!",
      "parseMode": "text"
    }
  }
}

# AttachmentMessageEnvelopeContent

This object is used as the content of a message with the type EnvelopeTypeEnum.ATTACHMENT and has the following interface:

interface AttachmentMessageEnvelopeContent extends AbstractEnvelopeContent {
  name: string;
  mimeType: string;
  size: number;
  id: string;
}

Parameter	Type	Required	Default	Description
name	string	Yes		The name of the file on the sender's side. For example, "photo.jpg"
mimeType	string	Yes	""	The MIME type of the file being sent. It could be a string such as "image/jpeg" or an empty string if the attachment type could not be determined
size	uint64	Yes		The file size in bytes
id	string	Yes	""	A unique identifier for the file to enable downloading. For more details, see the section on working with attachments

# ChatParticipant

This object is used to store information about a chat participant.

interface ChatParticipant {
  userId: string;
  role: ChatParticipantRoleEnum;
}

Parameter	Type	Req.	Description
userId	string	Yes	User's TrueConf ID added to the chat
role	ChatParticipantRoleEnum	Yes	User's role in the chat (see ChatParticipantRoleEnum enumeration)

← Server Notifications