跳转到主要内容
v2 的私信 endpoint 将会话和会话事件引入为核心 X API 对象，并区分 1 对 1 与群组会话。1 对 1 会话始终且仅有两位参与者，而群组会话可包含两位或更多参与者，且成员关系可变。    本页汇总了在将私信查询 endpoint 集成到你的系统时需要了解的多种工具与关键概念。我们将页面分为两个部分：

​
核心概念

​
私信会话

所有私信都属于某个私信会话。会话可以是一对一或群组会话。本次发布提供了用于创建私信并检索与私信会话相关事件的基础 endpoint。所有会话都有唯一的 dm_conversation_id，构成该会话的所有事件都有唯一的 dm_event_id。   私信查找 endpoint 提供用于检索与会话相关事件的方法。这些 GET endpoint 用于获取构成某个会话的消息；对于群组会话，还可用于了解谁加入或退出了群组会话。 本次私信查找的初始发布包含三种 GET 方法：
  • GET /2/dm_conversations/with/:participant_id/dm_events - 检索与一对一会话相关的私信事件。:participant_id 路径参数为与发起此请求的已认证用户进行会话的账号的数值型用户 id。  
  • GET /2/dm_conversations/:dm_conversation_id/dm_events - 根据 :dm_conversation_id 路径参数指定的会话 id，检索与该会话相关的私信事件。支持一对一和群组会话的 id。  
  • GET /2/dm_events - 检索与已认证用户相关的私信事件，包括一对一和群组会话。可获取最近最多 30 天内的事件。  
这些 GET endpoint 均支持按事件类型检索 dm_events，可使用 event_types 请求 query（查询）参数。目前支持三种会话事件类型：
  • MessageCreate - 当创建新的私信时触发。该事件对象可包含消息的时间与文本、发送者的账号 id，以及会话和事件的 id。 
  • ParticipantsJoin - 当新参与者加入群组会话时触发。该 dm_event 对象包含加入者的 id，以及 created_at 时间和“invite”事件的 sender_id。 
  • ParticipantsLeave - 当参与者退出会话时触发。该事件对象包含退出者的 id，以及事件发生的时间。 
欲了解更多信息，请参阅私信查找 API 参考。

​
在 v1.1 与 v2 间共享的会话与事件 ID

一个重要概念是，会话和事件 ID 在 X 平台的 v1.1 与 v2 版本之间是共享的。这意味着这两个版本可以搭配使用。比如，私信的 v1.1 endpoint 提供了返回单个事件和删除事件的方法，而这些方法在 v2 中尚不可用。由于 ID 在 v1.1 和 v2 中是通用的，你可以基于 v2 提供的 ID 发起 v1.1 请求，或者引用 X 应用中会话 URL 中显示的会话 ID。  

​
私信事件字段与 expansions

X API v2 允许用户使用称为 fields 和 expansions 的一组工具，精确选择希望从 API 返回的 data。例如，私信查询 endpoints 支持以下 dm_events 字段：
  • 对于 MessageCreate 事件，默认返回 id、event_type 和 text。
  • 对于 ParticipantsJoin 和 ParticipantsLeave 事件，默认返回 id、event_type 和 participant_ids。
  • 所有事件均可用 dm_conversation_id 和 created_at。
  • 对于 MessageCreate 事件，可用 attachments 和 referenced_tweets。
  • 对于 MessageCreate 和 ParticipantsJoin 事件，可用 sender_id。
  • 对于 ParticipantsJoin 和 ParticipantsLeave 事件，可用 participant_ids。
此外，私信查询 endpoints 支持以下expansions：
  • sender_id - 展开与发送消息或邀请他人加入会话的用户关联的用户对象。
  • referenced_tweets.id - 如果私信文本包含指向 Post 的链接，则展开 Post 对象。
  • attachments.media_keys - 如果私信包含媒体附件，则展开 Media 对象。
  • participant_ids - 展开与加入或离开群组会话的用户关联的用户对象。
由于 expansions 可包含 Posts、Users 和 Media 对象，您还可以使用 tweet.fields、user.fields 和 media.fields 请求 query（查询）参数。有关更多信息，请参阅我们的如何使用 fields 和 expansions指南。

​
会话事件类型

