# Manage chat room attributes (/en/realtime-media/im/build/build-groups-rooms-and-threads/chat-room/manage-chatroom-attributes/ios)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Chat room attributes consist of basic attributes (such as room subject, room description, and room announcement) and custom attributes. When basic attributes cannot satisfy the business requirements, users can add custom attributes that are synchronized with all chat room members.
    Custom attributes can be used to store information such as chat room type, game roles, game status, and host positions. They are stored as key-value maps, and the updates of custom attributes are synchronized with all chat room members.

    This page shows how to use the Agora Chat SDK to manage basic and custom attributes of a chat room in your app.

    ## Understand the tech [#understand-the-tech-1]

    The Chat SDK provides the `IAgoraChatroomManager`, `AgoraChatroomManagerDelegate`, and `AgoraChatRoom` classes for chat room management, which allow you to implement the following features:

    ## Prerequisites [#prerequisites-1]

    Before proceeding, ensure that you meet the following requirements:

    * You have initialized the Chat SDK. For details, see [SDK quickstart](../../../get-started-sdk).
    * You understand the call frequency limit of the Chat APIs supported by different pricing plans as described in [Limitations](../../limitations).
    * You understand the number of chat rooms supported by different pricing plans as described in [Pricing Plan Details](../../../reference/pricing-plan-details).

    ## Implementation [#implementation-1]

    This section introduces how to call the APIs provided by the Chat SDK to implement the features listed above.

    ### Manage basic chat room attributes [#manage-basic-chat-room-attributes-1]

    #### Retrieve basic chat room attributes [#retrieve-basic-chat-room-attributes-1]

    All chat room members can call `getChatroomSpecificationFromServerWithId` to retrieve the detailed information of the current chat room, including the subject, announcements, description, member type, and admin list.

    ```objc
    // Chat room members can call getChatroomSpecificationFromServerWithId to get the information of the specified chat room.
    AgoraChatError *error = nil;
    AgoraChatroom *chatroom = [[AgoraChatClient sharedClient].roomManager getChatroomSpecificationFromServerWithId:@“chatroomId” error:&error];
    ```

    #### Change chat room name or description [#change-chat-room-name-or-description-1]

    Only the chat room owner and admin can set and update the chat room name and description.

    ```objc
    // The chat room owner and admins can call updateSubject to update the chat room name.
    AgoraChatError *error = nil;
    [[AgoraChatClient sharedClient].roomManager updateSubject:textString forChatroom:self.chatroom.chatroomId error:&error];

    // The chat room owner and admins can call updateDescription to update the chat room description.
    AgoraChatError *error = nil;
    [[AgoraChatClient sharedClient].roomManager updateDescription:textString forChatroom:self.chatroom.chatroomId error:&error];
    ```

    #### Retrieve or change chat room announcements [#retrieve-or-change-chat-room-announcements]

    All chat room members can retrieve the chat room announcements.

    Only the chat room owner and admins can set and update the chat room announcements. Once the announcements are updated, all the chat room members receive the `chatroomAnnouncementDidUpdate` callback.

    ```objc
    // Chat room members can call getChatroomAnnouncementWithId to retrieve the chat room announcements.
    [AgoraChatClient.sharedClient.roomManager getChatroomAnnouncementWithId:@"chatRoomId" error:&error];

    // The chat room owner and admins can call updateChatroomAnnouncementWithId to set or update the chat room announcements.
    AgoraChatError *error =  nil;
    [[AgoraChatClient sharedClient].roomManager updateChatroomAnnouncementWithId:_chatroomId announcement:textString error:&error];
    ```

    ### Manage custom chat room attributes [#manage-custom-chat-room-attributes-1]

    #### Set a custom attribute [#set-a-custom-attribute-1]

    Chat room members can call `setChatroomAttributes` to set one single custom attribute. Use this method to add new custom attributes or update existing attributes that are set by yourself. After you successfully call this method, other members in the chat room receive a `chatroomAttributesDidUpdated` callback.

    ```objc
    // Sets a custom attribute by specifying chat room ID, attribute key, and attribute value.
    [AgoraChatClient.sharedClient.roomManager setChatroomAttributes:self.currentConversation.conversationId key:@"234" value:@"123" autoDelete:YES completionBlock:^(EMError * _Nullable aError, NSDictionary * _Nullable failureKeys) {
                    }];
    ```

    If you want to update a custom attribute that is set by other members, call `setChatroomAttributesForced` instead. After you successfully call this method, other members in the chat room receive a `chatroomAttributesDidUpdated` callback.

    ```objc
    // Sets a custom attribute by specifying chat room ID, attribute key, and attribute value.
    [AgoraChatClient.sharedClient.roomManager setChatroomAttributesForced:self.currentConversation.conversationId key:@"234" value:@"123" autoDelete:YES completionBlock:^(EMError * _Nullable aError, NSDictionary * _Nullable failureKeys) {
                    }];
    ```

    #### Set multiple custom attributes [#set-multiple-custom-attributes-1]

    To set multiple custom attributes, call the `setChatroomAttributes` method with same name. Use this method to add new custom attributes or update existing attributes that are set by yourself. After you successfully call this method, other members in the chat room receive a `chatroomAttributesDidUpdated` callback.

    ```objc
    // Sets multiple custom attributes by specifying chat room ID and the key-value maps of the attributes.
    [AgoraChatClient.sharedClient.roomManager setChatroomAttributes:self.currentConversation.conversationId attributes:@{@"testKey":@"123"} autoDelete:YES completionBlock:^(EMError * _Nullable aError, NSDictionary * _Nullable failureKeys) {
                    }];
    ```

    If you want to update custom attributes that are set by other members, call `setChatroomAttributesForced` instead. After you successfully call this method, other members in the chat room receive a `chatroomAttributesDidUpdated` callback.

    ```objc
    // Sets a custom attribute by specifying chat room ID and the key-value map of the attribute.
    [AgoraChatClient.sharedClient.roomManager setChatroomAttributesForced:self.currentConversation.conversationId attributes:@{@"testKey":@"123"} autoDelete:YES completionBlock:^(EMError * _Nullable aError, NSDictionary * _Nullable failureKeys) {
                    }];
    ```

    #### Retrieve specified or all custom attributes [#retrieve-specified-or-all-custom-attributes-1]

    All chat room members can call `fetchChatroomAttributes` or `fetchChatroomAllAttributes` to retrieve specified or all custom attributes of the chat room.

    ```objc
    // Retrieves certain custom attributes by specifying chat room ID and attribute keys.
    [AgoraChatClient.sharedClient.roomManager fetchChatroomAttributes:self.currentConversation.conversationId keys:@[@"123"] completion:^(NSDictionary * _Nullable map, EMError * _Nullable error) {
                }];

    // Retrieves all custom attributes by specifying chat room ID.
    [AgoraChatClient.sharedClient.roomManager fetchChatroomAllAttributes:self.currentConversation.conversationId completion:^(NSDictionary * _Nullable map, EMError * _Nullable error) {
                }];
    ```

    #### Remove a custom attribute [#remove-a-custom-attribute-1]

    Chat room members can call `removeChatroomAttributes` to remove one single custom attribute that is set by themselves. After you successfully call this method, other members in the chat room receive a `chatroomAttributesDidRemoved` callback.

    ```objc
    // Removes a custom attribute by specifying chat room ID and attribute key.
    [AgoraChatClient.sharedClient.roomManager removeChatroomAttributes:self.currentConversation.conversationId key:@"234" autoDelete:YES completionBlock:^(EMError * _Nullable aError, NSDictionary * _Nullable failureKeys) {
                    }];
    ```

    If you want to update custom attributes that are set by other members, call `removeChatroomAttributesForced` instead. After you successfully call this method, other members in the chat room receive a `chatroomAttributesDidRemoved` callback.

    ```objc
    // Removes a custom attribute by specifying chat room ID and attribute key.
    [AgoraChatClient.sharedClient.roomManager removeChatroomAttributesForced:self.currentConversation.conversationId key:@"234" autoDelete:YES completionBlock:^(EMError * _Nullable aError, NSDictionary * _Nullable failureKeys) {
                    }];
    ```

    #### Remove multiple custom attributes [#remove-multiple-custom-attributes-1]

    To remove multiple custom attributes, chat room members can call the `removeChatroomAttributes` method with same name to remove multiple custom attributes that are set by themselves. After you successfully call this method, other members in the chat room receive a  `chatroomAttributesDidRemoved` callback.

    ```objc
    // Removes multiple custom attributes by specifying chat room ID and the attribute key list.
    [AgoraChatClient.sharedClient.roomManager removeChatroomAttributes:self.currentConversation.conversationId attributes:@[@"testKey"] completionBlock:^(EMError * _Nullable aError, NSDictionary * _Nullable failureKeys) {
                    }];
    ```

    If you want to update custom attributes that are set by other members, call `removeChatroomAttributesForced` instead. After you successfully call this method, other members in the chat room receive a `chatroomAttributesDidRemoved` callback.

    ```objc
    // Removes multiple custom attributes by specifying chat room ID and the attribute key list.
    [AgoraChatClient.sharedClient.roomManager removeChatroomAttributesForced:self.currentConversation.conversationId attributes:@[@"testKey"] completionBlock:^(EMError * _Nullable aError, NSDictionary * _Nullable failureKeys) {
                    }];
    ```