跳转到主要内容
此 endpoint 已更新，现包含 Post 编辑 metadata。请在”编辑 Posts” 基础知识页面了解这些 metadata 的更多信息。 此 endpoint 通常与私信相关的 endpoints 搭配使用。我们已发布新的v2 私信 endpoints。请注意，Enterprise 和 Premium 的 Account Activity API 支持 v2 一对一消息，但暂不支持群组会话。   
概览 Enterprise Account Activity API 使您能够通过 webhook（回调接口）订阅与用户账号相关的实时活动。这意味着，您可以通过单一连接，从一个或多个您拥有或已订阅的账号接收实时的 Posts、私信以及其他账号事件。 对于您在 webhook 注册中的每个用户订阅，您将收到以下所有相关活动：
活动类型
* Posts（由用户）

* Post 删除（由用户）
* @ 提及（涉及用户）
* 回复（发给用户或来自用户）
* 转发（由用户或涉及用户）
* 引用 Tweets（由用户或涉及用户）
* 对被引用 Tweets 的转发（由用户或涉及用户）
* like（由用户或涉及用户）
* 关注（由用户或涉及用户）

* 取消关注（由用户）		* 拉黑（由用户）
* 取消拉黑（由用户）
* 静音（由用户）
* 取消静音（由用户）
* 私信已发送（由用户）
* 私信已接收（由用户）
* 正在输入指示（发给用户）
* 已读回执（发给用户）
* 订阅撤销（由用户）
请注意 - 我们不会通过 Account Activity API 传递首页时间线数据。请使用 GET statuses/home_timeline 来获取这些数据。  

​
视频系列

观看我们的四集视频系列，快速了解并上手使用 Account Activity API！

​
功能摘要

等级定价唯一订阅数webhook 数量可靠性与活动恢复
Enterprise联系销售最高 500+3+重试 和 重放

​
管理 webhook（回调接口）和已订阅用户

⏱ 阅读时间 10 分钟 Enterprise 级的 Account Activity API 会在与订阅了你服务的 X 账户相关的事件发生时，通过 webhook 向你提供基于 JSON 的消息。X 会将这些活动投递到你注册的 webhook。通过以下步骤，你将学习如何管理 webhook 和已订阅用户。 你将学习如何注册、查看和移除 webhook 与已订阅用户。我们将使用简单的 cURL 命令向各个 API endpoint 发起请求。cURL 是一个使用 URL 语法进行请求与发送的命令行工具。 你需要： 在开始之前，我们建议你查看我们的 GitHub 代码库，其中提供了一个示例 Web 应用和辅助脚本，帮助你快速上手 X 的 Account Activity API

​
管理 webhook（回调接口）：

使用 webhook（回调接口）可以通过单一连接订阅与某个用户账户相关的实时活动。
  • Adding a webhook
  • Viewing a webhook
  • Removing a webhook
先在所给应用程序的 context 中注册一个新的 webhook URL。在保存前，系统会通过 CRC 请求验证该 URL。注册完成后，请务必记录 webhook ID，稍后会用到。按需替换占位符后，将以下 cURL 请求复制到命令行中运行：
  • URL <URL>，例如 https://yourdomain.com/webhooks/twitter/
  • Consumer key <CONSUMER_KEY>，例如 xvz1evFS4wEEPTGEFPHBog
  • Access token <ACCESS_TOKEN>，例如 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb 
    curl --request POST --url 'https://api.x.com/1.1/account_activity/webhooks.json?url=<URL>' --header 'authorization: OAuth oauth_consumer_key="<CONSUMER_KEY>", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="<ACCESS_TOKEN>", oauth_version="1.0"'

​
管理已订阅的用户：

注册 webhook 后，您可以将订阅用户添加到 Account Activity API，以开始接收其账户活动。
  • 添加订阅
  • 查看订阅
  • 移除订阅
我们先从为用户添加订阅开始，这样您就能接收所有事件类型。在按以下说明完成替换后，将下面的 cURL 请求复制到命令行中：
  • Webhook ID <:WEBHOOK_ID>，例如 1234567890
  • Consumer key 名称 <CONSUMER_KEY>，例如 xvz1evFS4wEEPTGEFPHBog
  • 订阅用户的 access token <SUBSCRIBING_USER'S_ACCESS_TOKEN>，例如 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb 
    curl --request POST --url https://api.x.com/1.1/account_activity/webhooks/<:WEBHOOK_ID>/subscriptions/all.json --header 'authorization: OAuth oauth_consumer_key="<CONSUMER_KEY>", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="<SUBSCRIBING_USER'S_ACCESS_TOKEN>", oauth_version="1.0"'
做得好！现在您应该能够管理 webhook 和已订阅的用户。

​
参考文章

​
Account Activity API 的视频演示

在本视频演示中，您将了解 Account Activity API 的 premium 和 Enterprise 级别所提供的功能。 观看完本视频后，您将了解以下能力：
  • 注册 webhook（回调接口）
  • 添加用户订阅
  • 移除用户订阅
  • 接收账号活动
  • 回放账号活动
Enterprise

​
webhook 入门

Account Activity API 是一种基于 webhook 的 API，会将账户事件发送到由你开发、部署并托管的 Web 应用。 在你的事件消费应用开始接收 webhook 事件之前，有若干“管道”细节需要留意。如下所述，你需要创建一个 X App，获取 Account Activity API 访问权限，并开发一个用于消费 webhook 事件的 Web 应用。 

​
1. 创建一个 X App。

  • 使用开发者门户中已获批准的开发者账户创建一个 X App。如果你代表公司创建此 App，建议使用公司的 X 账户创建。要申请开发者账户，点击此处。
  • 在你的 App 页面 permissions 选项卡中启用“Read, Write and Access Direct Messages”。
  • 在“Keys and Access Tokens”选项卡中，记录你的 App 的 Consumer Key（API Key）和 Consumer Token（API Secret）。
  • 在同一选项卡中，生成你的 App 的Access Token 和 Access Token Secret。你需要这些 Access Tokens 来注册你的 webhook（回调接口）URL，X 会将账户事件发送到该地址。
  • 如果你不熟悉 X Sign-in 以及用户上下文在 X API 中的工作方式，请查看Obtaining Access Tokens。当你添加需要接收事件的账户时，将使用该账户的 access token 为其订阅。
  • 记录你的 App 的数字 id，可在开发者门户的“Apps”页面查看。申请 Account Activity API 访问权限时需要此 App id。  

​
2. 获取 Account Activity API 访问权限

创建 X App 后，下一步是申请 Account Activity API 的访问权限。 Account Activity API 仅在 Enterprise 等级提供，因此你需要通过下方链接提交申请。

​
3. 开发 webhook 消费端 App

获得 Account Activity API 访问权限后，你需要开发、部署并托管一个用于接收 X webhook 事件的 Web 应用。 
  • 创建一个带有 URL 的 Web 应用，将其作为接收事件的 webhook。这是在你的服务器上部署的 endpoint，用于监听传入的 X webhook 事件。 
  • 如我们的Securing Webhooks指南所述，第一步是编写代码以接收 X Challenge Response Check（CRC）GET 请求，并返回格式正确的 JSON 响应。 
  • 注册你的 webhook URL。你需要向 /webhooks.json?url= endpoint 发起一次 POST 请求。当你发起该请求时，X 会向你的 Web 应用发出 CRC 请求。webhook 成功注册后，响应将包含一个 webhook id。稍后在向 Account Activity API 发起某些请求时需要该 webhook id。 
  • X 会将账号级的 webhook 事件发送到你注册的 URL。请确保你的 Web 应用支持用于接收事件的 POST 请求。这些事件采用 JSON 编码。参见此处查看示例 webhook JSON 负载。
  • 当你的 Web 应用准备就绪后，下一步是添加需要接收活动的账号。添加（或删除）账号时，你将发起引用账号 id 的 POST 请求。更多信息请参阅我们的添加订阅指南。

​
4. 验证设置

  • 要验证你的 App 和 webhook 是否配置正确，请给你的 App 订阅的某个 X 账号发布的 Post 点赞。你的 webhook URL 应该会针对你的订阅者收到的每一次点赞，通过 POST 请求接收到一个 favorite_events。
  • 请注意，添加订阅后，事件开始投递可能最多需要 10 秒。
重要说明
  • 在注册你的 webhook URL 时，你的 Web 应用必须使用其 consumer token 和 secret，且还需使用应用所有者的用户访问令牌和 secret 进行身份验证。
  • 所有传入的私信都将通过 webhook（回调接口）投递。通过 POST direct_messages/events/new (message_create) 发送的所有私信也会通过 webhook（回调接口）投递。这样你的 Web 应用才能感知由其他客户端发送的私信。
  • 请注意，每个 webhook 事件都会包含一个 for_user_id 用户 ID，指示该事件是为哪个订阅投递的。
  • 如果同一会话中有两位用户使用你的 Web 应用进行私信，你的 webhook 将会收到两条重复事件（每个用户各一条）。你的 Web 应用应对此进行处理。 
  • 如果有多个 Web 应用共享同一 webhook URL，且同一用户映射到每个应用，则同一事件会被多次发送到你的 webhook（每个 Web 应用一次）。
  • 在某些情况下，你的 webhook 可能会收到重复事件。你的 webhook 应用应具备容错能力，并按事件 ID 进行去重。
  • 不要期望 Quick Reply 的响应会直接紧随请求。用户可以忽略 Quick Reply 请求，并可能改用传统私信回复。用户也可能对此前在消息线程中未回复的请求再提供 Quick Reply 响应。
  • 查看示例代码：

​
保护 webhook（回调接口）

X 的 webhook（回调接口）类 API 提供两种方法来保障你的 webhook 服务器的安全：
  1. 通过挑战-响应校验，X 可以确认接收 webhook 事件的 Web 应用的归属。
  2. 每个 POST 请求中的签名请求头可用于验证传入的 webhook 确实来自 X。  

​
挑战-响应检查

