# Working with Chats

# Client requests

# Create personal chat

Creating a personal chat (peer-to-peer) with a server user. 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, the existing chat will be returned.

Request:

{
    "type": 1,
    "id": 1,
    "method": "createP2PChat",
    "payload": {
        "userId": "user@video.example.com"
    }
}
Parameter Type Required Description
type uint32 Yes Type of message (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. Incremental value assigned by the sender, required in each request for subsequent linking with the response. Read more here
method string Yes Command createP2PChat
userId string Yes TrueConf ID of the user with whom we want to create a chat

Answer:

{
    "type": 2,
    "id": 1,
    "payload": {
        "chatId": "4a1f88f1070d2f43d385cde9ff61964bc6b74477"
    }
}
Parameter Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes An identifier matching the number sent in the original request, used to associate the request and response
chatId string Yes Identifier of the created chat

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

# Create a group chat

Request:

{
    "type": 1,
    "id": 1,
    "method": "createGroupChat",
    "payload": {
        "name": "TrueConf Server Administrators’ Chat"
    }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementing value assigned by the sender, required in each request for subsequent association with the response. Read more here
method string Yes Command createGroupChat
name string Yes Name of the group chat

Answer:

{
    "type": 2,
    "id": 1,
    "payload": {
        "chatId": "2b896a6ef210d6b2dcaebc2186c9a7974d616054"
    }
}
Parameter Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes An identifier matching the number sent in the original request, used to link the request and response
chatId string Yes The identifier of the created group chat

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

# Create channel

Request:

{
    "type": 1,
    "id": 1,
    "method": "createChannel",
    "payload": {
        "title": "Company news"
    }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementing value assigned by the sender, required in each request for subsequent matching with the response. Read more here
method string Yes The command createChannel
title string Yes Channel name

Answer:

{
    "type": 2,
    "id": 1,
    "payload": {
        "chatId": "2b896a6ef210d6b2dcaebc2186c9a7974d616054"
    }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier that matches the number sent in the original request, used for linking the request and response
chatId string Yes Identifier of the created channel

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

# Delete chat

Deleting both personal and group chats.

Request:

{
  "type": 1,
  "id": 1,
  "method": "removeChat",
  "payload": {
    "chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256"
  }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incremented value assigned by the sender, required in each request for subsequent linkage with the response. Read more here
method string Yes Command removeChat
chatId string Yes Identifier of the chat to be removed

Answer:

{
  "type": 2,
  "id": 1,
  "payload": {
    "chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256"
  }
}
Parameter Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier matching the number sent in the original request, used to link the request and response
chatId string Yes Remote chat identifier

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

# Add participant to chat

Request:

{
  "type": 1,
  "id": 1,
  "method": "addChatParticipant",
  "payload": {
    "chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
    "userId": "user@video.example.com"
  }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementing value assigned by the sender, required in every request for subsequent matching with a response. For more details, read here
method string Yes The command addChatParticipant
chatId string Yes The identifier of the chat to which the user is being added
userId string Yes The TrueConf ID of the user being added to the chat

Answer:

{
  "type": 2,
  "id": 1,
  "payload": {}
}
Parameter Type Req. Description
type uint32 Yes Type of message (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes An identifier matching the number sent in the original request, used to link the request and response
payload object Yes In case of success, you will receive an empty object

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

# Remove chat participant

Request:

{
  "type": 1,
  "id": 1,
  "method": "removeChatParticipant",
  "payload": {
    "chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
    "userId": "user@video.example.com"
  }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementing value assigned by the sender, mandatory in each request for subsequent linking to the response. Read more here
method string Yes Command removeChatParticipant
chatId string Yes Chat identifier from which the user is removed
userId string Yes TrueConf ID of the user being removed

Answer:

{
  "type": 2,
  "id": 1,
  "payload": {}
}
Parameter Type Req. Description
type uint32 Yes Type of message (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes An identifier matching the number sent in the original request, used to link the request and response
payload object Yes In case of success, you will receive an empty object

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

# Retrieve the list of chats

Request:

{
    "type": 1,
    "id": 1,
    "method": "getChats",
    "payload": {
        "count": 10,
        "page": 1
    }
}
Parameter Type Req. Description
type uint32 Yes Type of message (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. This is an incremented value assigned by the sender, required in each request to associate with a response. Read more here
method string Yes Command getChats
count uint32 Yes Maximum number of chat objects in the response
page uint32 Yes Page number of the request (paging). Starts at 1

Answer:

{
    "type": 2,
    "id": 1,
    "payload": [
        {
            "chatId": "2b896a6ef210d6b2dcaebc2186c9a7974d616054",
            "title": "TrueConf Server Administrators’ Chat",
            "chatType": 2,
            "unreadMessages": 0,
            "lastMessage": {
                "messageId": "267d61f2-2ba1-4e88-83ab-bb84415f31b6",
                "timestamp": 1746028006345,
                "author": {
                    "id": "brown@video.example.com",
                    "type": 1
                },
                "type": 200,
                "content": {
                    "text": "What's up?",
                    "parseMode": "html"
                }
            }
        },
        {
            "chatId": "4a1f88f1070d2f43d385cde9ff61964bc6b74477",
            "title": "chester@video.example.com",
            "chatType": 1,
            "unreadMessages": 1,
            "lastMessage": {
                "messageId": "d4f756a2-8dd1-4cce-af7c-5a4311af0c79",
                "timestamp": 1746028006690,
                "author": {
                    "id": "chester@video.example.com",
                    "type": 1
                },
                "type": 200,
                "content": {
                    "text": "Hello!",
                    "parseMode": "html"
                }
            }
        },
        {
            "chatId": "5abba630dd1089090ba41c69c7aa34e4ba277a43",
            "title": "Project Announcements",
            "chatType": 6,
            "unreadMessages": 1,
            "lastMessage": {
                "messageId": "267d61f2-2ba1-4e88-83ab-bb84415f31b6",
                "timestamp": 1746028006345,
                "author": {
                    "id": "brown@video.example.com",
                    "type": 1
                },
                "type": 200,
                "content": {
                    "text": "Hello everyone!",
                    "parseMode": "html"
                }
            }
        }
    ]
}
Parameter Type Required Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier matching the number sent in the original request, used for linking the request and response
payload Array<Chat> Yes User's chat array

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

# Get chat information

Request:

{
    "type": 1,
    "id": 1,
    "method": "getChatByID",
    "payload": {
        "chatId": "2b896a6ef210d6b2dcaebc2186c9a7974d616054"
    }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incremented value assigned by the sender, required in each request for subsequent linking to the response. Read more here
method string Yes Command getChatByID
chatId string Yes Chat identifier

Answer:

{
    "type": 2,
    "id": 1,
    "payload": {
        "chatId": "2b896a6ef210d6b2dcaebc2186c9a7974d616054",
        "title": "TrueConf Server Administrators’ Chat",
        "chatType": 2,
        "unreadMessages": 0,
        "lastMessage": {
            "messageId": "267d61f2-2ba1-4e88-83ab-bb84415f31b6",
            "timestamp": 1746028006345,
            "author": {
                "id": "brown@video.example.com",
                "type": 1
            },
            "type": 200,
            "content": {
                "text": "What's up?",
                "parseMode": "html"
            }
        }
    }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier matching the number sent in the original request, used to link the request and response
chatId string Yes Chat identifier
title string Yes Chat title
chatType ChatTypeEnum Yes Type of chat
unreadMessages uint32 Yes Number of unread messages in the chat
lastMessage Envelope Yes Last message in the chat

The lastMessage field follows the Envelope format, except that it does not include the chatId, isEdited, and box fields.

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

# Get chat participants

Request:

{
  "type": 1,
  "id": 1,
  "method": "getChatParticipants",
  "payload": {
    "chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
    "pageSize": 100,
    "pageNumber": 1
  }
}
Parameter Type Req. Description
type uint32 Yes Type of message (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementing value assigned by the sender, required for every request to link with a response. More details read here
method string Yes Command getChatParticipants
chatId string Yes Chat identifier
pageSize uint32 Yes Number of records with chat participant information in the response to the request
pageNumber uint32 Yes Offset at which the list of participants will be returned. Calculated by the formula startOffset = pageSize * pageNumber

Answer:

{
  "type": 2,
  "id": 1,
  "payload": {
    "participants": [
      {
        "userId": "user@video.example.com",
        "role": "user"
      },
      {
        "userId": "admin@video.example.com",
        "role": "admin"
      }
    ]
  }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes An identifier matching the number sent in the original request, used to link the request and response
participants Array<ChatParticipant> Yes A list of chat participants represented as ChatParticipant objects

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

# Verify participant in chat

Request:

{
  "type": 1,
  "id": 1,
  "method": "hasChatParticipant",
  "payload": {
    "chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
    "userId": "user@video.example.com"
  }
}
Parameter Type Req. Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementable value assigned by the sending party, required in every request for subsequent mapping with the response. Read more here
method string Yes Command hasChatParticipant
chatId string Yes The chat ID in which the user's presence is checked
userId string Yes TrueConf ID of the user being checked

Answer:

{
  "type": 2,
  "id": 1,
  "payload": {
    "result": true
  }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier matching the number sent in the original request, used to associate the request and response
result boolean Yes Flag indicating participant presence in the chat. If true — the participant is present in the chat

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

# Server notifications

For each server notification (request), the client should respond as follows:

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

Once the response is sent, the user’s message is marked as read by the bot and a check mark appears in the TrueConf client application.

# Personal chat created

Notification from the server:

{
    "method": "createP2PChat",
    "type": 1,
    "id": 2,
    "payload": {
        "chatId": "bd05af54347e04a1c44e70033d35834d4428bb5d",
        "title": "brown@video.example.com",
        "chatType": 1,
        "lastMessage": {
            "chatId": "bd05af54347e04a1c44e70033d35834d4428bb5d",
            "messageId": "d8bdd362-2656-46ff-a1db-8dadd2b76250",
            "timestamp": 1746028006345,
            "author": {
                "id": "brown@video.example.com",
                "type": 1
            },
            "type": 200,
            "content": {
                "text": "What's up?",
                "parseMode": "text"
            }
        },
        "unreadMessages": 1
    }
}
Parameter Type Required Description
method string Yes Command createP2PChat
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementing value assigned by the sender. Read more here.
chatId string Yes Identifier of the created chat
title string Yes TrueConf ID of the user who created the chat
chatType uint32 Yes Type of the created chat. Corresponds to ChatTypeEnum
lastMessage.chatId string Yes Chat identifier where the message is located
messageId string Yes Message identifier. Can be used later for editing, forwarding, or deleting the message
timestamp uint64 Yes Message sending timestamp in UNIX timestamp format with millisecond precision
author.id string Yes Unique identifier of the message author (TrueConf ID or server name)
author.type uint32 Yes Type of message author. See EnvelopeAuthorTypeEnum
lastMessage.type uint32 Yes Type of message, corresponds to EnvelopeTypeEnum
text string No Message text
parseMode string No Formatting mode (more details)
unreadMessages uint32 Yes Number of unread messages in the personal chat

The payload.lastMessage.content field contains different data depending on the payload.lastMessage.type message type.

Response for the server:

{
    "type": 2,
    "id": 123456
}
Field Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier of the message being responded to (see details)

# Group chat created

Message from the server:

{
    "method": "createGroupChat",
    "type": 1,
    "id": 14,
    "payload": {
        "chatId": "08d5dbda94a9de4b7554e3b4355307f9e97ffdb7",
        "title": "Marketing",
        "chatType": 2,
        "lastMessage": {
            "chatId": "08d5dbda94a9de4b7554e3b4355307f9e97ffdb7",
            "messageId": "cccea4a7-24b4-4b2c-8c50-67d01bce17bf",
            "timestamp": 1746029638147,
            "author": {
                "id": "user@video.example.com",
                "type": 0
            },
            "type": 110,
            "content": {
                "userId": "bot@video.example.com",
                "role": "user"
            }
        },
        "unreadMessages": 2
    }
}
Parameter Type Req. Description
method string Yes Command createGroupChat
type uint32 Yes Message type (default 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incremented value assigned by the sender, required in each request for subsequent response matching. Read more here
chatId string Yes Identifier of the created chat
title string Yes Title of the created chat
chatType uint32 Yes Type of the created chat. Corresponds to ChatTypeEnum
lastMessage.chatId string Yes Identifier of the chat containing the message
messageId string Yes Message identifier. Can be used for modification, forwarding or deletion
timestamp uint64 Yes Timestamp in UNIX timestamp format with millisecond precision
author.id string Yes TrueConf ID of the message author or server name
author.type uint32 Yes Type of author. See EnvelopeAuthorTypeEnum
lastMessage.type uint32 Yes Message type. See EnvelopeTypeEnum
userId string No TrueConf ID of the user who sent the message
role string No User's role in the chat (see more)
unreadMessages uint32 Yes Number of unread messages in the group chat

The payload.lastMessage.content field varies depending on the payload.lastMessage.type of the message.

Response from client:

{
    "type": 2,
    "id": 123456
}
Field Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier of the message being responded to (see details)

# Channel created

Message from the server:

{
    "method": "createChannel",
    "type": 1,
    "id": 14,
    "payload": {
        "chatId": "08d5dbda94a9de4b7554e3b4355307f9e97ffdb7",
        "title": "Important Announcements",
        "chatType": 6,
        "lastMessage": {
            "chatId": "08d5dbda94a9de4b7554e3b4355307f9e97ffdb7",
            "messageId": "cccea4a7-24b4-4b2c-8c50-67d01bce17bf",
            "timestamp": 1746029638147,
            "author": {
                "id": "user@video.example.com",
                "type": 0
            },
            "type": 110,
            "content": {
                "userId": "bot@video.example.com",
                "role": "user"
            }
        },
        "unreadMessages": 2
    }
}
Parameter Type Req. Description
method string Yes Command createChannel
type uint32 Yes Message type (default 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incremented value assigned by the sender, required in each request for subsequent matching with the response. More details read here
chatId string Yes Identifier of the created channel
title string Yes Name of the created channel
chatType uint32 Yes Type of the created channel. Corresponds to ChatTypeEnum = 6
lastMessage.chatId string Yes Identifier of the channel where the message is located
messageId string Yes Identifier of the message. This identifier can be used later for editing, forwarding, or deleting the message
timestamp uint64 Yes Timestamp of the message sent in UNIX timestamp format with millisecond precision
author.id string Yes Unique identifier of the message author. It is either the TrueConf ID of the user or the server name from which the message was sent. The type of identifier depends on the type field
author.type uint32 Yes Type of the message author. For more details, see EnvelopeAuthorTypeEnum
lastMessage.type uint32 Yes Type of message. Allows identification of the type of content in the message. Corresponds to EnvelopeTypeEnum
userId string No TrueConf ID of the user who sent the message
role string No User role in the group chat (see more details)
unreadMessages uint32 Yes Number of unread messages in the channel

The payload.lastMessage.content field varies depending on the payload.lastMessage.type of the message.

Response from client:

{
    "type": 2,
    "id": 123456
}
Field Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier of the message being responded to (see details)

# Chat deleted

Message from the server:

{
    "method": "removeChat",
    "type": 1,
    "id": 1,
    "payload": {
        "chatId": "84960c6d80afa729b0fd42d35331de5814cc3e9a"
    }
}
Parameter Type Req. Description
method string Yes Command removeChat
type uint32 Yes Message type (default 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incremental value assigned by the sender. Read more here
chatId string Yes Identifier of the remote chat

# Participant added to chat

Message from the server:

{   
    "method": "addChatParticipant",
    "type": 1,
    "id": 1,
    "payload": {
        "chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
        "userId": "user@video.example.com",
        "addedBy": {
            "id": "admin@video.example.com",
            "type": 1
        },
        "timestamp": "1735370776"
    }
}
Parameter Type Required Description
method string Yes Command addChatParticipant
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incrementable value assigned by the sender. More details read here
chatId string Yes Identifier of the chat where the user was added
userId string Yes TrueConf ID of the user added to the chat
addedBy.id string Yes Unique identifier of the user who added the new participant. This is either the TrueConf ID or the server name, depending on addedBy.type
addedBy.type uint32 Yes Type of the user who added the new participant. See EnvelopeAuthorTypeEnum
timestamp uint64 Yes Timestamp of adding the participant to the chat in UNIX timestamp format (in milliseconds)

Response from client:

{
    "type": 2,
    "id": 123456
}
Field Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier of the message being responded to (see details)

# Chat participant removed

Message from the server:

{
  "method": "removedChatParticipant",
  "type": 1,
  "id": 1,
  "payload": {
    "chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
    "userId": "user@video.example.com",
    "removedBy": {
      "id": "admin@video.example.com",
      "type": 1
    },
    "timestamp": "1735370778"
  }
}
Parameter Type Required Description
method string Yes The removeChatParticipant command
type uint32 Yes Message type (default 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incremental value assigned by the sender, required in each request to subsequently link it with the response. More details here
chatId string Yes The chat identifier from which the user was removed
userId string Yes The TrueConf ID of the user removed from the chat
removedBy.id string Yes Unique identifier of the user who removed the participant from the chat. This is either the TrueConf ID or the server name from which the message was sent. The identifier type depends on the removedBy.type field
removedBy.type uint32 Yes Type of user who removed the participant from the chat. See more in EnvelopeAuthorTypeEnum
timestamp uint64 Yes Timestamp of the user's removal from the chat in UNIX timestamp format with millisecond precision

Response from client:

{
    "type": 2,
    "id": 123456
}
Field Type Req. Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier of the message being responded to (see details)