快速入门

​

开始使用 Direct Message 管理端点

本快速入门指南将帮助你使用 Postman（一款用于管理和发起 HTTP 请求的工具）向 Direct Message 端点发送你的第一个请求。想了解我们的 Postman 集合，请参阅使用 Postman指南。

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

先决条件

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

• 注册开发者账户并获得批准。
• 在开发者门户中创建一个Project以及关联的开发者应用。
• 转到你的应用的“Keys and tokens”页面以生成所需的凭据。请务必将所有凭据保存在安全位置。

​

构建私信查找请求的步骤

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

​

第一步：从工具或库入手

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

虽然该集合的大部分内容已预填，但仍有一些细节需要你根据用于承载这些 API 请求的 X 应用提供。首先，让我们加载或更新该集合。

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

将 X API v2 添加到 Postman

在你将 X API v2 集合加载到 Postman 后，前往“Manage Direct Messages”文件夹。该文件夹的 Authorization 选项卡在可能的情况下已预填。你需要更新一些设置，以便提供你的 X 应用的认证信息。

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

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

下一步是对该端点进行认证。

​

步骤二：为你的请求进行认证

要正确地向 X API 发起请求，你需要先验证自己是否具备相应权限。为成功调用此端点，我们将使用 OAuth 2.0 授权码模式（含 PKCE）。你可以在 Postman 中生成访问令牌。

在 Postman 中，你可以在文件夹级或请求级设置认证方式。这里我们将在文件夹级配置认证信息。进入 “Mange 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 应用，其 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 - 仅当你使用的应用类型为机密客户端时才需要此项。如需， 从开发者门户复制并粘贴 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” 流程，并生成新的令牌用于发起请求。

​

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

使用此端点检索私信会话事件时，你需要指定会话 ID。会话 ID 是端点路径的一部分：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"
   }
}

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

在本练习中，我们将为 dm_event 对象请求额外的字段集：

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

2. 额外的 Direct Message 对象字段：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"
   }
}