快速入门

​

开始使用 Direct Message 管理类 endpoint

本快速上手指南将帮助您使用 Postman（用于管理和发起 HTTP 请求的工具）向 Direct Message 相关的 endpoint 发送首个请求。要了解更多关于我们 Postman 集合的信息，请参阅使用 Postman指南。

如需查看基于 Python 的示例，请访问我们的 X API v2 示例代码 GitHub 仓库。此外，官方的 X Developer Platform 软件开发工具包（SDK） 将陆续更新以支持这些 Direct Message endpoint。

先决条件

完成本指南，您需要一组用于对请求进行认证的密钥和令牌。您可以按照以下步骤生成这些密钥和令牌：

• 注册开发者账户并通过审核。
• 在开发者门户中创建一个Project并关联一个开发者 App。
• 前往您的 App 的“Keys and tokens”页面生成所需凭据。请确保将所有凭据妥善保存在安全位置。

​

构建私信查找请求的步骤

在本示例中，我们将在一次请求中创建一个新的群聊会话并添加第一条消息。随后，我们将向该会话再添加一条消息。

​

第一步：从工具或库入手

要开始使用管理私信的 endpoint，我们将借助 Postman 工具来简化流程。我们将使用由 XDevelopers 编写的 X API v2 示例请求集合，来探索六个用于创建新私信以及列出私信会话事件的 endpoint。

尽管该集合的大部分内容已预先填充，但你仍需根据用于承载这些 API 请求的 X App 提供一些详细信息。首先，让我们加载或更新该集合。

要将 X API v2 的 Postman 集合加载到你的环境中，请点击以下按钮：

将 X API v2 添加到 Postman

在你将 X API v2 集合加载到 Postman 后，导航到“Manage Direct Messages”文件夹。该文件夹的 Authorization 选项卡在可预填的部分已预先填充。你需要更新少量设置以提供你的 X App 的身份验证信息。

该文件夹还包含三个用于创建新私信的 endpoint。请注意，还有一个名为“Direct Message lookup”的文件夹，其中提供三个 endpoint，用于检索私信会话事件，包括消息的发送与接收，以及会话参与者加入和离开时的事件。

由于创建群组会话是 X API v2 的一项新功能，本示例将重点演示这一功能。我们将使用“New group DM and conversation”示例，通过此请求创建一个私信群组会话。

下一步是与该 endpoint 进行身份验证。

​

步骤二：为请求进行身份验证

要正确向 X API 发起请求，您需要先确认自己拥有相应权限。为了成功调用此 endpoint，我们将使用 OAuth 2.0 Authorization Code Flow with PKCE。您可以在 Postman 中生成一个 access token。 

在 Postman 中，您可以在文件夹级或请求级设置身份验证方式。此处我们将在文件夹级配置身份验证详情。导航到 “Manage Direct Messages” 文件夹，选择 “Authorization” 选项卡，确认 Type 设置为 “OAuth 2.0”，且 “Add auth data to” 设置为 “Request Headers.” 在 “Current Token” 部分，确保 “Header Prefix” 设置为 Bearer。  

配置并生成新令牌：

1. 创建一个 Token Name，例如 “DM lookup.”

2. 确认 Grant Type 设置为 Authorization Code (with PKCE)。

3. 设置您的 Callback URL。需要将 Callback URL 更新为与 v2 Dev Portal 中与您的应用关联的 Callback URL 完全一致。本示例所用的 X App 的 Callback URL 设置为 - https://www.example.com.（注意必须完全匹配， https://example.com 将无法使用。） 

4. 确认 Auth URL 设置为 https://x.com/i/oauth2/authorize

5. 确认 Access Token URL 设置为 https://api.x.com/2/oauth2/token.Client ID - 从开发者门户复制并粘贴 OAuth 2.0 Client ID Client Secret - 仅当您使用的是机密客户端类型的 App 时才需要。如果是，请从开发者门户复制并粘贴 OAuth 2.0 Client Secret。 

6. 确认 Scope 设置为 dm.read dm.write tweet.read users.read。

7. 确认 State 设置为 “state.”

8. 确认 Client Authentication 设置为 Send as Basic Auth header。

9. 点击 “Get New Access Token”，在 “Sign-in with X” 流程中点击 “Authorize app”。

10. 点击 “Proceed” 按钮，然后点击 “Use Token” 以生成令牌。 

11. 点击 “Save” 按钮保存这些配置信息。

您可能会收到尚未登录 X 的提示。如果出现该错误，您需要在 Postman 内登录要代表其发帖的 X 账号。

现在这些 OAuth 2.0 详情已在文件夹级设置，请依次进入每个示例的 “Authorization” 选项卡，并确认其 Type 设置为 “Inherit auth from parent.” 

请注意此令牌会很快过期，您需要通过点击 “Get New Access Token” 按钮重新生成。点击后将触发 “Sign-in with X” 流程，并生成一个新的令牌用于发起请求。

​

步骤三：检索私信会话事件

使用此 endpoint 检索私信会话事件时，需要指定会话 ID。会话 ID 是 endpoint 路径的一部分：https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events

在 Postman 中，进入“Params”选项卡，并在“Path Variables”部分输入要检索其事件的会话 ID。

设置如下：

Key	Value
dm_conversation_id	1228393702244134912

指定该会话后，生成的路径为 https://api.x.com/2/dm_conversations/1582103724607971328/dm_events

点击“Send”按钮后，响应中将返回私信对象的默认字段：id、text 和 event_type。还会包含一个“meta”对象，其中包括结果数量，以及在可用时用于检索更多事件的分页令牌。

{
   "data": [
       {
           "event_type": "MessageCreate",
           "id": "1580705921830768647",
           "text": "你们好，这是一个新的群组对话。"
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}

如果你希望获取更多 fields，需要在请求中通过 field 和/或 expansion 参数显式指定这些 fields。

在本练习中，我们将为 dm_event 对象请求额外的一组 fields：

1. 默认的 Direct Message 对象 fields：id、text 和 event_type。

2. 额外的 Direct Message 对象 fields：dm_conversation_id、created_at、sender_id、attachments、participant_ids、referenced_tweets

在 Postman 中，转到“Params”选项卡，并在“Query Params”表中添加以下键值对：

Key	Value
dm_event.fields	dm_conversation_id,created_at,sender_id,attachments,participant_ids,referenced_tweets

现在你应该会在“Send”按钮旁看到以下 URL：

https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events?dm_event.fields=id,text,event_type,dm_conversation_id,created_at,sender_id,attachments,participant_ids,referenced_tweets

​

第四步：发起请求并查看响应

完成所有设置后，再次点击“Send”按钮，您将收到与下方类似的响应。请注意，该响应包含所有可用的 dm_event fields。

{
   "data": [
       {
           "text": "你们好，这是一个新的群组对话。",
           "id": "1580705921830768647",
           "dm_conversation_id": "1580705921830768643",
           "event_type": "MessageCreate",
           "sender_id": "17200003",
           "created_at": "2022-10-13T23:43:54.000Z"
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}