为验证您对 App 和 webhook URL 的所有权，X 会执行 Challenge-Response Check（CRC，挑战-响应检查），请勿与循环冗余校验混淆。发送 CRC 时，X 会向您的 Web 应用发起一次带有 crc_token 参数的 GET 请求。收到该请求后，您的 Web 应用需要基于 crc_token 参数和 App 的 Consumer Secret（见下文）构建一个加密的 response_token。response_token 必须以 JSON 编码（参见下方示例）并在三秒内返回。成功后，会返回一个 webhook id。 在注册 webhook URL 时会发送 CRC，因此实现 CRC 响应代码是首要步骤。一旦建立 webhook，X 将在上次收到成功响应后大约每 24 小时触发一次 CRC。您的 App 也可以在需要时通过 webhook id 发起 PUT 请求以触发 CRC。在开发 webhook 应用、部署新代码并重启服务后，触发 CRC 十分有用。 crc_token 在每个传入的 CRC 请求中都会变化，应作为计算中的消息使用，而 Consumer Secret 作为密钥。 如果未在 3 秒内返回响应或响应无效，将停止向已注册的 webhook 发送事件。

​
CRC 请求会在以下情况下发生：

  • 注册 webhook URL 时。
  • 大约每隔_一小时_会触发一次以验证你的 webhook URL。
  • 你可以通过发送 PUT 请求手动触发 CRC。在开发 webhook 客户端时，应将手动触发 CRC 作为验证 CRC 响应的一部分进行规划。   

​
响应要求：

  • 使用 crc_token 和你的 App Consumer Secret 生成的、经 base64 编码的 HMAC SHA-256 hash
  • 有效的 response_token，且为 JSON 格式。
  • 延迟小于 3 秒。
  • 200 HTTP 状态码。  

​
各语言的 HMAC 库：

​
在 Python 中生成响应令牌的示例：

下面在一个基于 Python 2.7 的 Flask webapp 中定义了一个路由，用于正确处理挑战响应校验。 
import base64
import hashlib
import hmac
import json


\# 定义 GET 请求的路由
@app.route('/webhooks/twitter', methods=\['GET'\])
def webhook_challenge():

  # 从传入的令牌和您的消费者密钥创建 HMAC SHA-256 hash
  sha256\_hash\_digest = hmac.new(TWITTER\_CONSUMER\_SECRET, msg=request.args.get('crc_token'), digestmod=hashlib.sha256).digest()

  # 使用 base64 编码的 hash 构造响应数据
  response = {
    'response\_token': 'sha256=' + base64.b64encode(sha256\_hash_digest)
  }

  # 返回格式正确的 JSON 响应
  return json.dumps(response)

​
示例 JSON 响应：

按照上述方式定义路由后，当你在网页浏览器中访问 https://your-app-domain/webhooks/twitter?crc&#95;token=foo 时，你的 Web 应用应返回与下方类似的响应。 
{
  "response_token": "sha256=x0mYd8hz2goCTfcNAaMqENy2BFgJJfJOb4PdvTffpwg="
}

​
其他示例：

  • 此处给出了一个使用 Node/JS 编写的 CRC 响应方法示例。
  • 此处给出了一个使用 Ruby 编写的 CRC 响应方法示例（参见 generate_crc_response 以及用于接收 CRC 事件的 /GET 路由）。

​
可选的签名请求头验证

当接收来自 X 的 POST 请求、发送用于创建 webhook（回调接口）的 GET 请求，或发送用于执行手动 CRC 的 GET 请求时，请求头中会通过 x-twitter-webhooks-signature 传递一个 hash 签名。该签名可用于验证数据来源是否来自 X。POST 的 hash 签名以 sha256= 开头，表示使用 HMAC SHA-256 对你的 X App Consumer Secret 和负载进行加密。GET 的 hash 则基于 query（查询）参数字符串 crc_token=token&amp;nonce=nonce 计算得到。 验证请求的步骤
  1. 使用你的 consumer secret 和传入的负载主体创建一个 hash。
  2. 将生成的 hash 与 base64 编码的 x-twitter-webhooks-signature 值进行比较。使用类似 compare_digest 的方法以降低对计时攻击的风险。

​
其他安全指南

以下是你的 Web 应用在安全方面应额外考虑的指南。即使未实施这些指南，你的 webhook（回调接口）仍可正常工作，但 X 信息安全团队强烈建议采纳。如果你不熟悉以下建议，请咨询你的服务器管理员。

​
X 汇总网段

为提高安全性，您可以将以下汇总网段添加到允许列表（allowlist）中：
  • 199.59.148.0/22
  • 199.16.156.0/22
  • 192.133.77.0/26
  • 64.63.15.0/24
  • 64.63.31.0/24
  • 64.63.47.0/24
  • 202.160.128.0/24
  • 202.160.129.0/24
  • 202.160.130.0/24
  • 在 ssllabs.com 测试中获得“A”级
  • 启用 TLS 1.2
  • 启用 Forward Secrecy（前向保密）
  • 关闭 SSLv2
  • 关闭 SSLv3（因 POODLE 漏洞）
  • 关闭 TLS 1.0
  • 关闭 TLS 1.1
  • 关闭 TLS 压缩
  • 关闭会话票据（Session Tickets），除非你会轮换会话票据密钥。
  • 在 SSL 配置中将“ssl_prefer_server_ciphers”或“SSLHonorCipherOrder”选项设置为“on”。
  • 确保加密套件列表为现代套件，例如： ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES128-SHA256:AES128-SHA:AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:ECDHE-RSA-DES-CBC3-SHA:DES-CBC3-SHA

​
管理 webhook（回调接口）与订阅

​
创建与更改 webhook（回调接口）

若要更改 webhook URL，必须先删除现有 webhook，然后创建一个新的。请注意，这样做之后，需要将用户订阅重新添加到新的 webhook 中。

​
webhook 配置管理 endpoint：

方法Enterprise
注册 webhook URL／生成 webhook_idPOST webhooks
返回所有 webhook URL 及其 statusesGET webhooks
删除 App 当前的 webhook 配置DELETE webhooks/:webhook_id
手动触发 CRC 请求PUT webhooks/:webhook_id

​
为什么我不能直接更新 webhook URL？

为什么 webhook 配置不可变？X 对安全性极为重视。若你的 webhook URL 被更改，则有可能意味着你的应用程序的 consumer key 和 consumer secret 已遭泄露。要求你创建新的 webhook 配置，也就要求你重新为用户事件订阅。这需要使用恶意方不太可能持有的 access tokens，从而降低其他方获取你用户私密信息的可能性。  

​
添加与移除用户订阅

Enterprise 级别支持数以千计的订阅。如果您已有客户经理，请直接联系其咨询。申请访问 Enterprise API，请点击此处。 

​
订阅管理 endpoint

方法Enterprise
添加新的用户订阅POST webhooks/:webhook_id/subscriptions/all
获取用户订阅GET webhooks/:webhook_id/subscriptions/all
返回所有有效订阅的列表GET webhooks/:webhook_id/subscriptions/all/list
使用仅限应用的 OAuth 停用用户订阅DELETE webhooks/:webhook_id/subscriptions/:user_id/all.json
Account Activity API: Enterprise
请注意： 在您开始使用 API 之前，X 需要为您的开发者 App 启用对 Account Activity API 的访问。为此，请务必将您计划用于认证的 App id 与您的客户经理或技术支持团队共享。
Account Activity API 由一组 endpoint 组成，使您能够创建和管理用户订阅，并通过单一连接为您所有已订阅的账户接收实时账户活动。  Account Activity API 提供两种可用的认证方法（OAuth 1.0a 和 OAuth 2.0 Bearer Token）。您应使用的认证方法取决于所调用的 endpoint。
描述EndpointOAuth 1.0a
(用户上下文)		OAuth 2.0 Bearer Token（仅应用）
为指定的应用上下文注册新的 webhook URLPOST account_activity/webhooks✓
返回指定应用的所有 URL 及其状态GET account_activity/webhooks✓
对指定 webhook 的 URL 触发挑战响应检查（CRC）PUT account_activity/webhooks/:webhook_id✓
将应用订阅到某个用户的账户事件POST account_activity/webhooks/:webhook_id/subscriptions/all✓ *
返回当前有效订阅的数量GET account_activity/subscriptions/count✓
检查某个 webhook 配置是否已订阅某用户的事件GET account_activity/webhooks/:webhook_id/subscriptions/all✓ *
返回当前有效订阅的列表GET account_activity/webhooks/:webhook_id/subscriptions/all/list✓
删除 webhookDELETE account_activity/webhooks/:webhook_id✓
[已弃用] 为提供的用户上下文和应用停用订阅DELETE account_activity/webhooks/:webhook_id/subscriptions/all✓ *
使用仅应用 OAuth 停用订阅DELETE /account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json✓
重新向 webhook 投递活动POST /1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json✓
*_ 认证需要订阅用户的 Access Tokens。 _ 对于需要 OAuth 1.0a 用户上下文认证的 endpoint，你需要提供以下凭据以完成请求认证： 
  • Consumer Keys（API Key 和 Secret）
  • Access Tokens（Access Token 和 Secret）