以下是 Direct Message 的 MessageCreate、ParticipantsJoin 和 ParticipantsLeave 事件类型的示例 JSON 对象。 可用的 dm_event 对象字段：id、text、event_type、dm_conversation_id、created_at、sender_id、attachments、referenced_tweets、participant_ids。有关在请求中选择这些字段的详细说明，请参阅“Fields and Expansion”部分。 MessageCreate 事件示例： 在指定所有 dm_event 字段的情况下，以下是一个纯文本 Direct Message 的响应： { "text": "Hi everyone.", "sender_id": "944480690", "dm_conversation_id": "1578398451921985538", "id": "1582838499983564806", "event_type": "MessageCreate", "created_at": "2022-10-19T20:58:00.000Z" } ParticipantsJoin 事件示例： 在指定所有 dm_event 字段的情况下，以下是参与者加入会话时的响应： { "participant_ids": [ "944480690" ], "sender_id": "17200003", "dm_conversation_id": "1578398451921985538", "id": "1582835469712138240", "event_type": "ParticipantsJoin", "created_at": "2022-10-19T20:45:58.000Z" } ParticipantsLeave 事件示例： 在指定所有 dm_event 字段的情况下，以下是参与者离开会话时的响应： { "participant_ids": [ "944480690" ], "dm_conversation_id": "1578398451921985538", "id": "1582838535115067392", "event_type": "ParticipantsLeave", "created_at": "2022-10-19T20:58:09.000Z" }

​
身份验证

所有 X API v2 endpoint 都要求你使用一组凭证（也称为密钥和令牌）来对请求进行身份验证。所有私信均为私密内容，访问它们需要用户授权。 这些私信 endpoint 需要使用 OAuth 2.0 Authorization Flow with PKCE 或 1.0a User Context，这意味着你必须使用一组 API 密钥和用户 Access Tokens 才能成功发起请求。Access Tokens 必须与您代表其发起请求的用户关联。如果你想为其他用户生成一组 Access Tokens，他们必须使用 三方 OAuth 授权流程 授权或验证你的 App。 请注意，OAuth 的用户上下文可能较为复杂。如果你不熟悉此身份验证方法，我们建议使用一个库或 Postman 等工具来正确地对请求进行身份验证。 OAuth 2.0 Authorization Code with PKCE 允许更精细地控制应用的 scope，并支持跨多设备的授权流程。OAuth 2.0 允许你选择细粒度的 scope，从而代表用户获取特定权限。私信查询 endpoint 需要以下 scopes：dm.read、post.read、user.read 要在你的 App 中启用 OAuth 2.0，你需要在开发者门户的 App 设置中启用 App 的身份验证设置。

​
开发者门户、Project 和开发者 App

要获取可用于 X API v2 endpoint 的一组身份验证凭据，您必须拥有已批准的开发者账户，在该账户中创建一个 Project，并在该 Project 中创建一个开发者 App。随后，您可以在开发者 App 中找到您的密钥和令牌。 

​
请求速率限制

每天有成千上万的开发者向 X API 发起请求。为应对如此庞大的请求量，我们在每个 endpoint 上设置了请求速率限制，限制你代表你的 App 或代表已通过身份验证的用户所能发起的请求数量。 Direct Message 查询类 endpoints 采用用户级别的请求速率限制，这意味着你所代表的已验证用户通过你的 X App 只能发起一定数量的请求。对于 GET 方法，用户请求速率限制为每 15 分钟 300 次。该请求速率限制在所有 GET endpoints 之间共享。  这些 endpoint 使用分页以便快速返回响应。当结果多于单个响应可返回的数量（最多 100 个事件）时，你需要进行分页。使用 max_results 参数指定每页返回的结果数量，使用 pagination_token 参数请求下一页结果。你可以通过查看我们的分页指南了解更多信息。 实用工具 以下是一些我们建议你在使用私信查询 endpoint 时探索的实用工具：  Postman Postman 是一款非常适合用于测试 endpoint 的工具。每个 Postman 请求都包含所有路径参数和请求正文参数，帮助你快速了解可用内容。要进一步了解我们的 Postman 集合，请访问我们的使用 Postman页面。  代码示例 适用于 v2 私信 endpoint 的 Python 示例代码可在我们的 X API v2 示例代码 GitHub 仓库中找到。“Manage-Direct-Messages” 文件夹包含 POST 方法的示例，“Direct-Messages-lookup” 文件夹包含 GET 方法的示例。 XDev 软件开发工具包（SDK） 这些库正在为 v2 私信 endpoint 更新，预计很快即可使用： 第三方库 社区开发的第三方库数量在不断增长。这些库旨在帮助你快速上手，且预计有数个很快会支持 v2 私信 endpoint。你可以通过查找合适的版本标签来确定与 v2 endpoint 兼容的库。
⌘I