跳转到主要内容
本指南介绍如何使用 X Activity API 端点订阅并接收事件。通常分为 3 个步骤：
  1. 找到你要筛选其事件的用户的 User ID
  2. 为该用户创建要筛选的事件类型的订阅
  3. 通过 webhook 或持久化的 HTTP 流式连接接收事件

​
获取用户 ID

在创建订阅之前，你需要知道要用于过滤的账户的用户 ID。此示例中，我们将使用 XDevelopers 的用户名。你可以通过多种方式查找用户 ID，包括： 通过用户名查询用户 ID： 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" "https://api.x.com/2/users/by/username/xdevelopers"
获取你的用户 id： 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/users/me
这两个端点都会返回包含 id 字段的用户信息，您可以在订阅过滤条件中使用该字段。下面展示了示例 JSON 响应： 
{
    "data": {
        "id": "2244994945",
        "name": "Developers",
        "username": "XDevelopers"
    }
}

​
创建订阅

下一步是创建订阅。在此示例中，我们将订阅 X Developers 的个人简介更新。为此，我们将在 JSON 正文中传入 user_id 和 event_type。在本例中，event_type 为 ProfileBioUpdate。 我们将传入 X Developer 的用户 ID：2244994945，以及一个可选的标签： 
{
  "event_type": "ProfileBioUpdate",
  "filter": {
    "user_id": "2244994945"
  },
  "tag": "Xdevelopers 的简介更新"
}
我们将使用持有者令牌（来自开发者门户）为所有与 XAA 相关的端点进行授权： 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions \
  -X POST \
  -d '{
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "2244994945"
    },
    "tag": "Xdevelopers 的简介更新"
  }'
请求成功后，将创建您的订阅： 
{
  "data":[
    {
      "created_at":"2025-10-09T16:35:08.000Z",
      "event_type":"ProfileBioUpdate",
      "filter":{
        "user_id":"2244994945"
      },
      "subscription_id":"1976325569252868096",
      "tag": "Xdevelopers 的简介更新",
      "updated_at":"2025-10-09T16:35:08.000Z"
    }
  ],
  "meta": {
    "total_subscriptions": 1
  }
}

​
获取事件

创建订阅后，我们可以通过 webhooks 或持久化 HTTP 流接收事件。本示例中，我们将打开一个持久化 HTTP 流： 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/activity/stream
当 Xdevelopers 账号更新其个人简介时，该事件会通过流式接口推送： 
{
  "data": {
    "filter": {
      "user_id": "2244994945"
    },
    "event_type": "ProfileBioUpdate",
    "tag": "Xdevelopers 的简介更新",
    "payload": {
      "before": "Mars & Cars",
      "after": "Mars, Cars & AI"
    }
  }
}

​
订阅管理

X Activity API 提供端点，可通过标准的 CRUD 操作来管理你的订阅。

​
创建订阅

创建新的订阅以接收事件： 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X POST \
  https://api.x.com/2/activity/subscriptions \
  -d '{
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "tag": "我的简介更新",
    "webhook_id": "1976325569252868099"
  }'
注意：
  • tag 字段为可选。可用于帮助在投递时识别事件。
  • webhook_id 字段同样为可选。有关设置 webhook 的说明，请参阅我们的webhook 文档。如果指定了 webhook_id，在流处于打开状态时，事件将在发送到该流的同时，也会投递到所提供的 webhook。
响应： 
{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-09T16:35:08.000Z",
    "tag": "我的简介更新",
    "webhook_id": "1976325569252868099"
  }
}

​
列出订阅

检索你的应用的所有有效订阅： 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions
响应： 
{
  "data": [
    {
      "subscription_id": "1976325569252868096",
      "event_type": "ProfileBioUpdate",
      "filter": {
        "user_id": "123456789"
      },
      "created_at": "2025-10-09T16:35:08.000Z",
      "updated_at": "2025-10-10T03:50:59.000Z",
    },
    {
      "subscription_id": "1976325569252868097",
      "event_type": "ProfilePictureUpdate",
      "filter": {
        "user_id": "987654321"
      },
      "created_at": "2025-10-08T14:35:08.000Z",
      "updated_at": "2025-10-08T14:35:08.000Z",
    }
  ],
  "meta": {
    "total_subscriptions": 2
  }
}

​
删除订阅

删除一个订阅： 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X DELETE \
  https://api.x.com/2/activity/subscriptions/1976325569252868096
响应： 
{
  "data": {
    "deleted": true
  },
  "meta": {
    "total_subscriptions": 0
  }
}
total_subscriptions 显示删除操作后与你的应用关联的剩余订阅数。

​
更新订阅

通过该 PUT 端点，你可以更新订阅的投递方式或标签。 如需更新 filter 或 event_type，必须先删除现有订阅并创建一个新的订阅。 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X PUT \
  https://api.x.com/2/activity/subscriptions/1976325569252868096 \
  -d '{
    "tag": "my new tag",
    "webhook_id": "192846273860294839"
  }'
响应： 
{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-10T17:10:58.000Z",
    "tag": "my new tag",
    "webhook_id": "192846273860294839"
  },
  "meta": {
    "total_subscriptions": 1
  }
}