对于以下三个 endpoint，你在应用的上下文中执行写操作（不涉及 X 用户）。因此，你需要提供的 Access Tokens 属于你的开发者 App。你可以直接在 developer portal 的 App“Keys and tokens”选项卡中生成这些。   另一方面，对于以下三个 endpoint，你将发起请求，使你的应用程序能够代表某位 X 用户访问受保护的 data（例如，私信）。因此，你必须提供该订阅用户的 Access Tokens。所需的 Access Tokens 可通过三方 OAuth 授权流程获取（参见 OAuth 1.0a: how to obtain a user’s Access Tokens）。这些 endpoint 在上表中已用星号（*）标注。
请注意: 请确保你的开发者 App 已启用 “Read, Write, and Direct Messages”。你可以在开发者账户的 Projects & Apps section 中所选开发者 App 的 “App permissions” 下更改此设置。更改权限后，你需要重新生成 App 凭据。
包含所有可用于 Account Activity API 的 endpoint、相关说明以及带有认证实现示例的 cURL 示例请求的列表，可在 the API reference documentation 中找到。 如需更多信息，请查看 XDev 的 sample web app and helper scripts，以开始使用 Enterprise Account Activity API。
请注意: 在开始使用 API 之前，X 需要为你的开发者 App 启用对 Account Activity API 的访问。为此，请将你用于认证的 App ID 提供给客户经理或技术支持团队。
Account Activity API 由一组 endpoint 组成，允许你创建和管理用户订阅，通过单一连接接收你所有已订阅账户的实时账户活动。 Account Activity API 提供两种认证方法（OAuth 1.0a 和 OAuth 2.0 Bearer Token）。应使用哪种认证方法取决于你调用的 endpoint。
描述EndpointOAuth 1.0a
(用户上下文)		OAuth 2.0 Bearer Token（仅应用）
为给定的应用上下文注册新的 webhook URLPOST account_activity/webhooks✓
返回给定应用的所有 URL 及其状态GET account_activity/webhooks✓
为指定 webhook 的 URL 触发挑战响应检查（CRC）PUT account_activity/webhooks/:webhook_id✓
将应用订阅到某个用户的账号事件POST account_activity/webhooks/:webhook_id/subscriptions/all✓ *
返回当前有效订阅的数量GET account_activity/subscriptions/count✓
检查某个 webhook 配置是否已订阅某用户的事件GET account_activity/webhooks/:webhook_id/subscriptions/all✓ *
返回当前有效订阅的列表GET account_activity/webhooks/:webhook_id/subscriptions/all/list✓
删除 webhookDELETE account_activity/webhooks/:webhook_id✓
[已弃用] 为所提供的用户上下文和应用停用订阅DELETE account_activity/webhooks/:webhook_id/subscriptions/all✓ *
使用仅应用 OAuth 停用订阅DELETE /account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json✓
重新投递活动到某个 webhookPOST /1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json✓
*_ 认证需要订阅用户的 Access Tokens。 _ 对于需要 OAuth 1.0a 用户上下文认证的 endpoint，你需要提供以下凭据来对请求进行认证： 
  • Consumer Keys（API Key 和 Secret）
  • Access Tokens（Access Token 和 Secret）
对于以下三个 endpoint，你在应用上下文中执行写操作（不涉及任何 X 用户）。因此，你需要提供的 Access Tokens 为你的开发者 App 所属的那些。你可以直接在 developer portal 中 App 的“Keys and tokens”选项卡下生成这些令牌。   另一方面，对于以下三个 endpoint，你将发起请求，允许你的应用代表某个 X 用户访问受保护的数据（例如，私信）。因此，必须提供该订阅用户的 Access Tokens。所需的 Access Tokens 可通过三方 OAuth 授权流程获取（参见 OAuth 1.0a：如何获取用户的 Access Tokens）。这些 endpoint 在上表中已用星号（*）标注。
请注意： 确保你的开发者 App 已启用“Read, Write, and Direct Messages”。你可以在开发者账户的 Projects & Apps 部分中，在所选开发者 App 的“App permissions”下更改此设置。更改权限设置后，你需要重新生成 App 凭证。
可用的 Account Activity API 的全部 endpoint 列表（包含相应说明以及带有身份验证实现示例的 cURL 请求示例）见API 参考文档。 如需更多信息，请查看 XDev 的示例 Web 应用和辅助脚本，以开始使用 Enterprise Account Activity API。

​
重试

Enterprise Account Activity API 的 Enterprise 级别提供的一项优势是针对 webhook 事件的重试机制。如果未收到 200“success”HTTP 响应状态码，X 服务器将启动重试机制，在五分钟内最多重试发送该 webhook 事件三次。该 webhook 事件重试服务有助于在发生网络问题、客户端服务中断或部署期间提升可靠性并实现事件恢复。  

​
什么是重试？

当客户端的 Web 应用未对账户活动 webhook 事件返回“成功”的 200 响应时，Account Activity API 会提供重试功能。当客户端未确认成功接收事件时，X 会认为该事件未被接收。如果收到非 200 响应、在三秒内未收到响应，或完全未收到响应，我们会重试该请求，并将连接保持打开三秒。这意味着在两次尝试中，你大约有五秒时间来响应，以接收我们尝试发送到你的 webhook URL 的活动。若你的服务器未响应或返回了瞬时错误，我们将持续重试五分钟。为确认验证，总共会进行三次重试。这提供了冗余和保障，确保你能接收所有 webhook（回调接口）事件。请注意，启用重试的订阅，其 webhook 上所有已订阅用户的任何/全部活动都会进行事件重试。 如果你未在这八次尝试内完成验证确认，则该活动将无法再通过 Account Activity API 获取。 

​
重试时间线

Account Activity API 会在五分钟内最多重试三次，直到收到 200 响应。有关更多详情，请参阅下表。约五分钟后，将无法通过 Account Activity API 重新发送该活动。您需要使用其他 X endpoint 来收集遗漏的 data。例如，search APIs 可用于检索相关的 Post、转发、Quote Tweets、提及和回复。遗漏的私信可通过此 endpoint检索。

​
重试时间线

活动已创建，Account Activity API 向 webhook URL 发起 POST，请求在 3 秒内超时。
在上一次超时结束后等待 3 秒，然后 Account Activity API 再次向 webhook URL 发起 POST，请求在 3 秒内超时。
在上一次超时结束后等待 27 秒，然后 Account Activity API 再次向 webhook URL 发起 POST，请求在 3 秒内超时。
在上一次超时结束后等待 242 秒，然后 Account Activity API 再次向 webhook URL 发起 POST，请求在 3 秒内超时。
此后，Account Activity API 将停止尝试 POST。客户端必须使用其他 X endpoint 来恢复 data。

​
账户活动数据对象结构

Object详情
for_user_id标识与该事件相关的订阅用户。
is_blocked_by（条件）仅当其他用户提及你所订阅的用户时显示。仅在 Post 提及事件且值为 true 时包含。
source执行动作的用户。例如，发起关注、屏蔽或静音的用户为来源用户。
target动作所作用的用户。例如，被关注、被屏蔽或被静音的用户为目标用户。
可用活动
Message Type详情
tweet_create_events当对订阅用户执行或由其执行以下任一操作时的 Post 状态负载：Posts、转发、回复、@ 提及、QuoteTweets、对 Quote Tweets 的转发。
favorite_eventslike 事件状态，包含用户与目标。
follow_events关注事件，包含用户与目标。
unfollow_events取消关注事件，包含用户与目标。
block_events屏蔽事件，包含用户与目标。
unblock_events取消屏蔽事件，包含用户与目标。
mute_events静音事件，包含用户与目标。
unmute_events取消静音事件，包含用户与目标。
user_event当用户移除应用授权且订阅被自动删除时发送的撤销事件。
direct_message_events当发送或接收私信时，包含用户与目标的私信状态。
direct_message_indicate_typing_events私信“正在输入”事件，包含用户与目标。
direct_message_mark_read_events私信“标记已读”事件，包含用户与目标。
tweet_delete_events删除 Post 的通知，便于维护合规性。
负载示例 请参见下方针对上述表格中每个账户活动事件的负载示例。

​
tweet_create_events（Posts、转发、回复、引用推文）

{
	"for_user_id": "2244994945",
	"tweet_create_events": [
	  {
		<Tweet 对象>
	  }
	]
}

​
tweet_create_events（@提及）

{
	"for_user_id": "2244994945",
	"user_has_blocked": "false",
	"tweet_create_events": [
	  {
		<Tweet 对象>
	  }
	]
}

​
favorite_events

{
	"for_user_id": "2244994945",
	"favorite_events": [{
		"id": "a7ba59eab0bfcba386f7acedac279542",
		"created_at": "Mon Mar 26 16:33:26 +0000 2018",
		"timestamp_ms": 1522082006140,
		"favorited_status": {
			<Tweet 对象>
		},
		"user": {
			<用户对象>
		}
	}]
}

​
follow_events

{
	"for_user_id": "2244994945",
	"follow_events": [{
			"type": "follow",
			"created_timestamp": "1517588749178",
			"target": {
				<用户对象>
			},
			"source": {
				<用户对象>
			}
		]
	}
}

​
unfollow_events

{
	"for_user_id": "2244994945",
	"follow_events": [{
			"type": "unfollow",
			"created_timestamp": "1517588749178",
			"target": {
				<用户对象>
			},
			"source": {
				<用户对象>
			}
		]
	}
}

​
block_events

{
	"for_user_id": "2244994945",
	"block_events": [{
		"type": "block",
		"created_timestamp": "1518127020304",
		"source": {
			<用户对象>
		},
		"target": {
			<用户对象>
		}
	}]
}

​
unblock_events

{
	"for_user_id": "2244994945",
	"block_events": [{
		"type": "unblock",
		"created_timestamp": "1518127020304",
		"source": {
			<用户对象>
		},
		"target": {
			<用户对象>
		}
	}]
}

​
mute_events

{
	"for_user_id": "2244994945",
	"mute_events": [
		{
			"type": "mute",
		  	"created_timestamp": "1518127020304",
			"source": {
				<用户对象>
			},
			"target": {
				<用户对象>
			}
		}
	]
}

​
unmute_events

{
	"for_user_id": "2244994945",
	"mute_events": [
		{
			"type": "unmute",
		  	"created_timestamp": "1518127020304",
			"source": {
				<用户对象>
			},
			"target": {
				<用户对象>
			}
		}
	]
}

​
user_event

{
	"user_event": {
		"revoke": {
			"date_time": "2018-05-24T09:48:12+00:00",
			"target": {
				"app_id": "13090192"
			},
			"source": {
				"user_id": "63046977"
			}
		}
	}
}

​
direct_message_events

{
  	"for_user_id": "4337869213",
	"direct_message_events": [{
		"type": "message_create",
		"id": "954491830116155396",
		"created_timestamp": "1516403560557",
		"message_create": {
			"target": {
				"recipient_id": "4337869213"
			},
			"sender_id": "3001969357",
			"source_app_id": "13090192",
			"message_data": {
				"text": "Hello World!",
				"entities": {
					"hashtags": [],
					"symbols": [],
					"user_mentions": [],
					"urls": []
				}
			}
		}
	}],
	"apps": {
		"13090192": {
			"id": "13090192",
			"name": "FuriousCamperTestApp1",
			"url": "https://x.com/furiouscamper"
		},
		"users": {},
		"3001969357": {
			"id": "3001969357",
			"created_timestamp": "1422556069340",
			"name": "Jordan Brinks",
			"screen_name": "furiouscamper",
			"location": "Boulder, CO",
			"description": "Alter Ego - X PE opinions-are-my-own",
			"url": "https://t.co/SnxaA15ZuY",
			"protected": false,
			"verified": false,
			"followers_count": 22,
			"friends_count": 45,
			"statuses_count": 494,
			"profile_image_url": "null",
			"profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg"
		},
		"4337869213": {
			"id": "4337869213",
			"created_timestamp": "1448312972328",
			"name": "Harrison Test",
			"screen_name": "Harris_0ff",
			"location": "Burlington, MA",
			"protected": false,
			"verified": false,
			"followers_count": 8,
			"friends_count": 8,
			"profile_image_url": "null",
			"statuses_count": 240,
			"profile_image_url_https": "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png"
		}
	}
}

