跳转到主要内容
v2 的私信 endpoint 将会话与会话事件引入为核心 X API 对象，并区分一对一会话与群组会话。一对一会话始终且仅有两位参与者；群组会话则可包含两位或更多参与者，且成员可变。    本页提供若干工具与关键概念，供你在将 Manage Direct Messages endpoint 集成到系统时参考。我们将本页分为两个部分： 关键概念

​
私信会话

所有私信都属于某个私信会话。这些会话可以是一对一会话或群组会话。本次发布提供了创建私信并检索与私信会话相关事件所需的基础 endpoint。所有会话都有唯一的 dm_conversation_id，构成该会话的各个事件也都有唯一的 dm_event_id。   Manage Direct Message 这一组 endpoint 提供了三个用于创建新消息并将其加入会话的 POST 方法：
  • POST /2/dm_conversations/with/:participant_id/messages - 创建一条一对一私信。该方法会将消息添加到现有的一对一会话，或创建一个新会话。:participant_id 路径参数是接收消息账号的 User ID。  以下是一对一私信的 JSON 请求正文示例：
{
   "text": "你好。如果我们之前没有聊过，这将显示为新对话，否则会添加到我们现有的对话中。"
}
  • POST /2/dm_conversations - 创建一个新的群组会话并向其中添加一条 Direct Message。此类请求需要提供会话参与者列表。请注意，你可以使用相同的参与者列表创建多个会话；这些请求将始终返回一个新的会话 ID。下面是一个用于创建新的群组会话并添加一条 Direct Message 的示例 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” 字段。更多信息请参见下一节。 欲了解更多信息，请参阅 管理私信 API 参考。

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

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

​
包含媒体附件并引用 Post

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

​
身份验证

所有 X API v2 endpoint 都要求你使用一组凭据（也称为密钥和令牌）对请求进行身份验证。所有私信均为私密内容，访问它们需要用户授权。  这些私信 endpoint 需要使用 OAuth 2.0 Authorization Flow with PKCE 或 1.0a User Context，这意味着你必须使用一组 API 密钥和用户 Access Tokens 才能成功发出请求。Access Tokens 必须与你代表其发起请求的用户关联。如果你想为另一位用户生成一组 Access Tokens，他们必须使用 三方 OAuth 授权流程 授权或认证你的 App。 请注意，OAuth 用户上下文的使用可能较为棘手。如果你不熟悉此身份验证方法，建议使用一个库或 Postman 等工具来正确地为你的请求进行身份验证。  OAuth 2.0 授权码模式（Authorization Code）配合 PKCE 允许在多设备上对应用的 scope 和授权流程进行更精细的控制。OAuth 2.0 允许你选择特定的细粒度 scope，从而代表用户获取特定权限。私信查询类 endpoint 需要以下 scope：dm.write、dm.read、tweet.read、user.read。 要在你的 App 中启用 OAuth 2.0，你必须在开发者门户的 App 设置中的身份验证设置里将其启用。

​
开发者门户、Project 和开发者 App

要获取可用于 X API v2 endpoint 的一组身份验证凭据，你必须拥有通过审核的开发者账户，在该账户下创建一个 Project，并在该 Project 中创建一个开发者 App。随后，你可以在该开发者 App 中找到你的密钥和令牌。 

​
请求速率限制

每天都有成千上万的开发者向 X API 发起请求。为便于管理庞大的请求量，我们在每个 endpoint 上设置了请求速率限制，用于限制你代表你的 App 或代表已认证用户所能发起的请求数量。  Manage Direct Message endpoints 在用户级和 X App 级都实施了请求速率限制。这意味着，你代表其发起请求的已认证用户，通过你的 X App 只能发送一定数量的消息。此外，你的 X App 每日可发送的私信总量也有上限。  对于 POST 方法，用户级请求速率限制为每 15 分钟 200 次请求/消息。用户还被限制为每 24 小时最多发送 1000 条私信。此外，X Apps 的限制为每 24 小时 15000 条消息。这些请求速率限制在所有 POST endpoints 间共享。  实用工具 以下是在你使用私信查询 endpoints 时建议探索的一些实用工具：  Postman Postman 是一款非常适合用来测试 endpoint 的工具。每个 Postman 请求都包含所有路径参数和请求体参数，帮助你快速了解可用项。要了解更多我们的 Postman 集合，请访问我们的使用 Postman页面。  代码示例 适用于 v2 私信 endpoints 的 Python 示例代码可在我们的 X API v2 示例代码 GitHub 仓库中找到。“Manage-Direct-Messages” 文件夹包含 POST 方法的示例，“Direct-Messages-lookup” 文件夹包含 GET 方法的示例。 XDev 软件开发工具包（SDK） 这些库正在为 v2 私信 endpoints 更新，预计很快可用： 第三方库 我们的社区正在开发越来越多的第三方库。这些库旨在帮助你快速上手，并且预计很快将支持 v2 私信 endpoints。你可以通过查找正确的版本标签来找到适用于 v2 endpoints 的库。
⌘I