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

← User Roles and Permissions Working with Address Book →