# Working with Chats

# Creating a personal chat with a user

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.

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

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

# Retrieving chat information by ID

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.

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

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

# Adding a participant to the 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.

# Removing a participant from the chat

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.

# Checking Participant Presence 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.

# Retrieving the list of 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.

← User Roles and Permissions Working with Address Book →