> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ably/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rooms

Rooms are used to organize and logically separate your users and chat messages into 'rooms'. They are the entry object into using chat and provide access to all other chat features, such as messages, online status and typing indicators.

A room can represent a 1:1 chat between an agent and a customer, a private message between two users in a chat application, a large group conversation, or the chat section of a livestream with thousands of users.

## Use a Room

Users send messages to a room and subscribe to the room in order to receive messages.

<Tabs>
  <Tab name="JavaScript">
    <Code>
      ```javascript theme={null}
      const room = await chatClient.rooms.get('basketball-stream', {occupancy: {enableEvents: true}});
      ```
    </Code>
  </Tab>

  <Tab name="React">
    <Code>
      ```react theme={null}
      import * as Ably from 'ably';
      import { LogLevel } from '@ably/chat';
      import { ChatClientProvider, ChatRoomProvider } from '@ably/chat/react';

      const realtimeClient = new Ably.Realtime({ key: '{{API_KEY}}', clientId: 'clientId' });
      const chatClient = new ChatClient(realtimeClient);

      const App = () => {
        return (
          <ChatClientProvider client={chatClient}>
            <ChatRoomProvider
              name="my-room-id"
              options={{occupancy: {enableEvents: true}}}
            >
              <RestOfYourApp />
            </ChatRoomProvider>
          </ChatClientProvider>
        );
      };
      ```
    </Code>
  </Tab>

  <Tab name="Swift">
    <Code>
      ```swift theme={null}
      let room = try await chatClient.rooms.get(named: "basketball-stream", options: .init(occupancy: .init(enableEvents: true)))
      ```
    </Code>
  </Tab>

  <Tab name="Android / Kotlin">
    <Code>
      ```android theme={null}
      val room = chatClient.rooms.get(roomId = "basketball-stream")
      ```
    </Code>
  </Tab>
</Tabs>

## Attach to a Room

To start receiving messages and events from a room, you need to attach to it:

<Tabs>
  <Tab name="JavaScript">
    <Code>
      ```javascript theme={null}
      await room.attach();
      ```
    </Code>
  </Tab>

  <Tab name="React">
    <Code>
      ```react theme={null}
      import { useRoom } from '@ably/chat/react';

      const MyComponent = () => {
        const { attach } = useRoom();
        return (
          <div>
            <button onClick={attach}>Attach Me!</button>
          </div>
        );
      };
      ```
    </Code>
  </Tab>

  <Tab name="Swift">
    <Code>
      ```swift theme={null}
      try await room.attach()
      ```
    </Code>
  </Tab>

  <Tab name="Android / Kotlin">
    <Code>
      ```android theme={null}
      room.attach()
      ```
    </Code>
  </Tab>
</Tabs>

## Room Status

A room can have any of the following statuses:

| Status         | Description                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------- |
| `initializing` | The library is initializing the room.                                                           |
| `initialized`  | The room has been initialized, but no attach has been attempted yet.                            |
| `attaching`    | An attach has been initiated.                                                                   |
| `attached`     | An attach has succeeded. In the attached status a client can publish and subscribe to messages. |
| `detaching`    | A detach has been initiated.                                                                    |
| `detached`     | The room has been detached by the client.                                                       |
| `suspended`    | The room, having previously been attached, has lost continuity.                                 |
| `failed`       | An indefinite failure condition.                                                                |

Use the `status` property to check which status a room is currently in:

<Tabs>
  <Tab name="JavaScript">
    <Code>
      ```javascript theme={null}
      const currentStatus = room.status;
      const currentError = room.error;
      ```
    </Code>
  </Tab>

  <Tab name="React">
    <Code>
      ```react theme={null}
      import { useMessages } from '@ably/chat/react';

      const MyComponent = () => {
        const { roomStatus, roomError } = useMessages({
          listener: (message) => {
            console.log('Received message: ', message);
          },
        });

        return (
          <div>
            Room status is: {roomStatus}
            Room error is: {roomError}
          </div>
        );
      };
      ```
    </Code>
  </Tab>

  <Tab name="Swift">
    <Code>
      ```swift theme={null}
      let status = room.status
      ```
    </Code>
  </Tab>

  <Tab name="Android / Kotlin">
    <Code>
      ```android theme={null}
      val status = room.status
      ```
    </Code>
  </Tab>
</Tabs>

## Next Steps

* Learn about [messages](/docs/chat/rooms/messages)
* Explore [presence](/docs/chat/rooms/presence)
* Understand [typing indicators](/docs/chat/rooms/typing-indicators)
* Discover [room reactions](/docs/chat/rooms/reactions)