API Objects

TrueConfAbout 42 min

API Objects

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

TrueConf Server API for Chat Bots It is built on a message exchange 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.

Enumerations (Enums)

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.

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

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,
}

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+ Updated chat image
CLEAR_CHAT_HISTORY235.5.3+ Chat history removed

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

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 message content of type EnvelopeContentType.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 field descriptions will be provided there.

AuthRequestPayload

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

interface AuthRequestPayload {
  token: string;
  tokenType: "JWT";
  receiveUnread?: boolean;
}
ParameterTypeMandatoryDefault valueDescription
tokenstringYesauthAuthorization token obtained via an HTTP request
tokenTypestringYesJWTString "JWT"
receiveUnreadbooleanNofalseThe parameter responsible for retrieving unread messages when the bot was offline. Messages are returned one by one, from oldest to newest. The maximum number of messages that can be retrieved is 1000.

SuccessAuthResponse

Response from the server upon successful authorization:

interface SuccessAuthResponse extends ResponseMessage<SuccessAuthResponsePayload> {}

The SuccessAuthResponse interface inherits fields from the SuccessAuthResponsePayload object, essentially serving as the message body; therefore, the field descriptions will be provided there.

SuccessAuthResponsePayload

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

interface SuccessAuthResponsePayload {
  userId: string;
}
ParameterTypeMandatoryDescription
userIdstringYesTrueConf 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 description of the fields is 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 description of the fields is provided there.

CreateGroupChatRequest

Interface for creating a group chat:

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

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

CreateGroupChatRequestPayload

interface CreateGroupChatRequestPayload {
  title: string;
}
ParameterTypeMandatoryDescription
titlestringYesGroup Chat Name

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> {}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID

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 description of the fields is provided there.

RemoveChatRequestPayload

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

