logo
In-app Chat
On this page

Update room attributes


Description

Update the custom room attributes of the specified room ID. A room can set up to 20 room attributes. If you need to increase the upper limit of the number of room attributes, please contact ZEGOCLOUD Technical Support.

After the room attribute is updated, you can receive the notification of the room attribute update through the following ZIM SDK callback interfaces.

PlatformCallback
iOS/macOSzim:roomAttributesUpdated:roomID:
AndroidonRoomAttributesUpdated
WindowsonRoomAttributesUpdated
WebroomAttributesUpdated

Request method and endpoint

  • Request method: POST
  • Request URL: https://zim-api.zego.im/?Action=ModifyRoomAttribute
  • Transmission protocol: HTTPS
  • QPS limit: 20 requests/second

Request parameters

The following table describes only the operation-specific request parameters and some common request parameters. For the complete list of common request parameters, see the Common request parameters section of the Accessing Server APIs topic.

ParameterTypeRequiredDescription
FromUserIdStringYesThe operator, which needs to be in the registered state. This user will not be automatically added to the room. Only numbers, English characters, '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', ' ', ', ', '|', '~' are supported.
RoomIdStringYesRoom ID. Only numbers, English characters, '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', ' ', ', ', '|', '~' are supported.
AttributesArray of ModifyRoomAttributeYesThe room attribute information to be updated.

ModifyRoomAttribute structure:

ParameterTypeRequiredDescription
ActionNumberYesDelete or set, 0: set, 1: delete.
KeyStringYesRoom attribute key.
ValueStringNoRoom attribute value.
AutoDeleteNumberNoWhether to automatically delete when the user exits the room, 0: not automatically delete, 1: automatically delete. If FromUserId is not in the room, it will trigger the deletion operation after it enters the room and then exits the room.
StopOnErrorNumberNoWhether to enable fast failure, default is disabled.
  • 0: Disable fast failure. When an error occurs during execution, the current attribute is recorded and the subsequent update operations are continued. All recorded attributes are returned after the execution is completed.
  • 1: Enable fast failure. When an error occurs during execution, the subsequent update operations are stopped and the attribute that failed to be updated is returned. The successfully executed update operations are retained.
Description

If the Key already exists, the existing attribute information will be modified.

Request example

  • Request URL:
https://zim-api.zego.im/?Action=ModifyRoomAttribute
&<Common request parameters>
  • Request body:
{
    "RoomId": "room123",
    "FromUserId": "fromUserId",
    "Attributes": [
        {
            "Action": 0,
            "Key": "attribute1",
            "Value": "value1",
            "AutoDelete": 1
        },
        {
            "Action": 1,
            "Key": "attribute2",
            "Value": "",
            "AutoDelete": 0
        }
    ]    
}

Response parameters

The response parameters are as follows:

ParameterTypeRequiredDescription
CodeNumberYesReturn status code (0 means success).
MessageStringYesReturn status information.
RequestIdstringYesRequest unique identifier.
ErrKeyListArray of ErrListNoThe list of keys that

ErrList structure:

ParameterTypeRequiredDescription
SubCodeNumberYesError code.
KeyStringYesThe key value that caused the error.

Response example

{
    "Code": 0,
    "Message": "success",
    "RequestId": "req-123456789",
    "ErrKeyList": [
        {
            "SubCode": 1,
            "Key": "attr1"
        },
        {
            "SubCode": 2,
            "Key": "attr2"
        }
    ]
}

Return codes

The following return codes are only listed for interface business logic. For the complete list of return codes, see Global return codes.

Return codeDescriptionSolution
660000002Parameter error.Please check the parameters.
660300005Frequency limit.Please try again later.

Previous

Query room attributes

Next

Destroy a room