​
direct_message_indicate_typing_events

{
	"for_user_id": "4337869213",
	"direct_message_indicate_typing_events": [{
		"created_timestamp": "1518127183443",
		"sender_id": "3284025577",
		"target": {
			"recipient_id": "3001969357"
		}
	}],
	"users": {
		"3001969357": {
			"id": "3001969357",
			"created_timestamp": "1422556069340",
			"name": "Jordan Brinks",
			"screen_name": "furiouscamper",
			"location": "Boulder, CO",
			"description": "Alter Ego - X PE opinions-are-my-own",
			"url": "https://t.co/SnxaA15ZuY",
			"protected": false,
			"verified": false,
			"followers_count": 23,
			"friends_count": 47,
			"statuses_count": 509,
			"profile_image_url": "null",
			"profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg"
		},
		"3284025577": {
			"id": "3284025577",
			"created_timestamp": "1437281176085",
			"name": "Bogus Bogart",
			"screen_name": "bogusbogart",
			"protected": true,
			"verified": false,
			"followers_count": 1,
			"friends_count": 4,
			"statuses_count": 35,
			"profile_image_url": "null",
			"profile_image_url_https": "https://pbs.twimg.com/profile_images/763383202857779200/ndvZ96mE_normal.jpg"
		}
	}
}

​
direct_message_mark_read_events

{
	"for_user_id": "4337869213",
	"direct_message_mark_read_events": [{
		"created_timestamp": "1518452444662",
		"sender_id": "199566737",
		"target": {
			"recipient_id": "3001969357"
		},
		"last_read_event_id": "963085315333238788"
	}],
	"users": {
		"199566737": {
			"id": "199566737",
			"created_timestamp": "1286429788000",
			"name": "Le Braat",
			"screen_name": "LeBraat",
			"location": "Denver, CO",
			"description": "白天在 @X 处理数据，黄昏时做设计",
			"protected": false,
			"verified": false,
			"followers_count": 299,
			"friends_count": 336,
			"statuses_count": 752,
			"profile_image_url": "null",
			"profile_image_url_https": "https://pbs.twimg.com/profile_images/936652894371119105/YHEozVAg_normal.jpg"
		},
		"3001969357": {
			"id": "3001969357",
			"created_timestamp": "1422556069340",
			"name": "Jordan Brinks",
			"screen_name": "furiouscamper",
			"location": "Boulder, CO",
			"description": "另一个自我 - X PE 个人观点",
			"url": "https://t.co/SnxaA15ZuY",
			"protected": false,
			"verified": false,
			"followers_count": 23,
			"friends_count": 48,
			"statuses_count": 510,
			"profile_image_url": "null",
			"profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg"
		}
	}
}

​
tweet_delete_events

{
    "for_user_id": "930524282358325248",
    "tweet_delete_events": [
{
        "status": {
            "id": "1045405559317569537",
            "user_id": "930524282358325248"
        },
        "timestamp_ms": "1432228155593"
    }
   ]
}

​
Account Activity Replay API

Enterprise Account Activity Replay API 是一款数据恢复工具，可用于检索最久可回溯至五天前的事件。应在你的 webhook 服务器错过事件时使用——无论是由于断连时间超过 retry window，还是在需要数天时间将系统恢复至正常状态的灾难恢复场景中。 Account Activity Replay API 面向在一段时间内未能摄取 activities 的任何场景。它会将活动投递到与原始实时投递相同的 webhook。这是一款恢复工具而非回填工具，这意味着仅当先前曾尝试投递某事件时，该事件才会被重放。Account Activity Replay API 无法投递订阅创建时间之前时段的事件。

​
使用 Account Activity Replay API

如果你的账号已启用 Replay 功能，你可以以与调用 Account Activity API 类似的方式发起请求。需要特别注意，你的请求必须指定 webhook 的 id 参数，以表明你希望回放哪个 webhook 的活动。换言之，Replay 请求会根据 webhook id 和 application id，要求 Account Activity Replay API 在指定的起止日期与时间范围内检索事件。 请注意需使用 UTC 时间。这些活动将通过与该 id 关联的已注册 webhook 投递，速率最高可达每秒 2,500 个事件。另请留意，同一时间每个 webhook 只能运行一个 Replay 任务；不过，在该 webhook 上于所指定日期/时间范围内处于活跃状态的所有订阅都会被回放。 事件投递将从指定时间段内最早的那一分钟开始，按时间顺序（尽可能）持续，直至最后一分钟投递完成。届时，Replay 会向该 webhook 发送作业完成事件。由于活动按时间顺序投递，如果在开始时间附近匹配结果很少或没有，首次结果投递前很可能会有一段等待时间。

​
限制

Replay 旨在作为一种便于将活动回溯至最多五天前的工具，但不会提供早于订阅创建时间的事件。例如，如果你在三天前添加了一个新订阅，并运行了一个回溯至今天前五天的 Replay 任务，你只会收到该新订阅生效后的这三天的数据。

​
数据可用性和类型

Account Activity Replay API 的活动数据自请求发起之时起可保留 5 天，新数据通常在某项活动创建约 10 分钟后可用。您可以在这 5 天的时间窗口内，通过请求中的 from_date 和 to_date 参数指定时间范围。在获得 Replay 访问权限之前已投递的事件无法重放。例如，如果您的帐户在 2019 年 6 月 1 日 UTC 时间 15:30 获得了 Account Activity Replay API 的访问权限，您将无法使用 Replay 检索该日期时间之前的任何事件。 继续查看 Account Activity Replay API 参考

​
迁移介绍

我们已于 2018 年停用 Site Streams、User Streams，以及 Account Activity API - DM Only 的标准测试版产品。如果您曾使用这些产品，请务必迁移到 Account Activity API 的 premium 或 Enterprise 版本。 我们也已停用旧版私信（Direct Message）endpoint。如果您曾使用这些 endpoint，请务必迁移到新的 DM endpoint，或迁移到 Account Activity API 的 premium 或 Enterprise 版本。 请查看此公告了解更多信息。 以下 endpoint 将受到这些变更的影响：
  • User Streams
  • Site Streams
  • GET direct_messages
  • GET direct_messages/sent
  • GET direct_messages/show
  • POST direct_messages/new
  • POST direct_messages/destroy  
我们提供了新的 endpoint 和服务，能够提供类似的访问能力，并且针对私信（Direct Messages）还提供了一些额外功能： 为帮助您顺利迁移到这些新的 endpoint 和服务，我们提供了两份迁移指南： 另外，我们还提供了一套关于 Account Activity API 及其入门方法的视频系列。 最后，我们还提供了代码示例，以加深理解并帮助您快速上手：
  • Account Activity Dashboard 是一个示例 Node.js Web App，包含用于开始使用 Account Activity API 的辅助脚本。
  • SnowBot 是一个使用 Account Activity API 和 REST 私信 endpoint 的示例聊天机器人。它由 Ruby 编写，采用 Sinatra Web App 框架，并部署在 Heroku 上。

​
迁移指南：从 User Streams/Site Streams 迁移到 Account Activity API

自 2018 年 8 月 23 日起，我们已下线 Site Streams 和 User Streams。请务必迁移至 Account Activity API。 请查看该公告以了解更多信息。 本指南旨在帮助您将遗留的 User Streams 和 Site Streams API 迁移到其替代方案 Account Activity API。下文提供了变更摘要、新功能列表，以及有助于过渡的关键差异与注意事项。如需从基础 DM endpoint 迁移的指导，请参阅Direct Message 迁移指南。

​
变更摘要

与 User Streams 和 Site Streams 这类流式连接不同，Account Activity API 将通过 webhook（回调接口）向已通过认证并已订阅的账户传递事件。

​
已弃用的 API

GET user GET site（包括控制 stream：GET site/c/:stream_id、GET site/c/:stream_id/info.json、GET site/c/:stream_id/friends/ids.json、POST site/c/:stream_id/add_user.json、POST /site/c/:stream_id/remove_user.json）

​
替代方案 API

Enterprise Account Activity API - 全部活动

​
差异与迁移注意事项

API 格式： 新的 Account Activity API 与 User Streams 和 Site Streams 的运作方式不同。你需要修改你的 Web 应用，以通过 webhook（回调接口）接收 data。有关 webhook 的更多信息请参见此处。 可用数据： 你会注意到的另一个关键差异在于所传递的数据。X 将不再发送你在 X 上关注的用户的事件（即你的首页时间线）。这是有意的更改，我们目前不计划调整。 可靠性： 与 stream 不同，webhook 支持送达确认，并可对未到达 webhook URL 的已 POST 的活动进行重试。即便出现短暂的断连或停机，也能更有把握确保 App 接收到所有相关活动。

​
新功能

Account Activity API 引入了许多新功能，其中最显著的是现在通过 webhook（回调接口）而非 stream 交付数据。与 stream 相比，webhook 的优势众多，最突出的在于速度与可靠性。API 会在 JSON 事件就绪时将 data 发送给你，你无需再维持持续连接或轮询该 endpoint。这样可以减少对冗余机制的依赖，并整体提升效率。有关 webhook 的更多信息，请参阅技术文档。

​
管理用户订阅

Account Activity API 允许在单个已注册的 webhook（回调接口）上设置多个订阅。这样，多个用户订阅的活动就能通过 webhook 发送到同一位置，类似于 Site Streams 架构。也就是说，你可以在不依赖 webhook 连接的前提下，独立地根据订阅配额跟踪各项订阅。这同样便于扩展：单个 webhook 可从只有一个或少量订阅扩展到成千上万个订阅。

​
迁移指南

​
按照以下步骤，轻松从 Site Streams API 迁移到 Account Activity API