interface RemoveChatRequestPayload {
  chatId: string;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID

SuccessRemoveChatResponse

Response upon successful chat deletion:

interface SuccessRemoveChatResponse
  extends ResponseMessage<SuccessRemoveChatResponsePayload> {}

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

SuccessRemoveChatResponsePayload

interface SuccessRemoveChatResponsePayload {
  chatId: string;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID

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 serving as the message body, so the field descriptions will be provided there.

AddChatParticipantRequestPayload

interface AddChatParticipantRequestPayload {
  chatId: string;
  userId: string;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID to which the user is added
userIdstringYesTrueConf 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, therefore the description of the fields is provided there.

SuccessAddChatParticipantResponsePayload

The message body (payload) for a successful adding 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 field descriptions are 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, it serves as the message body, so the description of the fields will be provided there.

CreateP2PChatRequestPayload

interface CreateP2PChatRequestPayload {
  userId : string;
}
ParameterTypeMandatoryDescription
userIdstringYesTrueConf ID of the user with whom we want to start 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 serving as the message body, so the field descriptions will be provided there.

SuccessCreateP2PChatResponsePayload

interface SuccessCreateP2PChatResponsePayload {
  chatId : string;
}
ParameterTypeMandatoryDescription
chatIdstringYesID 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 interface RemoveChatParticipantRequest inherits fields from the RemoveChatParticipantRequestPayload object, essentially serving as the message body. Therefore, the field descriptions will be provided there.

RemoveChatParticipantRequestPayload

interface RemoveChatParticipantRequestPayload {
  chatId : string;
  userId : string;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID from which the user is being removed
userIdstringYesTrueConf ID of the user to be deleted

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 serving as the message body, so the field descriptions will be provided there.

HasChatParticipantRequestPayload

interface HasChatParticipantRequestPayload {
  chatId: string;
  userId: string;
}
ParameterTypeMandatoryDescription
chatIdstringYesThe chat ID in which the user's presence is verified.
userIdstringYesTrueConf ID of the user being verified

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;
}
ParameterTypeMandatoryDescription
resultbooleanYesFlag indicating participant presence 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 description of the fields will be provided there.

GetChatParticipantListRequestPayload

interface GetChatParticipantListRequestPayload {
  chatId: string;
  pageSize: uint32;
  pageNumber: uint32;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID
pageSizeuint32YesNumber of records with information about chat participants in the response to the request
pageNumberuint32YesThe offset with which the participant list 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, so the field descriptions will be provided there.

SuccessGetChatParticipantListResponsePayload

interface SuccessGetChatParticipantListResponsePayload {
  participants: Array<ChatParticipant>;
}
ParameterTypeMandatoryDescription
participantsArrayYesArray 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 serving as the message body, and therefore, the field descriptions will be provided there.

AddChatParticipantIncomingRequestPayload

interface AddChatParticipantIncomingRequestPayload {
  chatId: string;
  userId: string;
  addedBy: MessageAuthor;
  timestamp: uint64;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID
userIdstringYesTrueConf ID of the user added to the chat
addedByMessageAuthorYesWho added the participant. For more details, see the MessageAuthor object.
timestampuint64YesTimestamp of adding a participant 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 serving as the message body, so the field descriptions will be provided there.

RemoveChatParticipantIncomingRequestPayload

interface RemoveChatParticipantIncomingRequestPayload {
  chatId: string;
  userId: string;
  removedBy: MessageAuthor;
  timestamp: uint64;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID
userIdstringYesTrueConf ID of the user removed from the chat
addedByMessageAuthorYesWho removed the participant. For more details, see the MessageAuthor object.
timestampuint64YesTimestamp of a participant's removal 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 making it the message body, so the field descriptions will be provided there.

SendChatMessageRequestPayload

interface SendChatMessageRequestPayload {
  chatId: string;
  replyMessageId?: string;
  content: TextMessageContent;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID
replyMessageIdstringNoIf we are replying to a message, the field should contain the identifier of that message. This field is optional.
contentTextMessageContentYesMessage data

TextMessageContent

interface TextMessageContent {
  text: string;
  parseMode: TextParseModeEnum;
}
ParameterTypeMandatoryDescription
textstringYesMessage text
parseModeTextParseModeEnumYesMessage text processing 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 description of the fields will be provided there.

SuccessSendChatMessageResponsePayload

interface SuccessSendChatMessageResponsePayload {
  chatId: string;
  messageId: string;
  timestamp: uint64;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID where the message was sent
messageIdstringYesMessage ID. This identifier can be used later to modify, forward, or delete the message.
timestampuint64YesTimestamp of the message 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, essentially serving as the message body, so the description of the fields will be provided there.

EditChatMessageRequestPayload

interface EditChatMessageRequestPayload {
  messageId: string;
  content: TextMessageContent;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID
contentTextMessageContentYesMessage data

SuccessEditChatMessageResponse

Response in case of a successful message update:

interface SuccessEditChatMessageResponse
  extends ResponseMessage<SuccessEditChatMessageResponsePayload> {}

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

SuccessEditChatMessageResponsePayload

interface SuccessSendChatMessageResponsePayload {
  timestamp: uint64;
}
ParameterTypeMandatoryDescription
timestampuint64YesMessage edit timestamp in UNIX timestamp format with millisecond precision

ErrorEditChatMessageResponse

Response in case of message modification error:

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

The ErrorEditChatMessageResponse interface 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, so the field descriptions will be provided there.

ForwardChatMessageRequestPayload

interface ForwardChatMessageRequestPayload {  
  chatId: string;  
  messageId: string;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID to which you will forward the message
messageIdstringYesForwarded message ID

SuccessForwardChatMessageResponse

Response in case of successful message forwarding:

interface SuccessForwardChatMessageResponse
  extends ResponseMessage<SuccessForwardChatMessageResponsePayload> {}

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

SuccessForwardChatMessageResponsePayload

interface SuccessForwardChatMessageResponsePayload {
  chatId: string;
  messageId: string;
  timestamp: uint64;
}
ParameterTypeMandatoryDescription
chatIdstringYesUnique identifier of the chat to which the message was forwarded
messageIdstringYesUnique identifier of the new message containing your forwarded message
timestampuint64YesMessage forwarding timestamp in UNIX timestamp format with millisecond precision

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 serving as the message body, so the description of the fields will be provided there.

GetChatMessageRequestPayload

interface GetChatMessageRequestPayload {
  messageId: string;
}
ParameterTypeMandatoryDescription
messageIdstringYesRequested message ID

SuccessGetChatMessageResponse

Response upon successful receipt of the message:

interface SuccessGetChatMessageResponse
  extends ResponseMessage<SuccessGetChatMessageResponsePayload> {}

The SuccessGetChatMessageResponse interface inherits fields from the SuccessGetChatMessageResponsePayload object, essentially serving as the message body itself. 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 field descriptions will be provided there.

GetChatHistoryRequestPayload

interface GetChatHistoryRequestPayload {
  chatId: string;
  count: uint32;
  fromMessageId?: string;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID for which the message history is being requested
countuint32YesNumber of messages returned in the response
fromMessageIdstringNoThe 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, it serves 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>;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID for which the message history was requested
countuint32YesNumber of received messages
messagesArrayNoArray with Envelope objects

ErrorGetChatHistoryResponse

Error response when retrieving chat history:

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

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

RemoveChatMessageRequest

Command to delete a message:

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

The RemoveChatMessageRequest interface inherits fields from the RemoveChatMessageRequestPayload object, essentially making it the body of the message. Therefore, the field descriptions will be provided there.

RemoveChatMessageRequestPayload

interface RemoveChatMessageRequestPayload {
  messageId: string;
  forAll: boolean;
}
ParameterTypeMandatoryDescription
messageIdstringYesID of the message to be deleted
forAllbooleanYesMessage 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 itself, so the description of the fields 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 serving as the message body. Therefore, the field descriptions will be provided there.

UploadFileRequestPayload

interface UploadFileRequestPayload {
  fileName: string;
  fileSize: number;
  mimeType: string;
}
ParameterTypeMandatoryDescription
fileNamestringYesFilename
fileSizenumberYesFile size
mimeTypestringYesMIME type of the file

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, it serves as the message body, so the field descriptions will be provided there.

SuccessUploadFileResponsePayload

interface SuccessUploadFileResponsePayload {
  uploadTaskId: string;
}
ParameterTypeMandatoryDescription
uploadTaskIdstringYesFile upload task ID

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 field descriptions are provided 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 making it the message body, so the field descriptions will be provided there.

SendFileRequestPayload

interface SendFileRequestPayload {
  chatId: string;
  content: {
    fileId: string,
  };
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID for sending a message
fileIdstringYesFile ID 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. Therefore, field descriptions will be provided there.

SuccessSendFileResponsePayload

interface SuccessSendFileResponsePayload {
  chatId: string;
  timestamp: number;
  messageId: string;
}
ParameterTypeMandatoryDescription
chatIdstringYesChat ID
timestampnumberYesTime of message sending
messageIdstringYesMessage ID

ErrorSendFileResponse

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

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

FileMessageContent

Receiving file transfer notification:

interface FileMessageContent {
  name: string;
  mimeType: string;
  size: number;
  fileId: string;
}
ParameterTypeMandatoryDescription
namestringYesFilename
sizenumberYesFile size
mimeTypestringYesMIME type of the file
fileIdstringYesFile 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;
}
ParameterTypeMandatoryDescription
fileIdstringYesThe file identifier received 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, it serves as the message body, so the description of the fields 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,
    }>,
  }
ParameterTypeMandatoryDescription
namestringYesFilename
sizenumberYesFile size in bytes
mimeTypestringYesMIME type of the file
downloadUrlstringYesURL for file download
readyStateFileReadyStateEnumYesFile status on the server
infoHashstringYesFile ID on the server
previewsArrayYesFile preview array

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 interface SubscribeFileProgressRequest inherits fields from the SubscribeFileProgressRequestPayload object, essentially serving as the message body, so the field descriptions will be provided there.

SubscribeFileProgressRequestPayload

interface SubscribeFileProgressRequestPayload {
  fileId: string;
}
ParameterTypeMandatoryDescription
fileIdstringYesFile ID on the server

SuccessSubscribeFileProgressResponse

Response in case of successful subscription:

interface SuccessSubscribeFileProgressResponse
  extends ResponseMessage<SuccessSubscribeFileProgressResponsePayload> {}

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

SuccessSubscribeFileProgressResponsePayload

interface SuccessSubscribeFileProgressResponsePayload {
  result: boolean;
}
ParameterTypeMandatoryDescription
resultbooleanYesWas the subscription for the download 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;
}
ParameterTypeMandatoryDescription
fileIdstringYesFile ID on the server
ProgressnumberYesNumber 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, it serves as the message body, so the field descriptions will be provided there.

UnsubscribeFileProgressRequestPayload

interface UnsubscribeFileProgressRequestPayload {
  fileId: string;
}
ParameterTypeMandatoryDescription
idstringYesFile ID 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 message body, so the field descriptions will be provided there.

SuccessUnsubscribeFileProgressResponsePayload

interface SuccessUnsubscribeFileProgressResponsePayload {
  result: boolean;
}
ParameterTypeMandatoryDescription
resultbooleanYesWere you able to unsubscribe from receiving events?

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: EnvelopeContentType;
  author: EnvelopeAuthor;
  box: EnvelopeBox;
  content: AbstractEnvelopeContent;
}
ParameterTypeMandatoryDescription
messageIdstringYesUnique message identifier
chatIdstringYesUnique identifier of the chat containing the message
timestampuint64YesTimestamp for sending a message in UNIX timestamp format with millisecond precision
replyMessageIdstringNoIf this is a reply to a message, it contains the identifier of that message.
isEditedbooleanYesHas the message ever been edited
typeEnvelopeContentTypeYesMessage Type
authorEnvelopeAuthorYesMessage Author
boxEnvelopeBoxYesMessage sequence numbers
contentAbstractEnvelopeContentYesMessage 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;
}
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.
typeEnvelopeAuthorTypeEnumYesMessage author type

EnvelopeBox

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

interface EnvelopeBox {
  id: number;
  position: string;
}
ParameterTypeMandatoryDescription
idnumberYesThe serial number of the "box" containing the message
positionstringYesMessage serial number in the "box"

You can learn how to work with this object in the relevant 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 those sections for field descriptions.

GenericErrorPayload

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

Message

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

interface Message {
  type: MESSAGE_TYPE;
  id: uint64;
}
ParameterTypeMandatoryDescription
typeenum MESSAGE_TYPEYesMessage type from the MESSAGE_TYPE enumeration
iduint32YesThe unique message identifier is an incrementing number (in some protocols, like TCP, such a number is called a sequence id).****The identifier can be identical for outgoing and incoming messages.****The value of the identifier may increment by more than one unit at a time. For more details, see below.

RequestMessage

Message with the type Request.

interface RequestMessage<Method extends string, Payload extends JSONObject> extends Message {  
  type: MESSAGE_TYPE.REQUEST;  
  method: Method;  
  payload: Payload;
}
ParameterTypeMandatoryDescription
typeMESSAGE_TYPE.REQUESTYesMessage type (default is 1).
methodstringYesType of command being sent
payloadJSONObjectNoAny JSON object applicable for the given method. The field may be omitted if no additional parameters are provided for the given 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 type Response.

interface ResponseMessage<Payload extends JSONObject> extends Message {
  type: MESSAGE_TYPE.RESPONSE;
  payload: Payload;
}
ParameterTypeMandatoryDescription
typeMESSAGE_TYPE.RESPONSEYesMessage type (default is 2).
payloadJSONObjectNoAny JSON object that is applicable as payload for the response to a request. The 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;
}
ParameterTypeMandatoryBy defaultDescription
client_idstringYes"chat_bot"Constant string "chat_bot"
grant_typestringYes"password"Constant string "password"
usernamestringYes
passwordstringYes

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 in case of successful authorization when obtaining an identification token.

interface OAuthTokenSuccessResponse {
  access_token: string;
  token_type: string;
  expires_at: uint32;
}
ParameterTypeMandatoryBy defaultDescription
access_tokenstringYes
token_typestringYes"JWT"Constant string "JWT"
expires_atuint32Yes

OAuthTokenErrorResponse

The response structure in case of an authorization error when obtaining the identification token.

interface OAuthTokenErrorResponse {
  error: "OAUTH_ERROR";
  error_description: string;
}
ParameterTypeMandatoryDescription
errorenum OAUTH_ERRORYesValue from OAUTH_ERROR enumeration
error_descriptionstringYesHuman-readable authorization error text

RemoveParticipantEnvelopeContent

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

interface RemoveParticipantEnvelopeContent extends AbstractEnvelopeContent {
  userId: string;
}
ParameterTypeMandatoryDescription
userIdstringYesTrueConf ID of the user removed from the chat.

PlainMessageEnvelopeContent

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

interface RemoveParticipantEnvelopeContent extends AbstractEnvelopeContent {
  text: string;
  parseMode: TextParseModeEnum;
}
ParameterTypeMandatoryDescription
textstringYesMessage text
parseModeTextParseModeEnumYesMessage text processing mode. For more details, refer to the enumeration description.

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 the content of a message with the type EnvelopeContentType.FORWARD_MESSAGE and has the following interface:

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

A unique feature of the interface of an object with forwarded message content 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 EnvelopeContentType.ATTACHMENT type and has the following interface:

interface AttachmentMessageEnvelopeContent extends AbstractEnvelopeContent {
  name: string;
  mimeType: string;
  size: number;
  id: string;
}
ParameterTypeMandatoryBy defaultDescription
namestringYes
mimeTypestringYesI'm sorry, but it seems like there is no text provided for translation. Could you please provide the text you want to be localized?The MIME type of the file being sent. It can be, for example, the string "image/jpeg" or an empty string if the attachment type could not be determined.
sizeuint64Yes
idstringYesI'm sorry, but it seems like there is no text provided for translation. Could you please provide the text you want to be localized?A unique file identifier that allows for 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;
  type: EnvelopeAuthorTypeEnum;
}
ParameterTypeMandatoryDescription
userIdstringYesTrueConf ID of the user added to the chat
roleChatParticipantRoleEnumYesUser role in chat (see enumeration ChatParticipantRoleEnum)
roleEnvelopeAuthorTypeEnumYesUser type (see enumeration EnvelopeAuthorTypeEnum)