Messenger 开放平台

Messenger 开放平台的对话 API

本文档介绍如何获取有关 Messenger 和 Instagram 消息对话的信息。您可以获取：

  • Facebook 公共主页或 Instagram 专业帐户的对话列表
  • 每个对话的消息列表
  • 每条消息的详情，包括消息发送时间和发送人

准备工作

本教程假定您已阅读 Messenger 开放平台概览和 Instagram 消息概览，并实现了所需组件。

您将需要：

  • 商家的 Facebook 公共主页编号或与 Instagram 专业帐户绑定的 Facebook 公共主页的编号
  • 从可以在公共主页上执行 MESSAGING 或 MODERATE 任务的用户处请求获取的公共主页访问口令
  • 如要访问您的商家与在您的消息应用、Instagram 专业帐户、Facebook 公共主页或商家中未拥有身份的用户之间的对话，则必须具备高级访问级别

对于用户与您的公共主页之间的 Messenger 对话，您的应用将需要具备以下项目：

对于用户与您的 Instagram 专业帐户之间的 Instagram 消息对话，您的应用将需要具备以下项目：

  • 由可以在与您的 Instagram 业务帐户绑定的公共主页上执行 MESSAGING 任务的用户请求的公共主页访问口令
  • instagram_basic、instagram_manage_messages 和 pages_manage_metadata 权限
  • 您的应用所有者必须是已认证的商家

限制

  • API 调用或 Webhooks 通知返回的数据将仅包含用于分享的图像或视频网址。
  • 如果您使用私钥（如邮箱或电话号码）关联帐户，则将无法检索这些帐户之间的对话。仅可检索一个 Facebook 用户与一个 Instagram 帐户之间的对话。此问题可在您的应用获准使用高级访问级别时迎刃而解。如果 Instagram 应用的账户中心中关联了多个账户，您将能检索所有关联账户之间的对话。
  • 如果对话在“陌生消息”文件夹中持续 30 天处于不活跃状态，系统不会在 API 调用中返回该对话。

在将您的应用关联至新的 Instagram 业务账户时，您可以使用此 API 为收件箱同步过去的对话。

获取对话列表

如要获取对话列表，请向 /PAGE-ID/conversations 端点发送 GET 请求，其中应包含设置为 instagram 或 messenger 的 platform 参数。

请求示例

为方便阅读，示例格式已经过调整
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

成功后，应用会收到 JSON 对象，其中包含您与用户之间对话的编号和最近发送消息的时间列表。

{
  "data": 
    {
      "id": "CONVERSATION-ID-1",  
      "updated_time": "UNIX-TIMESTAMP"
    },
    {
      "id": "CONVERSATION-ID-2",   
      "updated_time": "UNIX-TIMESTAMP"
    }
    ...
  ]
}

查找与特定用户的对话

如要获取 Instagram 专业账户或 Facebook 公共主页与特定用户之间的对话，请向 /PAGE-ID/conversations 端点发送 GET 请求，其中应包含 platform 参数和 user_id 参数（后者设置为用户的 Instagram 范围编号或公共主页范围编号）。

请求示例

为方便阅读，示例格式已经过调整
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &user_id=INSTAGRAM-OR-PAGE-SCOPED-ID
    &access_token=PAGE-ACCESS-TOKEN"

成功后，应用会收到对话的编号。


{
  "data": [
      {
        "id": "CONVERSATION-ID"
      },
  ]
}

获取对话的消息列表

如要获取对话中的消息列表，请向 /CONVERSATION-ID 端点发送 GET 请求，并应在其中加入 messages 字段。

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/CONVERSATION-ID
    ?fields=messages
    &access_token=PAGE-ACCESS-TOKEN"

请求成功后，应用会收到消息编号和每条消息创建时间的列表。

{
  "messages": {
    "data": [
      {
        "id": "Message ID-1",      
        "created_time": "UNIX-TIMESTAMP-MOST-RECENT-MESSAGE"  
      },
      {
        "id": "Message ID-2",
        "created_time": "UNIX-TIMESTAMP"
      },
      {
        "id": "Message ID-3",
        "created_time": "UNIX-TIMESTAMP"
      },
...
    ]
  },
  "id": "Conversation ID", 
}

获取消息信息

要获取消息的详情，如发送人、接收人和消息内容，请向 /MESSAGE-ID 端点发送 GET 请求，并应在其中加入您感兴趣的字段。

默认字段为 id 和 created_time。

注意：查询 /CONVERSATION-ID 端点将返回某个对话中的所有消息编号。但是，您只能获取该对话中最近 20 条消息的详情。如果查询最近 20 条消息之前的某条消息，您会看到一条错误消息，显示所查询消息已被删除。

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/MESSAGE-ID
    ?fields=id,created_time,from,to,message
    &access_token=PAGE-ACCESS-TOKEN"

成功后，应用会收到以下 JSON 响应。在本示例中，一位客户向您的 Instagram 专业账户发送了一条纯文本消息。

{
  "id": "aWdGGiblWZ...",
  "created_time": "2022-07-12T19:11:07+0000",
  "to": {
    "data": [
      {
        "username": "INSTAGRAM-PROFESSIONAL-ACCOUNT-USERNAME",
        "id": "INSTAGRAM-PROFESSIONAL-ACCOUNT-ID"
      }
    ]
  },
  "from": {
    "username": "INSTAGRAM-USERNAME",
    "id": "INSTAGRAM-SCOPED-ID"
  },
  "message": "Hi Kitty!"
}

详细了解

请访问以下参考文档：

开发者支持