跳转到主要内容Direct Messages 端点 v2 将会话与会话事件引入为核心 X API 对象，并区分一对一和群组会话。一对一会话始终且仅包含两名参与者，而群组会话则可包含两名或更多参与者，且成员关系可能发生变化。
本页汇总了在将 Direct Messages 查询端点集成到你的系统时需要了解的多种工具与关键概念。我们将内容分为两个部分：
所有直接消息都属于某个直接消息会话。会话可以是一对一或群组会话。本次发布提供了创建直接消息及检索与直接消息会话相关事件所需的基础端点。每个会话都有唯一的 dm_conversation_id，构成该会话的每个事件都有唯一的 dm_event_id。
直接消息查询端点提供用于检索与会话相关事件的方法。这些 GET 端点用于获取构成会话的消息；对于群组会话，还可用于了解哪些成员加入或离开了群组会话。
此次直接消息查询的初始发布包含三个 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 端点均支持通过事件类型使用 event_types 查询参数来检索 dm_events。目前支持三种会话事件类型：
-
MessageCreate - 当创建新直接消息时产生。该事件对象可包含消息的时间与文本、发送者的账户 ID，以及会话与事件的 ID。
-
ParticipantsJoin - 当有新参与者加入群组会话时产生。该 dm_event 对象包含加入者的 ID、created_at 时间，以及“invite”事件的 sender_id。
-
ParticipantsLeave - 当有参与者离开会话时产生。该事件对象包含离开者的 ID 及事件发生时间。
更多信息请参阅直接消息查询 API 参考。
一个重要概念是，会话和事件的 ID 在 X 平台的 v1.1 和 v2 版本中是共享的。这意味着两个版本可以搭配使用。比如，Direct Messages v1.1 端点提供返回单个事件和删除事件的方法，而这些方法在 v2 中尚不可用。由于 ID 在 v1.1 和 v2 之间通用，你可以基于 v2 提供的 ID 发起 v1.1 请求，或引用 X 应用中会话 URL 所显示的会话 ID。
X API v2 允许用户使用称为 fields 和 expansions 的一组工具，精确选择希望从 API 返回的 data。比如，私信查询端点支持以下 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。
此外，私信查询端点支持以下 expansions：
-
sender_id - 展开与发送消息或邀请他人加入会话的用户关联的 User 对象。
-
referenced_tweets.id - 如果私信文本包含指向 Post 的链接，则展开该 Post 对象。
-
attachments.media_keys - 如果私信包含媒体附件，则展开 Media 对象。
-
participant_ids - 展开与加入或离开群组会话的用户关联的 User 对象。
由于 expansions 会包含 Posts、Users 和 Media 对象，你也可以使用 tweet.fields、user.fields 和 media.fields 请求查询参数。更多信息请参阅我们的如何使用 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 端点都要求你使用一组凭证（也称为密钥和令牌）来对请求进行认证。所有私信均为私密内容，访问它们需要用户授权。
这些私信端点需要使用 OAuth 2.0 授权码（PKCE） 或 1.0a 用户上下文，这意味着你必须使用一组 API 密钥和用户访问令牌才能成功发起请求。访问令牌必须与你代表其发起请求的用户关联。如果你想为另一位用户生成一组访问令牌，他们必须通过 三方 OAuth 流程授权或认证你的应用。
请注意，OAuth 用户上下文可能不太好用。如果你不熟悉这种认证方式，我们建议使用库或 Postman 等工具来正确地完成认证。
OAuth 2.0 Authorization Code with PKCE 允许对应用的 scope 进行更精细的控制，并支持跨设备的授权流程。OAuth 2.0 允许你选择细粒度的特定 scope，从而代表用户获取相应权限。私信查询端点需要以下 scope：dm.read、post.read、user.read
要在你的应用中启用 OAuth 2.0，你必须在开发者门户的应用设置中启用该应用的认证设置。
要获取可用于 X API v2 端点的一组认证凭据，您必须拥有已批准的开发者账户，在该账户中创建一个项目，并在该项目内创建一个开发者应用。随后，您可以在该开发者应用中找到您的密钥和令牌。
每天都有成千上万的开发者向 X API 发起请求。为管理如此庞大的请求量，我们在每个端点上实施速率限制，约束你代表你的应用或经过身份验证的用户所能发起的请求次数。
Direct Message 查询端点采用用户级速率限制，这意味着你代表其发起请求的已验证用户，使用你的 X 应用只能在一定配额内发起请求。对于 GET 方法，用户级速率限制为每 15 分钟最多 300 次请求。该速率限制在所有 GET 端点之间共享。
这些端点使用分页以便快速返回响应。当结果数量超过单个响应可返回的上限（最多 100 个事件）时，你需要进行分页。使用 max_results 参数确定每页返回的结果数量，使用 pagination_token 参数获取下一页结果。你可以通过查看我们的分页指南了解更多信息。
实用工具
以下是一些在使用 Direct Messages 查询端点时我们建议你探索的实用工具：
Postman
Postman 是一款非常适合测试端点的工具。每个 Postman 请求都包含所有路径和请求体参数，帮助你快速了解可用项。要了解更多关于我们 Postman 集合的信息，请访问使用 Postman页面。
代码示例
针对 v2 Direct Messages 端点的 Python 示例代码可在我们的X API v2 示例代码 GitHub仓库中获取。“Manage-Direct-Messages” 文件夹包含 POST 方法示例，“Direct-Messages-lookup” 文件夹包含 GET 方法示例。
XDev 软件开发工具包（SDK）
这些库正在为 v2 Direct Messages 端点进行更新，即将推出：
第三方库
社区开发的第三方库数量在不断增长。这些库旨在帮助你快速上手，部分库预计很快将支持 v2 Direct Messages 端点。你可以通过查找合适的版本标签来找到与 v2 端点兼容的库。 
