跳转到主要内容
Direct Messages 端点 v2 将会话与会话事件作为核心 X API 对象引入，并区分一对一和群组会话。一对一会话始终且仅有两名参与者，而群组会话可包含两名或更多参与者，且成员关系可能发生变化。    本页汇总了在将 Manage Direct Messages 端点集成到你的系统时需要了解的多种工具和关键概念。我们将内容分为两个部分： 关键概念

​
私信会话

所有私信都属于某个私信会话。会话可以是一对一，或多人群组会话。本次发布提供了创建私信以及检索与私信会话相关事件所需的基础端点。所有会话都有唯一的 dm_conversation_id，构成该会话的所有事件也各自拥有唯一的 dm_event_id。   Manage Direct Message 端点提供了三种 POST 方法，用于创建新消息并将其加入会话：
  • POST /2/dm_conversations/with/:participant_id/messages - 创建一条一对一私信。该方法会将消息添加到现有的一对一会话，或新建一个会话。:participant_id 路径参数为接收消息账号的用户 ID。  下面是一个用于发送一对一私信的 JSON 请求体示例：
{
   "text": "你好。如果我们之前从未发过消息,这将显示为新对话;否则将添加到我们现有的对话中。"
}
  • POST /2/dm_conversations - 创建新的群组会话并向其中添加一条私信。此类请求需要提供会话参与者列表。请注意，你可以使用相同的参与者列表创建多个会话；这些请求将始终返回一个新的会话 ID。下面是一个用于创建新群组会话并添加私信的示例 JSON 请求正文。请注意，该请求需要包含一个 “conversation_type” 字段，且其值必须设置为 “Group”（区分大小写）。
{
   "message": {"text": "你们好,这是一个新的群组对话。"},
   "participant_ids": ["944480690","906948460078698496"],
   "conversation_type": "Group"
}
  • POST /2/dm_conversations/:dm_conversation_id/messages - 创建一条私信并将其添加到现有会话。:dm_conversation_id 路径参数表示要添加消息的会话 ID。此方法可用于向一对一会话和群组会话添加消息。 下面是一个用于向一对一和群组会话发送私信的 JSON 请求体示例：
{
   "text": "这是一条新消息。"
}
这些 POST 方法支持附加单个媒体。POST 请求正文必须包含 “text” 和 “attachments” 字段中的至少一个或两个。如果未包含 “attachments” 字段，则必须提供 “text” 字段；如果未包含 “text” 字段，则必须提供 “attachments” 字段。更多信息请参见下一节。 更多信息请参阅 Manage Direct Messages API References。

​
v1.1 与 v2 之间共享的会话和事件 ID

一个重要概念是，会话和事件 ID 在 X 平台的 v1.1 与 v2 版本之间是共享的。这意味着可以将两个版本配合使用。 例如，Direct Messages v1.1 端点提供了返回单个事件和删除事件的方法。这些方法在 v2 中尚不可用。由于 ID 在 v1.1 与 v2 之间通用，你可以基于 v2 提供的 ID 发起 v1.1 请求，或引用 X 应用中会话 URL 所显示的会话 ID。  

​
包含媒体附件并引用 Post

所有 Manage Direct Message 端点均支持附加一项媒体（照片、视频或 GIF）。附加媒体需要使用由 v1.1 Upload media 端点生成的媒体 id。发送该 Direct Message 的已认证用户也必须是上传该媒体的用户。媒体上传后，在 24 小时内可用于随消息一同发送。 为演示如何包含媒体，以下是一个示例 JSON 请求正文： 
{
 "text": "这是一张照片...",
 "attachments": [{"media_id": "1583157113245011970}]
}
生成的 MessageCreate 事件将包含以下元信息： 
{
    "attachments": {
        "media_keys": [
            "5_1583157113245011970"
        ]
    }
}
也可以在消息文本中插入 Post 的 URL 来嵌入 Post。为演示如何在消息中包含 Post，下面是一个示例 JSON 请求正文： 
{
 "text": "这是我提到的推文：https://x.com/SnowBotDev/status/1580559079470145536"
}
生成的 MessageCreate 事件将包含以下元信息： 
{
    "referenced_tweets": [
        {
            "id": "1580559079470145536"
        }
    ]
}

​
认证

所有 X API v2 端点都要求你使用一组凭证（也称为 keys 和 tokens）对请求进行认证。所有私信均为私密内容，访问它们需要用户授权。 这些私信端点需要使用 OAuth 2.0 Authorization Flow with PKCE 或 1.0a 用户上下文，也就是说，你必须使用一组 API keys 和用户 Access Tokens 才能成功发起请求。Access Tokens 必须与您代表其发起请求的用户关联。如果你想为其他用户生成一组 Access Tokens，他们必须通过 三方 OAuth 流程授权或认证你的应用。 请注意，OAuth 用户上下文的使用可能较为复杂。如果你不熟悉此认证方式，建议使用库或 Postman 等工具来正确完成认证。 OAuth 2.0 授权码（PKCE）可在多设备场景下对应用的 scope 和授权流程提供更强的控制。OAuth 2.0 允许你选择细粒度的 scopes，从而代表用户授予特定权限。私信查询端点需要以下 scopes：dm.write、dm.read、tweet.read、user.read。 要在你的应用中启用 OAuth 2.0，你必须在开发者门户的应用设置中开启相应的认证设置。

​
开发者门户、Project 与开发者应用

要获取可用于 X API v2 端点的一组认证凭证，您必须拥有已获批准的开发者账户，在该账户下设置一个 Project，并在该 Project 中创建一个开发者应用。随后，您可以在开发者应用中找到您的密钥和令牌。 

​
速率限制

每天都有成千上万的开发者向 X API 发起请求。为管理庞大的请求量，我们对每个端点设定了速率限制，用于限制你代表你的应用或代表已认证用户所能发起的请求次数。  Manage Direct Message 端点在用户级和 X 应用级都实施了速率限制。这意味着，你所代表的已认证用户通过你的 X 应用只能发送一定数量的消息。此外，你的 X 应用每天可发送的 Direct Message 也有总量上限。  对于 POST 方法，用户每 15 分钟的请求/消息上限为 200 次。用户在 24 小时内也被限制为最多发送 1000 条 Direct Message。此外，X 应用在 24 小时内的消息上限为 15,000 条。这些速率限制在所有 POST 端点之间共享。  实用工具 在使用 Direct Messages 查询端点时，我们鼓励你探索以下实用工具：  Postman Postman 是一款非常适合用于测试端点的工具。每个 Postman 请求都包含所有路径参数和请求体参数，帮助你快速了解可用内容。要进一步了解我们的 Postman 集合，请访问 Using Postman 页面。  代码示例 v2 Direct Messages 端点的 Python 示例代码可在我们的 X API v2 sample code GitHub 仓库中获取。“Manage-Direct-Messages” 文件夹包含 POST 方法示例，“Direct-Messages-lookup” 文件夹包含 GET 方法示例。 XDev 软件开发工具包（SDK） 这些库正在为 v2 Direct Messages 端点更新，很快即可使用： 第三方库 社区开发的第三方库数量持续增长。这些库旨在帮助你快速上手，且预计很快将支持 v2 Direct Messages 端点。你可以通过查看相应的版本标签找到适配 v2 端点的库。