步骤 1：选择套餐 根据你当前使用 User Streams 或 Site Streams 的方式，考虑迁移到 Account Activity API 的 Enterprise 或 Premium 版本。请结合你当前支持的应用或已授权用户数量进行评估，并按所需的数据量与可靠性进行相应扩容。在选择最适合你需求的套餐时，需要重点考虑以下因素：
  • 所需的 webhook 数量
  • 你的应用当前/预期管理的订阅/已授权用户
  • 当前的 X 客户端应用数量
  • 你期望从 X 获得的支持级别（论坛支持或托管式 Enterprise 级 1:1 支持）
  • 各套餐价格
步骤 2： 在开发者门户检查你的 X App 设置 当前用于 User Streams 或 Site Streams 的 X app 会在开发者门户中列在其所属用户名下。此 X app 也可用于 Account Activity API，从而保留该应用的已授权用户。你也可以创建一个新的 App，并在需要时让用户为这个新的 App 重新授权。如果你代表企业创建新 App，建议使用公司的 X @handle 账号创建该 App。
  • 在你的 X App 页面上的 permissions 选项卡中启用“Read, Write and Access direct messages”。 请注意，更改这些设置不会追溯生效，任何已授权用户将保留其被授权时的授权设置。如果某位用户尚未授予你读取、写入和私信访问权限，你需要让该用户重新授权你的应用。
  • 如果你不熟悉 X Sign-in 以及用户上下文如何与 X API 协同工作，请查看Obtaining Access Tokens。
  • 在“Keys and Tokens”选项卡底部为 X App 所有者生成 Access Tokens。在同一选项卡中记下你的 Consumer Key、Consumer Secret、Access Token 和 Access Token Secret。你需要这些来使用 API。
  • 使用你的 Consumer Key 和 Consumer Secret 生成 Bearer Token，以用于application-only API 方法。
步骤 3：设置并配置你的 webhook
  • 创建一个带有 endpoint 的 Web 应用，将其用作 webhook 接收事件（例如：https://your&#95;domain.com/webhook/twitter 或 https://webhooks.your&#95;domain.com）。
  • 在创建 webhook 时使用你的 Consumer Key、Consumer Secret、Access Token 和 Access Token Secret。注意，你的 endpoint 必须返回一个包含 response_token 的 JSON 响应；该 response_token 是使用 crc_token 和你的 App Consumer Secret 生成的、经 base64 编码的 HMAC SHA-256 hash。
  • 查看 Securing Webhooks 文档，特别留意 Challenge Response Check（CRC）的要求。
  • 确保你的 webhook 支持用于接收事件的 POST 请求，以及用于 CRC 的 GET 请求。
  • 确保你的 webhook 具备低延迟（对 POST 请求的响应小于 3 秒）。
步骤 4：验证你的 webhook 设置
  • Webhook API 将通过两种方式保护你的 webhook：
               - 要求进行挑战响应检查，以验证 webhook 所有者即 Web 应用所有者。                - 在每个 POST 请求中包含一个签名请求头，供你的 Web 应用验证来源。
  • 为了验证你同时是 Web 应用和 webhook URL 的所有者，X 将执行 Challenge Response Check（CRC），这与循环冗余校验不同。
  • 一个带有名为 crc_token 的参数的 GET 请求将被发送到你的 webhook URL。你的 endpoint 必须返回一个包含 response_token 的 JSON 响应；该 response_token 是使用 crc_token 和你的 App Consumer Secret 生成的、经 base64 编码的 HMAC SHA-256 hash。
  • 应预期每个传入的 CRC 请求其 crc_token 都会变化。计算时应将 crc_token 作为消息，其中你的 Consumer Secret 作为密钥。
  • 如果响应无效，将停止向已注册的 webhook 发送事件。
步骤 5：为每个 User Stream 或 Site Streams 的已授权用户创建订阅 从 User Streams 迁移到 Account Activity API：
  • 生成你在 User Streams 上的当前用户订阅列表
  • 使用请求：  POST account_activity/all/:env_name/subscriptions 设置新的 Account Activity API 订阅
  • 使用请求：  GET account_activity/all/:env_name/subscriptions/list 确认你的 Account Activity API 订阅
从 Site Streams 迁移到 Account Activity API（使用控制流）：
  • 使用请求：  GET /1.1/site/c/:stream_id/info.json 生成你在 Site Streams 上的当前订阅列表
  • 使用请求：  POST account_activity/all/:env_name/subscriptions 设置新的 Account Activity API 订阅
  • 使用请求：  GET account_activity/all/:env_name/subscriptions/list 确认你的 Account Activity API 订阅
注册 webhook 并创建订阅（非从 Site Streams 或 User Streams 迁移）

​
Account Activity 仪表板（Account Activity API 示例应用）

我们创建了一个示例 App，帮助更高效地测试 Account Activity API：   
  • 在这里下载 Account Activity Dashboard 示例应用（基于 Node.js）
  • 按照 README 的说明安装并启动该应用
  • 应用启动后，您可以通过 UI 轻松设置 webhook（回调接口）并创建新订阅

​
可用活动

消息类型详情
tweet_create_events当订阅用户发起或收到以下任一操作时的 Post 状态负载：Post、转发、回复、@提及、QuoteTweets
favorite_events收藏（like）事件状态，包含用户与目标。
follow_events关注事件，包含用户与目标。
block_events屏蔽事件，包含用户与目标。
mute_events静音事件，包含用户与目标。
direct_message_events私信事件状态，包含用户与目标。
direct_message_indicate_typing_events私信“正在输入”事件，包含用户与目标。
direct_message_mark_read_events私信“标记为已读”事件，包含用户与目标。

​
已弃用的流式消息类型 

空行Account Activity API 将不再传递空行；此前在 User Streams 和 Site Streams 中，空行被用作保活消息。
限制通知将不再向指定的 webhook（回调接口）发送限制通知。相应地，用户可调用 API 获取可用句柄的当前使用情况。此功能未来将纳入开发者门户。
断开连接消息不再需要断开连接通知，因为 webhook（回调接口）不依赖活动连接。
阻塞警告不再需要阻塞警告，因为 webhook（回调接口）不依赖能够处理大量传入消息的活动连接。
好友列表将不再主动发送好友列表。现在将提供一个 REST endpoint 以获取该信息。

​
已弃用的事件类型

描述事件名称来源目标目标对象
用户删除一条 Postdelete当前用户当前用户Post
被关注用户删除一条 Postdelete被关注用户被关注用户Post
用户取消收藏一条 Postunfavorite当前用户Post 作者Post
用户的 Post 被取消收藏unfavorite取消收藏的用户当前用户Post
用户取消关注某人unfollow当前用户被关注用户Null
用户创建一个 Listlist_created当前用户当前用户List
用户删除一个 Listlist_destroyed当前用户当前用户List
用户编辑一个 Listlist_updated当前用户当前用户List
用户将某人添加到 Listlist_member_added当前用户被添加用户List
用户被添加到某个 Listlist_member_added添加用户当前用户List
用户将某人从 List 中移除list_member_removed当前用户被移除用户List
用户被从某个 List 中移除list_member_removed移除用户当前用户List
用户订阅某个 Listlist_user_subscribed当前用户List 所有者List
用户的 List 被订阅list_user_subscribed订阅用户当前用户List
用户取消订阅某个 Listlist_user_unsubscribed当前用户List 所有者List
用户的 List 被取消订阅list_user_unsubscribed取消订阅用户当前用户List
用户更新其个人资料user_update当前用户当前用户Null
用户更新其受保护状态user_update当前用户当前用户Null

​
私信迁移指南

我们已于 2018 年 9 月 17 日停用旧版私信 endpoint。 如果你此前使用这些 endpoint，请务必迁移至新的私信 endpoint 或 Account Activity API。 请查看此公告以了解更多信息。 本指南旨在帮助你从旧版私信 REST API 迁移到已脱离测试阶段的增强替代方案。下方提供了变更摘要、新功能清单，以及关键差异与注意事项，助你顺利完成迁移。新的私信 endpoint 现已向所有开发者开放。关于从 User Streams 或 Site Streams 迁移的指导，请参阅Account Activity API 迁移指南。

​
变更摘要

如果你仍在使用以下 DM endpoint，则需要迁移到较新的 endpoint。
已弃用的 endpoint迁移后的替代方案
POST direct_messages/newPOST direct_messages/events/new
GET direct_messages/showGET direct_messages/events/show
GET direct_messagesGET direct_messages/events/list
GET direct_messages/sentGET direct_messages/events/list
POST direct_messages/destroyDELETE direct_messages/events/destroy

​
新增功能

新的私信 API endpoints 支持多项新能力，并改进了对历史私信的访问。新增功能包括：
  • 支持媒体附件（图片、GIF 和视频）。
  • 可通过预设选项列表引导用户进行结构化回复。
  • 可访问过去最长 30 天的私信。
有关新的私信功能完整列表以及更多新增 API endpoints，请参阅技术文档。  

​
差异与迁移注意事项

新的 API endpoint 与先前版本有显著差异。仅更新 endpoint 的 URL 会导致应用发生错误。在为迁移更新应用时，请注意以下事项。

​
新的私信对象

