跳转到主要内容

​
开始使用 Direct Message 管理类 endpoint

本快速上手指南将帮助你使用 Postman（一个用于管理和发起 HTTP 请求的工具）向 Direct Message 相关的 endpoint 发出第一个请求。若要进一步了解我们的 Postman 集合，请参阅Using Postman 指南。 如果你想查看基于 Python 的示例，请访问我们的 X API v2 sample code GitHub 代码库。此外，官方的 X Developer Platform software development kits (SDKs) 将会更新以支持这些 Direct Message endpoint。
先决条件要完成本指南，你需要一组用于对请求进行身份验证的密钥和令牌。你可以按照以下步骤生成这些密钥和令牌：
  • 注册开发者账户并通过审核。
  • 在开发者门户中创建一个Project以及关联的开发者 App。
  • 前往你的 App 的“Keys and tokens”页面生成所需的凭据。请务必将所有凭据妥善保管。

​
构建和管理 Direct Message 请求的步骤

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

​
第一步：从工具或库入手

要开始使用用于管理私信的 endpoint，我们将使用 Postman 工具来简化流程。我们会使用由 XDev 编写的示例 X API v2 请求集合，来探索六个用于创建新私信和列出私信会话事件的 endpoint。 虽然该集合的大部分已预填，但仍有一些细节需要你根据用于承载这些 API 请求的 X App 来提供。首先，让我们加载/更新该集合。 要将 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，例如 “Manage DMs”。
  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” 流程，并生成一个新的令牌用于发起请求。

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

转到“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，则表示你已成功创建了新的私信会话。要开始查找与此会话关联的事件，请参阅“私信查询”快速上手指南。

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

现在选择 “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"
   }
}
⌘I