设置 Instagram 专用 Webhooks

您可借助 Instagram 专用 Webhooks，在有人评论您应用用户的媒体对象、@提及您的应用用户或应用用户的快拍到期时，接收实时通知。

接收实时 Webhooks 通知

如要接收实时 Webhooks 通知，则必须满足以下所有条件：

• 必须已为应用配置 Instagram Webhooks，且在应用面板中订阅了相应的字段。
• 消费者应用必须为已发布模式。
• 业务应用必须拥有具备高级访问级别的权限。您可以按照下方所显示的方法申请具备高级访问级别的权限：

• 应用用户必须向您的应用授予相应权限（针对快拍的 instagram_manage_insights、针对评论和 @提及功能的 instagram_manage_comments）。
• 与应用用户的帐户相关联的公共主页必须已启用公共主页订阅。
• 与应用用户公共主页相关联的企业必须已经过认证。
• 受到评论或 @提及的媒体对象的所有者必须尚未将其帐户设置为非公开。

限制

• 针对相册评论的 Webhooks 通知中不包含相册编号。如要获取相册编号，请查询 Webhooks 中的评论编号，然后请求其 media 字段。
• 如果受到评论或 @提及的媒体是由私密帐户所创建，则应用不会收到 Webhooks 通知。
• 快拍成效分析指标计数小于 5 时会返回 -1。
• 只有在直播 Instagram 媒体正在直播时，应用才会收到针对该媒体的评论的 Webhooks 通知。
• 不支持 Reels。
• 您的应用必须已经成功完成应用审核（高级访问级别），才能收到针对 comments 和 live_comments Webhooks 字段的 Webhooks 通知。

第 1 步：创建端点

创建用于接收和处理 Webhooks 的端点。在配置期间，选择 Instagram 图谱 API 对象，点击设置，然后订阅一或多个 Instagram 字段。

Instagram 字段

第 2 步：启用公共主页订阅

您的应用必须对应用用户帐户所关联的公共主页启用“公共主页订阅”，方法如下：向已订阅公共主页的应用连线发送 POST 请求，并订阅任意公共主页字段。

端点要求

• 应用用户的公共主页访问口令
• pages_manage_metadata

请求语法

POST /{page-id}/subscribed_apps
  ?access_token={access-token}
  &subscribed_fields={fields}

请求参数

您的应用不会在字段发生更改时收到通知，除非您在应用面板中配置了公共主页订阅并订阅了该字段。

请求示例

curl -i -X POST \
  "https://graph.facebook.com/v19.0/1755847768034402/subscribed_apps?subscribed_fields=feed&access_token=EAAFB..."

响应示例

{
  "success": true
}

常见用途

捕获快拍成效分析

如果您订阅 story_insights 字段，我们会在快拍过期后向您的端点发送 Webhooks 通知，其中包含该快拍的用户互动情况指标。

快拍成效分析负载示例

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "story_insights",
            "value": {
              "media_id": "18023345989012587",
              "exits": 1,
              "replies": 0,
              "reach": 17,
              "taps_forward": 12,
              "taps_back": 0,
              "impressions": 28
            }
          }
        ],
        "id": "17841405309211844",  // Instagram Business or Creator Account ID
        "time": 1547687043
      }
    ],
    "object": "instagram"
  }
]

回复带有 @提及内容的评论

如果您已订阅 mentions 字段，每当 Instagram 用户在评论或说明中 @提及 Instagram 业务帐户或创作者帐户时，我们都将向您的端点发送一条 Webhooks 通知。

例如，以下是针对 Instagram 业务帐户 (17841405726653026) 发送的评论 Webhooks 通知负载示例：

带有 @提及内容的评论负载示例

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "comment_id": "17894227972186120",
              "media_id": "17918195224117851"
            }
          }
        ],
        "id": "17841405726653026",
        "time": 1520622968
      }
    ],
    "object": "instagram"
  }
]

获取评论内容

如要获取评论内容，请使用 comment_id 属性查询 GET /{ig-user-id}/mentioned_comment 连线：

查询示例

GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_comment.comment_id(17894227972186120) 

响应示例

{
  "mentioned_comment": {
    "timestamp": "2018-03-20T00:05:29+0000",
    "text": "@bluebottle challenge?",
    "id": "17894227972186120"
  },
  "id": "17841405726653026"
}

解析负载及响应

获得响应后，请解析负载，以获取 text 属性，从而确定是否要回复评论。如要回复，请使用 Webhooks 通知负载的 caption_id 和 media_id 属性值来查询 POST /{ig-user-id}/mentions 端点：

查询示例

curl -i -X POST \
  -d "comment_id=17894227972186120" \
  -d "media_id=17918195224117851" \
  -d "message=Challenge%20accepted!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

响应示例

{
  "id": "17911496353086895"
}

回复带有 @提及内容的说明

如果您已订阅 mentions 字段，每当用户在非 Instagram 业务帐户或创作者帐户所有的媒体对象的评论或说明中 @提及 Instagram 业务帐户或创作者帐户时，我们都将向您的端点发送一条 Webhooks 通知。

例如，以下是针对带有“@提及”内容的说明，就 Instagram 业务帐户 (17841405726653026) 发送的 Webhooks 通知示例：

针对带有 @提及内容的说明的 Webhooks 通知示例

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "media_id": "17918195224117851"
            }
          }
        ],
        "id": "17841405726653026",
        "time": 1520622968
      }
    ],
    "object": "instagram"
  }
]

获取说明内容

如要获取说明内容，请使用 media_id 属性查询 GET /{ig-user-id}/mentioned_media 连线：

查询示例

GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_media.media_id(17918195224117851){caption,media_type} 

响应示例

{
  "mentioned_media": {
    "caption": "@bluebottle There can be only one!",
    "media_type": "IMAGE",
    "id": "17918195224117851"
  },
  "id": "17841405726653026"
}

解析负载及响应

获得响应后，请解析负载，以获取 caption 属性，从而确定是否要回复评论。若要回复，请使用 Webhooks 通知负载的 media_id 属性来查询 POST /{ig-user-id}/mentions 连线：

查询示例

curl -i -X POST \
  -d "media_id=17918195224117851" \
  -d "message=MacLeod%20agrees!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

响应示例

{
  "id": "17911496353086895"
}