跳转到主要内容

​
开始使用 Direct Message 管理端点

本快速入门指南将帮助你使用 Postman（一款用于管理并发送 HTTP 请求的工具）向 Direct Message 端点发出第一个请求。要进一步了解我们的 Postman 集合，请参阅使用 Postman 指南。 如果你想查看基于 Python 的示例，请访问我们的 X API v2 示例代码 GitHub 存储库。此外，官方的 X Developer Platform 软件开发工具包（SDK） 将更新以支持这些 Direct Message 端点。  
先决条件要完成本指南，你需要一组用于对请求进行认证的密钥和令牌。你可以按以下步骤生成这些密钥和令牌：
  • 注册开发者账号 并通过审批。
  • 在开发者门户中创建一个项目以及关联的开发者应用。
  • 前往你的应用的 “Keys and tokens” 页面以生成所需凭据。请确保将所有凭据妥善保存于安全位置。

​
构建和管理私信请求的步骤

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

​
第一步：从工具或库开始

要开始使用管理私信（Direct Message）端点，我们将借助 Postman 来简化流程。我们将使用由 XDev 编写的 X API v2 示例请求集合，来探索 6 个用于创建新私信以及列出私信会话事件的端点。 虽然该集合的大部分配置已预填，但你仍需提供一些与你用于承载这些 API 请求的 X 应用相关的详细信息。首先，我们来加载/更新该集合。 要将 X API v2 的 Postman 集合加载到你的环境中，请点击以下按钮：
在你将 X API v2 集合加载进 Postman 后，前往“Manage Direct Messages”文件夹。该文件夹的 Authorization 选项卡在可能的情况下已预填，你可以更新部分设置以填入你的 X 应用认证详情。该文件夹还包含 3 个用于创建新私信的端点。请注意，还有一个“Direct Message lookup”文件夹，包含 3 个用于检索私信会话事件的端点，包括发送与接收消息，以及会话参与者加入和离开的事件。  由于在 X API v2 中创建群组会话是一个令人期待的新功能，本示例将聚焦于此。我们将使用“New group DM and conversation”示例，通过该请求创建一个私信群组会话。 下一步是对该端点进行认证。 第二步：对你的请求进行认证 要正确向 X API 发起请求，你需要验证自己具备相应权限。为成功请求此端点，我们将使用OAuth 2.0 Authorization Code Flow with PKCE。你可以在 Postman 中生成访问令牌。  使用 Postman 时，你可以在文件夹级别或请求级别设置认证方式。这里我们将在文件夹级别配置认证详情。 前往“Manage Direct Messages”文件夹，选择“Authorization”选项卡，确认 Type 设置为“OAuth 2.0”，且“Add auth data to”设置为“Request Headers”。在“Current Token”部分，确保“header Prefix”设置为 Bearer。   配置并生成新令牌：
  1. 创建一个 Token Name，例如“Manage DMs”。
  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” 流程，并生成一个新的令牌用于发起请求。

​
步骤三：指定私信会话参与者和消息内容

前往“Body”选项卡，更新示例 JSON 对象。将 participant_ids 属性设置为你想发送私信的账户。 { "message": {"text": "Hello to just you two, this is a new group conversation."}, "participant_ids": ["944480690","906948460078698496"], "conversation_type": "Group" }

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

完成所有设置后，点击“Send”按钮，你将会收到与下方示例响应类似的结果。提醒：如果你在上方创建的令牌已过期，可以返回该文件夹的 Authorization 选项卡，点击“Get New Access Token”以创建新的令牌。 
{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582103724607971332"
   }
}
如果返回的响应“data”对象包含 dm_conversation_id 和 dm_event_id，则表示你已成功创建一个新的 Direct Message 会话。要开始查询与该会话相关的事件，请前往 Direct Message 查询快速入门指南。

​
第五步：向该群组会话再添加一条消息

现在选择“Add DM to conversation”示例，并切换到“Params”选项卡。在“Path Variables”下，将 dm_conversation_id 更新为你在上面创建的会话的 ID。
KeyValue
dm_conversation_id1582103724607971328
使用此会话 ID，请求路径将变为：https://api.x.com/2/dm_conversations/1582103724607971328/messages 同时，在“Body”选项卡中更新请求 JSON，填入你要发送的消息文本： 
{
   "text": "正在向群组对话添加新消息..."
}
完成所有设置后，点击“Send”按钮，您将收到与下方示例响应类似的返回结果： 
{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582106224379559940"
   }
}