您首先可能会注意到的是私信的全新对象结构。这个新的 Message Create 对象结构旨在支持诸如快速回复和附件等新功能。新的对象还包含一个更小、更精简的用户对象。您的应用需要更新，以在解析时适配这一新的对象结构，并可能相应调整数据模型或存储。有关各属性的说明，请参阅Message Create 对象的完整文档。 示例 Message Create 对象 
{
      "type": "message_create",
      "id": "1234858592",
      "created_timestamp": "1392078023603",
      "initiated_via": {
        "tweet_id": "123456",
        "welcome_message_id": "456789"
      },
      "message_create": {
        "target": {
          "recipient_id": "1234858592"
        },
        "sender_id": "3805104374",
        "source_app_id": "268278",
        "message_data": {
          "text": "蓝鸟",
          "entities": {
            "hashtags": [],
            "symbols": [],
            "urls": [],
            "user_mentions": [],
          },
          "quick_reply_response": {
            "type": "options",
            "metadata": "external_id_2"
          },
          "attachment": {
            "type": "media",
            "media": {
             ...
            }
          }
        }
      }

​
摘要

  • 全新的 Direct Message 对象结构。
  • 更精简的用户对象。
  • 新增信息（快速回复响应、附件等）。

​
发送私信

POST direct_messages/events/new 是用于发送私信的直接替代。与该 endpoint 相关的最大变化是，所有信息现在都以 JSON 的形式放在 POST 请求正文中发送，而不是作为单独的 POST 参数。 Twurl 请求示例 
twurl -A 'Content-type: application/json' -X POST /1.1/direct\_messages/events/new.json -d '{"event": {"type": "message\_create", "message\_create": {"target": {"recipient\_id": "4534871"}, "message_data": {"text": "Hello World!"}}}}'
请注意，在上述请求中，Content-Type 被设置为 application/json，而非 application/x-www-form-urlencoded。此外，如果你在构建 OAuth 1.0a 签名，请注意 JSON 请求体不参与签名生成。大多数 OAuth 库已考虑到这一点。如果你使用 twurl，请确保使用的版本不低于 0.9.3。

​
摘要

  • 消息在 JSON 的 POST 请求主体中定义
  • 必须将 Content-Type 标头设置为 application/json
  • 生成 OAuth 签名时不包含 JSON 主体。  

​
检索私信

现在可通过单一 API endpoint 检索历史私信：GET direct_messages/events/list。此新 endpoint 的显著变化在于，它按时间倒序返回已发送和已接收的消息，有助于重建会话。不过，如果您只需要已发送或已接收的消息，则需参考 sender_id 属性对响应进行后处理。 分页现基于游标值，而非某条私信的 id。每个响应都会返回一个游标属性。GET direct_messages/events/list 最多返回过去 30 天内的消息，不论过去 30 天内的消息数量如何。当未返回游标时，表示没有更多可返回的消息。使用 GET direct_messages/events/show 访问单条私信的方法保持不变，但返回的私信对象结构与之前描述的不同。 最后，对私信的实时访问现通过 webhook（回调接口）结合 Account Activity API 实现。关于从 User Streams 或 Site Streams 迁移的指南，请参阅迁移到 Account Activity API 的文档以获取更多信息。

​
摘要

  • 现已通过同一 endpoint 返回已发送与已接收的消息。
  • 可返回最长 30 天内的消息。
  • 支持基于游标的分页。
  • 通过 webhook（回调接口）实时访问私信。

​
删除私信

现在可以使用 DELETE direct_messages/events/destroy 删除私信。接口基本保持不变，仍需提供要删除消息的 id。主要区别在于，该 endpoint 现在需要发送 DELETE 请求，而非 POST 请求。 已删除私信在官方 X 客户端中的表现保持不变。私信只会从所提供用户 context 的界面中移除，会话中的其他成员仍可访问该私信。

​
摘要

  • 删除私信需要提供 id。
  • 新的 endpoint 需要使用 DELETE 请求。
  • 已删除私信在 X 官方客户端中的呈现方式保持不变。
关于迁移到新的私信 endpoint 的问题？ 请在开发者社区论坛 devcommunity.com 提交你的问题。

​
常见问题解答

​
常见问题

使用 Account Activity API 有哪些优势？ Account Activity API 使用 webhook（回调接口）。这意味着，与 streaming API 不同，你无需保持一个始终打开的连接来接收我们发送的信息。Webhook 也不同于 REST API，你无需每 15 分钟轮询我们数百次来获取关心的数据。它会在事件发生时推送数据，从而提升用户与您的 App 之间的效率。 Account Activity API 具有以下优势：
  1. 速度：我们以 X 的速度传递数据。
  2. 简单：我们通过单一的 webhook 连接传递一个账户的所有事件。API 中包含的活动有：Posts、@ 提及、回复、转发、引用推文、对引用推文的转发、like、发送的私信、收到的私信、关注、拉黑、静音。
  3. 可扩展性：你可以接收所管理账户的全部活动，而不受任何请求速率限制或事件上限的约束。
Account Activity API 提供 premium sandbox、付费 premium 和 enterprise 方案，因此当你需要更多账户用于合规功能或附加功能时，可以按需扩展。 开始使用，请从 GitHub 下载示例代码片段。   我如何确定哪个产品层级最适合我？ 请阅读我们的 Account Activity API 概览 页面，了解 Premium 选项与 Enterprise 选项之间的差异。    Premium 环境与 Enterprise webhook 有什么区别？ 没有区别。每个 Premium 环境都会有自己的 webhook_id。   我需要为 Account Activity API 准备开发、预发布和生产环境，这可行吗？ 可以！在 Account Activity API 的付费层级（付费 Premium 和 Enterprise）中，可以注册多个 webhook URL，并通过 API 方法分别管理每个环境的订阅。此外，可以将多个客户端应用添加到 allowlist 中，以维护你当前已授权用户的授权状态。   是否有关于如何设置 Account Activity API 的分步指南？ 当然有！
  • 如果你刚刚起步，我们建议你查看使用 webhook 入门指南
  • 参考我们的 X Dev 支持脚本：
    • Account Activity API dashboard，一个用于展示 webhook 事件的 Node Web 应用。
    • SnowBot chatbot，一个基于 Account Activity 和 Direct Message APIs 构建的 Ruby Web 应用。该代码库包含一个脚本，用于帮助设置 Account Activity API webhooks。  
如果我们的系统在一段时间内宕机，是否有办法恢复数据？ 在 Account Activity API 的付费层级（付费 Premium 和 Enterprise）中，我们的系统会在四小时内重试多次向你发送活动。如果你的系统在这四小时内未响应，则该活动将丢失，你需要在 7 天内使用其他 REST endpoint 恢复数据。 我们建议将不同的 webhooks 或环境作为冗余手段，例如使用 Account Activity Replay API，以确保当你的某个系统宕机时不会错过任何活动。   使用 Account Activity API 需要什么身份验证？ Account Activity API 所需的授权方式在API 参考页面中按方法进行了说明。如果你刚开始接触 X 的身份验证，我们建议你阅读此部分。 什么是质询-响应校验（CRC）？ Account Activity API 的挑战响应检查是一项安全功能，用于确保 Account Activity API 的活动被发送给正确的开发者。开发者也可借此确认其接收的 data 来自 X。自上次验证 webhook URL 起，X 将每 24 小时自动向你的 webhook URL 发送一次 CRC。你的系统必须在 3 秒内返回有效响应以保持验证状态。  请访问我们的页面 Securing webhooks 了解更多详情。   是否存在会立即使我的 webhook URL 失效的情况？ 如果发生以下任一情况，我们将立即将你的 webhook 标记为无效：
  • 服务器对 CRC 返回了不正确的令牌。在这种情况下，我们的系统不会重试向你发送活动。
  • webhook URL 配置了不正确的证书。在这种情况下，我们的系统不会重试向你发送活动。
  • 你的服务器返回非 2XX、非 4XX、非 5XX 的响应码。
  • 你声明使用 gzip，但实际未发送。
  • 你未声明使用 gzip，但在响应中实际发送了它。  
如果订阅了彼此互动的用户，我会收到重复的活动吗？ 会的。若你的 Web 应用对用户 A 和用户 B 都有有效订阅，且用户 A 在一条 Post 中提及了用户 B，那么将会向注册的 webhook 发送两条 POST 活动。每条活动都会包含一个 “for_user_id” 指示器，用于标明该活动属于哪个订阅。  当我向我的 webhook 发起订阅时，能否将以下 endpoint 中的 /all/ 部分替换为其他账户活动数据对象，以限制 API 交付的活动？POST https://api.x.com/1.1/account_activity/all/:env_name/subscriptions.json 不可以。目前我们仅提供 /all/ 产品。   有没有办法在不向用户请求私信权限的情况下使用 Account Activity API？ 目前需要私信权限，因为该 API 无法“过滤掉”私信活动。    Account Activity API 是否有免费版本？ 有的，我们提供沙盒版本作为免费层。我们的沙盒选项限制为单个 webhook，最多 15 个订阅。你可以在我们的文档中了解有关沙盒选项的更多信息。  能否使用 Account Activity API 获取提及已订阅用户的 Post 的转发？ 很遗憾，这不在该 API 提供的活动范围内。为此，我们建议改用 Streaming API。    tweet_create_event 可能代表哪些活动类型？ 在以下情况下会发送 tweet_create_event 负载： 如果订阅用户执行以下任一操作：
  • 创建 Post
  • 转发
  • 回复 Post
如果其他用户：
  • @提及 订阅用户
  • 引用订阅用户创建的 Tweet 
注意：Account Activity API 仅在订阅用户会从 X 收到通知且能够公开看到该事件时才会传递事件。这意味着，如果被提及的账户（@userA）关注了受保护的账户（@userB），则 UserA 会收到 UserB 提及他们的通知。如果 UserA 未关注 UserB（且未被 UserB 批准），UserA 将不会收到通知，因此如果 @userA 已订阅，则不会通过 AAA 发送 tweet_create_event。 如果被屏蔽的用户提及了我订阅的用户，我如何识别？ 你将在 JSON 响应的顶层看到一个布尔字段 user_has_blocked，其值为“true”或“false”。该字段仅在 Post 提及中暴露。  Enterprise 如何将我的 App 添加到 allowlist，或检查我的 App 是否已在 allowlist 上？ 要管理你已添加到允许列表、可通过 Enterprise API 访问的 X apps，请联系你的客户经理并提供你的 app ID。你可以在开发者门户的 “Apps” 页面找到你的 app ID。   如果我有三个 webhook 的访问权限，我能否为我注册为企业用途的每个 App 各使用三个 webhook？ webhook 限额是在账户级别设置的，而不是 App 级别。如果你有三个 webhook 的访问权限，并且有两个注册为企业用途的 App，你可以在一个 App 上使用两个 webhook，在另一个 App 上使用第三个，但不能在每个 App 上都使用三个。  我能否指定将使用 Account Activity Replay API 重新投递的事件类型？ 要重放的事件类型不可指定。将在所指定的日期和时间窗口内投递的所有事件都会被重放。  如果我的应用未能摄取某个 Account Activity Replay API 事件，是否会进行重试？ 不会，不会进行任何重试。如果应用未能摄取由 Account Activity Replay API 发送的事件，可以为相同的时间段提交另一个 Replay 作业，以尝试重新投递遗漏的 Replay 事件。  当我收到部分成功的完成事件时，我应该怎么做？ 建议记录已接收事件的时间戳，并为遗漏的事件请求另一个 Replay 作业。  我一次最多可以运行多少个 Account Activity Replay API 作业？ 每个 webhook 在同一时间只能运行一个 Account Activity Replay API 作业。  在事件被投递到我的 webhook 时，我如何区分 Account Activity Replay API 事件与实时生产事件？ 由于 Account Activity Replay API 始终投递过去的事件，因此可以根据事件的时间戳将其与实时生产事件区分开来。  我最早何时可以使用 Account Activity Replay API 来重新投递我的应用丢失或遗漏的活动？ 活动在创建约 10 分钟后可用于重新投递。 

​
错误故障排查指南

​
代码 32

此错误通常表示你在指定的请求、headers、authorization 或 URL 中的某处存在格式不正确的内容。这不是 Account Activity API 的错误，而是授权错误，X 未获取到正确的 OAuth 配置或 URL。
  • Enterprise - 请确保你使用的 consumer keys 和 access tokens 隶属于已注册使用 Enterprise 产品的 X app。如果你没有 consumer keys 和 access tokens，或需要将你的 X app 加入 allowlist，请联系你的客户经理。 
  • 如果以用户 context 进行认证，请确保你已使用正确的 oauth nonce、oauth_signature 和 oauth_timestamp 授权你的请求。
  • 请确保你的 access tokens 具备正确的权限级别。
    • 在 app dashboard 的“Keys and tokens”选项卡中，请确认你的 access tokens 拥有“Read, write, and direct messages”的 permission level。 
    • 如果 tokens 的权限级别低于此，请转到“Permissions”选项卡，将访问权限调整为“Read, write, and direct messages”，然后在“Keys and tokens”选项卡中重新生成你的 access tokens 和 secret。
  • 请确保你的 URL 构造正确。
    • 请注意，:env_name 区分大小写。  

​
代码 200 - 禁止

  • Premium - 在尝试向 API 发起请求之前，请确保您拥有已获批准的开发者账户。您还必须在请求中使用正确的 :env_name，您可以在 dev environments 页面进行设置。
  • Enterprise - 请确保您的客户经理已为您配置了对 Account Activity API 的访问权限。
  • 请确保您已正确配置 URI。如果在请求中填写了错误的 URI，可能会触发此错误。  

​
代码 214 - Webhook URL 不符合要求。

​
代码 214 - CRC 的 GET 请求延迟过高。你的 webhook（回调接口）应在 3 秒内完成响应。

  • 这表示你的服务器较慢。请确保在 3 秒内对 CRC 做出响应。  

​
代码 214 - 在 CRC GET 请求过程中返回非 200 的响应码（如 404、500 等）。

  • 你的服务器可能已宕机。请确保服务器正在正常运行。  

​
代码 214 - 已创建的资源过多。

  • Enterprise - 您已用尽所有 webhook（回调接口）。请对每个已注册的 App 使用 GET webhooks endpoint，以确定您的 webhook 的分布位置。 

​
代码 261 - 应用无法执行写入操作。

  • 您与 API 搭配使用的 App 的 access token 和 access token secret 未设置适当的权限级别。请前往 X apps 仪表板中的“Keys and tokens”选项卡，检查分配给您的 access token 和 access token secret 的权限级别。如果设置为除“Read, write and Direct Messages”之外的任何级别，则需要在“Permission”选项卡下调整设置，并重新生成您的 access token 和 access token secret 以使新设置生效。
  • 或者，您可能正尝试使用仅应用身份验证注册 webhook（回调接口），这是不受支持的。请按照为 Enterprise Account Activity API 注册 webhook 的 API 参考中的说明，改为使用用户上下文进行身份验证。

​
Account Activity API 参考索引

适用范围Enterprise
注册 webhook URL / 生成 webhook_idPOST
webhooks
返回所有 webhook URL 及其状态GET
webhooks
手动触发挑战响应检查PUT
webhooks/:webhook_id
将 App 订阅到账户事件POST
webhooks/:webhook_id/subscriptions/all
返回当前活跃订阅的数量GET
subscriptions/count
检查某 webhook 是否已订阅某账户GET
webhooks/:webhook_id/subscriptions/all
返回当前活跃订阅列表GET
webhooks/:webhook_id/subscriptions/all/list
删除该 webhookDELETE
webhooks/:webhook_id
使用三方 OAuth 停用订阅（已弃用）DELETE
webhooks/:webhook_id/subscriptions/all
使用仅限应用的 OAuth 停用订阅DELETE
webhooks/:webhook_id/subscriptions/:user_id/all.json
重新向 webhook 投递活动POST
replay/webhooks/:webhook_id/subscriptions/all

​
Enterprise Account Activity API

​
POST account_activity/webhooks

为指定的应用程序 context 注册新的 webhook URL。在保存之前，系统将通过 CRC 请求对该 URL 进行验证。若验证失败，将向请求方返回完整的错误信息。 允许的 webhook 数量取决于计费套餐。

​
资源 URL

https://api.x.com/1.1/account_activity/webhooks.json

​
资源信息

响应格式JSON
是否需要身份验证是（用户 context——所有 consumer 和 access tokens）
是否有请求速率限制是
每 15 分钟窗口的请求数（用户认证）15
是否支持 Tweet 编辑所有 Tweet 对象都会包含描述该 Tweet 编辑历史的 Tweet 编辑 metadata。更多详情请参见”Tweet edits” 基础知识页面。

​
参数

url（必填）回调 endpoint 的编码 URL。

​
示例请求

$ curl —request POST —url ‘https://api.x.com/1.1/account&#95;activity/webhooks.json?url=https%3A%2F%2Fyour&#95;domain.com%2Fwebhooks%2Ftwitter%2F0&#39; —header ‘authorization: OAuth oauth_consumer_key=“CONSUMER_KEY”, oauth_nonce=“GENERATED”, oauth_signature=“GENERATED”, oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“GENERATED”, oauth_token=“ACCESS_TOKEN”, oauth_version=“1.0“‘

​
HTTP 响应

HTTP 代码消息
200webhook URL 已为所提供的 App 完成注册
403你的请求有错误。请参见下方的错误信息部分。

​
示例响应 - 成功

_HTTP 200_

    {
      "id": "1234567890",
      "url": "https://your_domain.com/webhook/twitter/0",
      "valid": true,
      "created_at": "2016-06-02T23:54:02Z"
    }

​
错误消息

代码消息
214Webhook URL 不符合要求。
214已创建的资源过多。
214Webhook URL 不符合要求。CRC 令牌无效或 JSON 响应格式不正确。
214CRC GET 请求延迟过高。您的 webhook 应在 3 秒内响应。
214CRC GET 请求期间返回非 200 响应码（例如 404、500 等）。
HTTP 403 
    {
      "errors": [
        {
          "code": 214,
          "message": "已创建的资源过多。"
        }
      ]
    }

​
GET account_activity/webhooks

返回指定 App 的所有 URL 及其状态。 如果某个 URL 未通过每日验证检查，我们会将其标记为无效。要重新启用该 URL，请调用更新 endpoint。

​
资源 URL

https://api.x.com/1.1/account_activity/webhooks.json

​
资源信息

响应格式JSON
需要身份验证是（仅限 App——OAuth 2.0 Bearer Token）
有请求速率限制是
请求数 / 15 分钟窗口（App 认证）15

​
示例请求

    $ curl --request GET
     --url https://api.x.com/1.1/account_activity/webhooks.json
     --header 'authorization: Bearer TOKEN'

​
示例响应

HTTP 200 OK 
    [
      {
        "id": "1234567890",
        "url": "https://your_domain.com/webhook/twitter/0",
        "valid": true,
        "created_at": "2016-06-02T23:54:02Z"
      }
      {
        "id": "2468013579",
        "url": "https://your_domain2.com/webhook/twitter/0",
        "valid": true,
        "created_at": "2016-06-04T22:31:29Z"
      }
    ]

​
错误信息

代码信息
99您无权访问该资源。

​
PUT account_activity/webhooks/:webhook_id

对指定 webhook（回调接口）的 URL 触发挑战响应校验（CRC）。如果校验成功，则返回 204，并将其状态设置为 valid，从而重新启用该 webhook（回调接口）。

​
资源 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json

​
资源信息

响应格式JSON
需要验证是（用户 context——所有 consumer 和 access tokens）
请求速率限制是
每 15 分钟窗口的请求数（用户验证）15

​
参数

webhook_id（必填）webhook（回调接口）的 id。由资源路径定义。

​
示例请求

    $ curl --request PUT
     --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID.json
     --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

​
响应

HTTP 204 OK 
    { }

​
错误消息

CodeMessage
34Webhook 不存在，或与其他 X App 关联。
214Webhook URL 不符合要求。
214Webhook URL 不符合要求。CRC 令牌无效或 JSON 响应格式不正确。
214CRC 的 GET 请求延迟过高。你的 webhook 应在 3 秒内响应。
214CRC 的 GET 请求期间返回非 200 的响应码（如 404、500 等）。

​
POST account_activity/webhooks/:webhook_id/subscriptions/all

将指定的 App 订阅为针对所提供用户上下文、所有消息类型的全部事件。激活后，请求方用户的所有事件将通过 POST 请求发送至该 App 的 webhook（回调接口）。 当前可用的订阅数量受您的账户配置限制。如需增加订阅，请联系您的客户经理。

​
资源 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json

​
资源信息

响应格式JSON
需要身份验证是（3-legged OAuth——已列入白名单的 consumer key 和订阅用户的 access token）
请求速率限制是
请求数 / 15 分钟窗口（用户授权）500

​
参数

webhook_id（必填）webhook（回调接口）的 ID。由资源路径定义。

​
示例请求

    $ curl --request POST
     --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json
     --header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBING_USER'S_ACCESS_TOKEN", oauth_version="1.0"'

​
示例响应 - 成功

HTTP 204 无内容 
    {}

​
错误消息

代码消息
34webhook 不存在，或与其他 X App 关联。
348客户端 App 无权访问该用户的 webhook（回调接口）订阅。

​
GET account_activity/subscriptions/count

返回当前在你的账户上处于活动状态的订阅数量。请注意，/count endpoint 需要使用仅限应用的 OAuth，因此你应使用 OAuth 2.0 Bearer Token，而非用户 context 发起请求。

​
资源 URL

https://api.x.com/1.1/account_activity/subscriptions/count.json

​
资源信息

响应格式HTTP 响应码
需要身份验证是（仅限 App——OAuth 2.0 Bearer Token）
请求速率限制是
每 15 分钟窗口的请求数（App 认证）15

​
HTTP 响应代码

CodeMessage
200成功。将返回所请求 webhook（回调接口）的订阅计数。
401您的 App 无权查看指定 webhook（回调接口）的订阅。

​
示例请求

    $ curl --request GET
     --url https://api.x.com/1.1/account_activity/subscriptions/count.json
     --header 'authorization: Bearer TOKEN'

​
示例响应 - 成功

HTTP 200 
    {
      "account_name":"我的账户",
      "subscriptions_count_all":"1",
      "subscriptions_count_direct_messages":"0",
      "provisioned_count":"50"
    }

​
错误信息

代码信息
32无法对你进行身份验证。
HTTP 401 
    {
      "errors": [
        {
           "code": 32,
          "message": "无法对您进行身份验证。"
        }
      ]
    }

​
GET account_activity/webhooks/:webhook_id/subscriptions/all

用于判断某个 webhook（回调接口）配置是否已订阅指定用户的事件。若所提供的用户 context 在所提供的应用中具有有效订阅，则返回 204 OK。若响应代码不是 204，则表示该用户没有有效订阅。详情参见下方的 HTTP 响应代码与错误信息。

​
资源 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json

​
资源信息

响应格式JSON
需要身份验证是（三方 OAuth—列入白名单的 consumer key 和订阅用户的 access token）
有请求速率限制是
每 15 分钟窗口的请求数（用户认证）500

​
参数

webhook_id（必填）webhook（回调接口）ID。定义在资源路径中。

​
示例请求

$ curl —request GET —url https://api.x.com/1.1/account&#95;activity/webhooks/:WEBHOOK&#95;ID/subscriptions/all.json —header ‘authorization: OAuth oauth_consumer_key=“WHITELISTED_CONSUMER_KEY”, oauth_nonce=“GENERATED”, oauth_signature=“GENERATED”, oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“GENERATED”, oauth_token=“SUBSCRIBING_USER的ACCESS_TOKEN”, oauth_version=“1.0“‘

​
示例响应 - 成功

HTTP 204 No Content 
    { }

​
GET account_activity/webhooks/:webhook_id/subscriptions/all/list

返回指定 webhook 当前“All Activity”（所有活动）类型订阅的列表。请注意，/list endpoint 仅支持应用级 OAuth，因此请求应使用 OAuth 2.0 Bearer Token，而非用户上下文。

​
资源 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all/list.json

​
资源信息

响应格式HTTP 响应码
需要身份验证是（仅限应用，仅使用 OAuth 2.0 Bearer Token）
请求速率限制是
请求数 / 15 分钟窗口（应用认证）50

​
参数

webhook_id（必填）webhook（回调接口）的 ID。由资源路径定义。

​
HTTP 响应代码

代码消息
200成功。将返回所请求 webhook（回调接口）的订阅列表。
401您的 App 无权查看指定 webhook（回调接口）的订阅。

​
示例请求

$ curl —request GET —url https://api.x.com/1.1/account&#95;activity/webhooks/:WEBHOOK&#95;ID/subscriptions/all/list.json —header ‘Authorization: Bearer TOKEN’

​
示例响应 - 成功

HTTP 200 
    {
      "webhook_id": "1234567890",
      "webhook_url": "https://your_domain.com/webhook/twitter/0",
      "application_id": "11231812",
      "subscriptions": [{
        "user_id": "20212306"
      }]
    }

​
错误信息

代码信息
32无法验证您的身份。
HTTP 401 
    {
      "errors": [
        {
           "code": 32,
          "message": "无法对您进行身份验证。"
        }
      ]
    }

​
DELETE account_activity/webhooks/:webhook_id

从所提供的应用的配置中移除该 webhook（回调接口）。可通过调用 GET /1.1/account_activity/webhooks 获取该 webhook 的 id。

​
资源 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json

​
资源信息

响应格式JSON
需要身份验证是（用户 context——所有 consumer 和 Access Tokens）
受请求速率限制是
每 15 分钟窗口的请求数（用户认证）15

​
参数

webhook_id（必填）Webhook ID（webhook（回调接口）标识）。在资源路径中定义。

​
示例请求

    $ curl --request DELETE
     --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID.json
     --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

​
响应

HTTP 204 正常 
    { }

​
DELETE account_activity/webhooks/:webhook_id/subscriptions/all（已弃用）

为指定的用户context和应用停用订阅。停用后，将不再向该请求用户的webhook（回调接口）URL发送任何事件。

​
资源 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json

​
资源信息

响应格式JSON
需要身份验证是（3-legged OAuth——已加入白名单的consumer key和已订阅用户的access token）
受请求速率限制是
每15分钟窗口的请求数（用户认证）500

​
参数

webhook_id（必填）webhook（回调接口）的 ID。定义在资源路径中。

​
示例请求

    $ curl --request DELETE
     --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json
     --header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBED_USER'S_ACCESS_TOKEN", oauth_version="1.0"'
请求示例 
    { }

​
DELETE /account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json

为指定的 webhook 和用户 id 取消激活订阅。取消后，将不再向该 webhook URL 发送与请求用户相关的任何事件。请注意，此 endpoint 需要仅限应用的 OAuth（application-only），因此请求应使用 OAuth 2.0 Bearer Token，而非用户 context。

​
资源 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json

​
资源信息

响应格式JSON
需要身份验证是（仅 App — OAuth 2.0 Bearer Token）
是否有请求速率限制是
每 15 分钟窗口的请求数500

​
示例请求

    $ curl --request DELETE
     --url https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json
     --header 'authorization: Bearer TOKEN'

​
响应

HTTP 204 No Content

​
错误信息

代码信息
404抱歉，页面不存在。— 通常在指定的用户 id 实际未订阅时出现。

​
Replay API

POST /1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json  提交请求，从请求中指定的日期与时间窗口内、当时存在的所有订阅中，检索过去最多五天内的活动。如果你的 webhook 存在活跃的用户订阅，你也会同时实时收到这些事件。注意：在投递重放事件之前，我们会执行 CRC。
Request MethodHTTP POST
URL/1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json?from_date=yyyymmddhhmm&to_date=yyyymmddhhmm
Response FormatJSON
Requires Authentication是（仅应用程序 — OAuth 2.0 Bearer Token）
Rate Limit每 15 分钟 5 次请求。目前对可请求的重放作业数量没有上限。
from_date事件提供的最早（起始）UTC 时间戳，必须为“yyyymmddhhmm”格式。时间戳粒度为分钟，且为包含（例如 12:00 包含第 00 分钟）。有效时间必须为过去 5 天内的 UTC 时间，且不得晚于当前时间点前 31 分钟。建议 from_date 与 to_date 相差约 2 小时以内。
to_date事件提供的最晚（结束）UTC 时间戳，必须为“yyyymmddhhmm”格式。时间戳粒度为分钟，且为不包含（例如 12:30 不包含该小时的第 30 分钟）。有效时间必须为过去 5 天内的 UTC 时间，且不得晚于当前时间点前 10 分钟。

​
响应

API 可能返回以下响应。大多数错误代码会在响应体中包含附加详情的字符串。对于非 200 的响应，你应先排查错误并重试。
StatusTextError CodeDescriptionMessage
202AcceptedN/A请求成功，相关活动将被发送。N/A
400Bad Request214webhook 已被标记为无效。Webhook 被标记为无效，需要进行 CRC 检查。
400Bad Request357缺少 query 参数。: queryParam 为必填。
400Bad Request358路由或 query 参数格式不正确。无法解析参数。
400Bad Request360路由参数为负数。webhook_id: [] 不大于或等于 0。
400Bad Request368from_date 或 to_date 不是过去时间。: [<field_value>] 不是过去时间。
400Bad Request356from_date 必须早于 to_date。from_date 必须早于 to_date。
400Bad Request356from_date 必须在过去 5 天内。from_date 必须在过去 5 天内。
401Unauthorized32由于提供了三方授权，HTTP 认证失败。身份验证方法无效。请使用仅应用程序身份验证。
401Unauthorized61客户端无权请求此方法。客户端无权请求此方法。
403Forbidden200客户端没有启用 Replay 的 Enterprise 账户。需要启用 replay 的 Account Activity API Enterprise 账户。请确认你拥有 Enterprise 账户且已启用 replay。
404Not Found34不存在的 webhook_id；webhook_id 与 application_id 不匹配。Webhook 不存在或与其他 X 应用关联。
409Conflict355存在正在处理的请求，需等待其完成后再发起新的请求。此 webhook 的重放作业已在进行中。
429Too Many Requests88触发请求速率限制（在给定时间段内达到请求数量上限）请求过多。请降低 API 请求速率。
500Internal Server Error0内部服务器错误。内部服务器错误。
503Service Unavailable67X 的一个或多个依赖服务不可用。X 服务器错误。请使用指数退避策略重试。

​
“作业已成功完成”消息

当作业成功完成后，Account Activity Replay API 会发送如下作业完成事件。收到该事件即表示该作业已结束，可提交新的作业。 
{
  "replay\_job\_status": {
    "webhook_id": "1234577122340233217",
    "job_state": "Complete",
    "job\_state\_description": "任务已成功完成"
    "job_id": "1095098195724558337"
  }
}

​
“作业未完成” 消息

如果您的作业未能成功完成，我们将返回以下消息，提示您重试 Replay 作业。收到此事件后，表示该作业已结束运行，您可以提交新的作业。 
{
  "replay\_job\_status": {
    "webhook_id": "123451374207332352",
    "job_state": "Incomplete",
    "job\_state\_description": "作业未能传递所有事件，请重新执行重放作业",
    "job_id": "1093226942650736640"
  }
}

​
curl 请求示例

    curl --request POST  --url 'https://api.x.com/1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json?from_date=yyyymmddhhmm&to_date=yyyymmddhhmm'
    --header 'authorization: Bearer TOKEN'

​
示例响应

HTTP 202 
{
  "job_id": "1234567890",
  "created_at": "2016-06-02T23:54:02Z"
}
⌘I