Accessing Live Chat

Live chat is delivered through the X Activity API (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 endpoint.

Prerequisites

A developer app 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.
The X user ID whose broadcasts you want to receive chat for (see Getting Started).

broadcast.chat is a private event and can only be created for users who have authorized your app.

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 guide for the full flow, including the CRC validation your endpoint must implement. 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

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

{
  "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, Update, and Delete 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:

{
  "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 for the full shape. Respond to each delivery with a 2xx status within the timeout described in the Webhooks 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.

Overview

Stream Sources

Broadcasts

Scheduled Broadcasts

Live Chat

Accessing Live Chat

Prerequisites

Step 1: Register a webhook

Example request

Request fields

Success response

Step 3: Receive chat events on your webhook

Pulling chat after a broadcast ends

​Prerequisites

​Step 1: Register a webhook

​Step 2: Subscribe to broadcast.chat for the user

​Example request

​Request fields

​Success response

​Step 3: Receive chat events on your webhook

​Pulling chat after a broadcast ends

Prerequisites

Step 1: Register a webhook

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

Example request

Request fields

Success response

Step 3: Receive chat events on your webhook

Pulling chat after a broadcast ends