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

# Accessing Live Chat

> Receive live chat messages for your broadcasts in real time by subscribing to the broadcast.chat event on the X Activity API.

Live chat is delivered through the [X Activity API](/x-api/activity/introduction) (XAA). Subscribe once to the `broadcast.chat` event for a user with the `broadcast.read` scope, and XAA pushes chat messages for every broadcast that user owns to your webhook in real time. There is no per-broadcast subscription and no separate handoff step.

To send chat messages, use the [Send a Chat Message](/livestream-api/chat/send-chat-message) endpoint.

## Prerequisites

* A [developer app](https://developer.x.com/en/portal/petition/essential/basic-info) in a Project with the X Activity API and Webhooks enabled.
* OAuth 2.0 Authorization Code Flow with PKCE for the broadcasting user, granting the `broadcast.read` scope. See [Authentication](/livestream-api/authentication).
* The X user ID whose broadcasts you want to receive chat for (see [Getting Started](/livestream-api/getting-started)).

<Note>
  `broadcast.chat` is a private event and can only be created for users who have authorized your app.
</Note>

## Step 1: Register a webhook

XAA delivers events over a webhook you host. Create the webhook once per environment and reuse its `webhook_id` for every subscription.

See the [Webhooks](/x-api/webhooks/introduction) guide for the full flow, including the CRC validation your endpoint must implement.

## Step 2: Subscribe to `broadcast.chat` for the user

Create one subscription per broadcasting user. The subscription covers all broadcasts that user owns — you do not need to resubscribe when a new broadcast starts.

**Endpoint:** `POST https://api.x.com/2/activity/subscriptions`

**Auth:** OAuth 2.0 user context with the `broadcast.read` scope (the token must belong to the user in `filter.user_id`).

### Example request

```bash theme={null}
curl -X POST "https://api.x.com/2/activity/subscriptions" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "broadcast.chat",
    "filter": { "user_id": "1111111111111111111" },
    "webhook_id": "2090847910112202752",
    "tag": "live-chat"
  }'
```

### Request fields

| Field            | Required | Description                                                    |
| :--------------- | :------- | :------------------------------------------------------------- |
| `event_type`     | Yes      | Must be `broadcast.chat`.                                      |
| `filter.user_id` | Yes      | The broadcasting user's ID. Must match the authenticated user. |
| `webhook_id`     | Yes      | ID of the webhook that will receive events.                    |
| `tag`            | No       | Caller-defined label echoed back on each event.                |

### Success response

```json theme={null}
{
  "data": {
    "subscription": {
      "subscription_id": "1998240115200000001",
      "event_type": "broadcast.chat",
      "filter": { "user_id": "1111111111111111111" },
      "webhook_id": "2090847910112202752",
      "tag": "live-chat",
      "created_at": "2026-09-15T14:30:00.000Z",
      "updated_at": "2026-09-15T14:30:00.000Z"
    }
  }
}
```

Store the `subscription_id`; use it to update or delete the subscription later. See [List](/x-api/activity/get-x-activity-subscriptions), [Update](/x-api/activity/update-x-activity-subscription), and [Delete](/x-api/activity/deletes-x-activity-subscription) subscription endpoints for management.

## Step 3: Receive chat events on your webhook

Once the broadcast is live and viewers send chat messages, XAA POSTs `broadcast.chat` events to your webhook using the standard XAA event envelope:

```json theme={null}
{
  "data": {
    "event_uuid": "2080761390344937796",
    "filter": { "user_id": "1111111111111111111" },
    "event_type": "broadcast.chat",
    "tag": "live-chat",
    "payload": { },
    "includes": { }
  }
}
```

`filter.user_id` identifies the broadcast owner. The `payload` describes the chat message; `includes` may contain related user objects. See [Event payloads](/x-api/activity/event-payloads) for the full shape.

Respond to each delivery with a `2xx` status within the timeout described in the [Webhooks](/x-api/webhooks/introduction) guide, then process the event asynchronously.

## Pulling chat after a broadcast ends

Real-time chat is delivered only while the broadcast is live. To read chat after a broadcast has ended, use [Get Chat History](/livestream-api/chat/get-chat-history).