Working with chat participants
About 15 min
Working with chat participants
Client requests
Add participant to chat
Adds a user to a group chat or channel. Appropriate permissions are required to perform this operation.
Request:
{
"type": 1,
"id": 1,
"method": "addChatParticipant",
"payload": {
"chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
"userId": "user@video.example.com",
"displayHistory": false
}
}| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | Command addChatParticipant |
| chatId | string | Yes | Chat ID where the user is added |
| userId | string | Yes | TrueConf ID of the user being added to the chat |
| displayHistory | bool | No | 5.5.3+ Chat history display flag. If true, the user will see previous messages. |
Response:
{
"type": 2,
"id": 1,
"payload": {}
}| Parameter | Type | Mandatory | 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. |
| payload | object | Yes | In case of success, you will receive an empty object. |
In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding section of the documentation.
Remove chat participant
Removes the specified participant from the chat. This can only be used in group chats and channels. Appropriate permissions are required to perform this operation.
Request:
{
"type": 1,
"id": 1,
"method": "removeChatParticipant",
"payload": {
"chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
"userId": "user@video.example.com",
"clearHistory" : false
}
}| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | Command removeChatParticipant |
| chatId | string | Yes | Chat ID from which the user is being removed |
| userId | string | Yes | TrueConf ID of the user to be deleted |
| clearHistory | bool | No | 5.5.3+ If true, the chat will be cleared when the participant is removed. By default, it is false. |
Response:
{
"type": 2,
"id": 1,
"payload": {}
}| Parameter | Type | Mandatory | 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. |
| payload | object | Yes | In case of success, you will receive an empty object. |
In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding section of the documentation.
Change participant role 5.5.2+
Allows you to change the role of a chat participant. To change a role, you must have the appropriate permission. You will also receive a notification when the role is changed for any chat participant.
Request:
{
"type": 1,
"id": 1,
"method": "changeParticipantRole",
"payload": {
"chatId": "2b896a6ef210d6b2dcaebc2186c9a7974d616054",
"userId": "user@video.example.com",
"role": "admin"
}
}| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | Command changeParticipantRole |
| chatId | string | Yes | Chat ID |
| userId | string | Yes | TrueConf ID of the user whose role is being changed |
| role | string | Yes | New user role |
Response:
{
"type": 2,
"id": 1,
"payload": {}
}| Parameter | Type | Mandatory | 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. |
| payload | object | Yes | In case of success, you will receive an empty object. |
In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding section of the documentation.
Get chat participant 5.5.3+
Returns a participant of the specified chat, including their role and type.
Request:
{
"type": 1,
"id": 1,
"method": "getChatParticipant",
"payload": {
"chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
"userId": "user@video.example.com",
}
}| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | Command getChatParticipant |
| chatId | string | Yes | Chat ID |
| userId | string | Yes | TrueConf ID of the requested user |
Response:
{
"type": 2,
"id": 1,
"payload": {
"userId": "user@video.example.com",
"role": "user",
"type": 1
}
}| Parameter | Type | Mandatory | 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. |
| userId | string | Yes | TrueConf ID of the user |
| role | string | Yes | User role (see description) |
| type | uint32 | Yes | User type (see description) |
In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding section of the documentation.
Get chat participants
Returns a list of all participants in the specified chat, including their role and type.
Request:
{
"type": 1,
"id": 1,
"method": "getChatParticipants",
"payload": {
"chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
"pageSize": 100,
"pageNumber": 1
}
}| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | Command getChatParticipants |
| chatId | string | Yes | Chat ID |
| pageSize | uint32 | Yes | Number of records with information about chat participants in the response to the request |
| pageNumber | uint32 | Yes | The offset at which the participant list will be returned. It is calculated using the formula startOffset = pageSize * pageNumber. |
Response:
{
"type": 2,
"id": 1,
"payload": {
"participants": [
{
"userId": "user@video.example.com",
"role": "user",
"type": 1
},
{
"userId": "admin@video.example.com",
"role": "admin",
"type": 1
}
]
}
}| Parameter | Type | Mandatory | 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 | Yes | List of chat participants, presented as ChatParticipant objects |
In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding section of the documentation.
Verify participant in chat Deprecated in 5.5.3+
Use the getChatParticipant request.
Request:
{
"type": 1,
"id": 1,
"method": "hasChatParticipant",
"payload": {
"chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
"userId": "user@video.example.com"
}
}| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | The hasChatParticipant command |
| chatId | string | Yes | Chat ID where the user's presence is checked |
| userId | string | Yes | TrueConf ID of the user being verified |
Response:
{
"type": 2,
"id": 1,
"payload": {
"result": true
}
}| Parameter | Type | Mandatory | 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. |
| result | boolean | Yes | Flag indicating the presence of a participant in the chat. If true — the participant is present in the chat. |
In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding section of the documentation.
Server notifications
Participant added to chat
The server sends a notification when a new participant is added to a group chat or channel.
Notification from the server:
{
"method": "addChatParticipant",
"type": 1,
"id": 1,
"payload": {
"chatId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
"userId": "user@video.example.com",
"userRole": "owner",
"addedBy": {
"id": "admin@video.example.com",
"type": 1
},
"timestamp": "1735370776"
}
}| Parameter | Type | Mandatory | 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 incrementing value assigned by the sender. Read more here |
| chatId | string | Yes | Chat ID where the user was added |
| userId | string | Yes | TrueConf ID of the user who was added to the chat |
| userRole | string | Yes | 5.5.2+ Role of the user who added a participant to the chat |
| addedBy.id | string | Yes | Unique identifier of the user who added a new participant. This can be a TrueConf ID or a server name, depending on addedBy.type. |
| addedBy.type | uint32 | Yes | The type of user who added a new participant. See EnvelopeAuthorTypeEnum |
| timestamp | uint64 | Yes | Timestamp of adding a participant to the chat in UNIX timestamp format (in milliseconds) |
Response from client:
{
"type": 2,
"id": 123456
}| Field | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE |
| id | uint32 | Yes | Message ID being replied to (see more) |
Chat participant removed
The server sends a notification when a participant has been removed from a group chat or channel.
Notification 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 | Mandatory | Description |
|---|---|---|---|
| method | string | Yes | Command removeChatParticipant |
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| chatId | string | Yes | Chat ID where the user was removed |
| userId | string | Yes | TrueConf ID of the user who was removed from the chat |
| removedBy.id | string | Yes | Unique identifier of the user who removed a participant from the chat. This is either a TrueConf ID or the name of the server from which the message was received. The type of identifier depends on the removedBy.type field. |
| removedBy.type | uint32 | Yes | The type of user who removed a participant from the chat. For more details, see EnvelopeAuthorTypeEnum. |
| timestamp | uint64 | Yes | Timestamp of participant removal from chat in UNIX timestamp format with millisecond precision. |
Response from client:
{
"type": 2,
"id": 123456
}| Field | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE |
| id | uint32 | Yes | Message ID being replied to (see more) |
Participant role changed 5.5.2+
The server sends a notification when a chat participant's role has changed.
Request:
{
"type": 1,
"id": 1,
"method": "changeParticipantRole",
"payload": {
"chatId": "7e5ea3e8b5ed63e1443b2e4dcdd68b9f196abae1",
"userId": "user@video.example.com",
"role": "admin",
"timestamp": 1760594447544
}
}| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | Command changeParticipantRole |
| chatId | string | Yes | Chat ID |
| userId | string | Yes | TrueConf ID of the user whose role has changed |
| role | string | Yes | New user role |
| timestamp | uint64 | Yes | Timestamp of the chat participant role change in UNIX timestamp format with millisecond precision. |
Response from client:
{
"type": 2,
"id": 123456
}| Field | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE |
| id | uint32 | Yes | Message ID being replied to (see more) |