> ## 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. # Chat REST API The Chat REST API provides HTTP access to Ably Chat functionality for server-side operations. Use this API to send messages, manage rooms, and perform administrative tasks without maintaining a persistent connection. ## Overview The Chat REST API enables you to: * Send messages to chat rooms * Query message history * Manage room metadata * Retrieve room occupancy * Perform moderation actions ## Base URL All Chat REST API requests use:


  ```text theme={null}
  https://rest.ably.io
  ```

## Authentication The Chat REST API uses the same authentication as the standard [REST API](/docs/api/rest-api): ### Basic Authentication


  ```shell theme={null}
  curl https://rest.ably.io/chat/rooms/my-room/messages \
    -u "{{API_KEY}}"
  ```

### Token Authentication


  ```shell theme={null}
  curl https://rest.ably.io/chat/rooms/my-room/messages \
    -H "Authorization: Bearer {{TOKEN}}"
  ```

## Rooms Rooms are the primary organizational unit in Chat. ### Get Room Retrieve room metadata:


  ```shell theme={null}
  curl https://rest.ably.io/chat/rooms/my-room \
    -u "{{API_KEY}}"
  ```

Unique identifier for the room. Room display name. Custom room metadata. ### List Rooms List all active rooms:


  ```shell theme={null}
  curl https://rest.ably.io/chat/rooms \
    -u "{{API_KEY}}"
  ```

## Messages Send and retrieve chat messages. ### Send Message Send a message to a room:


  ```shell theme={null}
  curl -X POST https://rest.ably.io/chat/rooms/my-room/messages \
    -u "{{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Hello, world!",
      "metadata": {
        "userId": "user123"
      }
    }'
  ```

The message text content. Custom message metadata. Message headers for filtering and routing. ### Get Message History Retrieve message history for a room:


  ```shell theme={null}
  curl "https://rest.ably.io/chat/rooms/my-room/messages?limit=50&direction=backwards" \
    -u "{{API_KEY}}"
  ```

Start time in milliseconds since epoch. End time in milliseconds since epoch. Maximum number of messages to return (max 1000). Query direction: `forwards` or `backwards`. ## Occupancy Query room occupancy information. ### Get Occupancy Retrieve current room occupancy:


  ```shell theme={null}
  curl https://rest.ably.io/chat/rooms/my-room/occupancy \
    -u "{{API_KEY}}"
  ```

Number of active connections to the room. Number of members present in the room. ## Typing Indicators Manage typing indicators (typically used by server-side bots). ### Send Typing Indicator


  ```shell theme={null}
  curl -X POST https://rest.ably.io/chat/rooms/my-room/typing \
    -u "{{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "clientId": "bot-user",
      "isTyping": true
    }'
  ```

## Reactions Send reactions to messages. ### Send Reaction Add a reaction to a message:


  ```shell theme={null}
  curl -X POST https://rest.ably.io/chat/rooms/my-room/messages/MESSAGE_ID/reactions \
    -u "{{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "like",
      "metadata": {
        "userId": "user123"
      }
    }'
  ```

### Get Reactions Retrieve reactions for a message:


  ```shell theme={null}
  curl https://rest.ably.io/chat/rooms/my-room/messages/MESSAGE_ID/reactions \
    -u "{{API_KEY}}"
  ```

## Moderation Perform moderation actions on messages. ### Delete Message Delete a message from a room:


  ```shell theme={null}
  curl -X DELETE https://rest.ably.io/chat/rooms/my-room/messages/MESSAGE_ID \
    -u "{{API_KEY}}"
  ```

### Update Message Update a message in a room:


  ```shell theme={null}
  curl -X PATCH https://rest.ably.io/chat/rooms/my-room/messages/MESSAGE_ID \
    -u "{{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Updated message text",
      "metadata": {
        "edited": true
      }
    }'
  ```

## Error Handling The Chat REST API uses standard HTTP status codes:


  ```json theme={null}
  {
    "error": {
      "code": 40160,
      "message": "Room not found",
      "statusCode": 404
    }
  }
  ```

Common errors: * `400` - Invalid request parameters * `401` - Authentication failed * `403` - Insufficient permissions * `404` - Room or message not found * `429` - Rate limit exceeded ## Rate Limits The Chat REST API shares rate limits with the standard REST API: * Message sending: Up to 2,000 messages per second * History queries: Up to 50 requests per second See [rate limits](/docs/platform/pricing/limits) for details. ## Examples ### Send Chat Message


  ```javascript theme={null}
  async function sendChatMessage(roomId, text, userId) {
    const response = await fetch(
      `https://rest.ably.io/chat/rooms/${roomId}/messages`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Basic ${btoa(API_KEY)}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          text: text,
          metadata: { userId: userId }
        })
      }
    );
    
    return await response.json();
  }
  ```

### Retrieve Recent Messages


  ```javascript theme={null}
  async function getRecentMessages(roomId, limit = 50) {
    const response = await fetch(
      `https://rest.ably.io/chat/rooms/${roomId}/messages?limit=${limit}&direction=backwards`,
      {
        headers: {
          'Authorization': `Basic ${btoa(API_KEY)}`
        }
      }
    );
    
    return await response.json();
  }
  ```

## Related Resources * [Chat SDK Documentation](/docs/chat) * [REST API Reference](/docs/api/rest-api) * [Chat Rooms Guide](/docs/chat/rooms) * [Chat Messages Guide](/docs/chat/rooms/messages)