設定 Instagram 專用 Webhooks

Instagram 專用 Webhooks 可讓您在以下狀況接收即時通知：有人在應用程式用戶的影音素材物件上留言、使用 @ 提及應用程式用戶，或應用程式用戶的限時動態到期時。

接收即時 Webhook 通知

若要接收即時 Webhook 通知，必須滿足以下條件：

• 您的應用程式必須在應用程式主控板中設定 Instagram Webhooks 並訂閱適當的欄位。
• 消費者應用程式必須處於上線模式。
• 商業應用程式必須具備進階存取權限層級。您可以要求進階存取權限以取得權限，如下所示：

• 應用程式用戶必須已授予應用程式適當的權限（限時動態為 instagram_manage_insights，留言和 @ 提及為 instagram_manage_comments）。
• 連結應用程式用戶帳號的粉絲專頁必須啟用粉絲專頁訂閱。
• 連結應用程式用戶粉絲專頁的商家必須已驗證。
• 顯示留言或 @ 提及內容的影音素材物件擁有者不得將帳號設定為不公開。

限制

• 相簿留言的 Webhook 通知不包括相簿編號。查詢 Webhook 中的留言編號並要求其 media 欄位可以取得相簿編號。
• 如果顯示留言或 @ 提及內容的影音素材是由不公開帳號所建立，應用程式不會收到 Webhook 通知。
• 計數小於 5 的限時動態洞察報告衡量指標會以 -1 傳回。
• 如果影音素材正在進行直播，應用程式只會接收對直播 IG 影音素材發表留言的 Webhook 通知。
• 不支援連續短片。
• 您的應用程式必須已成功完成應用程式審查（進階存取權限），才能接收 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/v21.0/1755847768034402/subscribed_apps?subscribed_fields=feed&access_token=EAAFB..."

回應範例

{
  "success": true
}

常見用途

擷取限時動態洞察報告

如果您訂閱 story_insights 欄位，我們會在限時動態過期時，傳送包含限時動態用戶互動衡量指標的 Webhook 通知到您的端點。

限時動態洞察報告承載範例

[
  {
    "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 商業或創作者帳號時，我們就會傳送 Webhook 通知到您的端點。

例如，以下是為 Instagram 商業帳號（17841405726653026）傳送的留言 Webhook 通知承載範例：

留言 @ 提及承載範例

[
  {
    "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 屬性的承載，以判斷是否要回應留言。若要回應，請使用 Webhook 通知承載的 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 商業或創作者帳號時，我們就會傳送 Webhook 通知到您的端點。

例如，以下是為 Instagram 商業帳號（17841405726653026）傳送的說明文字 @ 提及通知承載範例：

說明文字 @ 提及 Webhook 通知範例

[
  {
    "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 屬性的承載以確定是否要回覆留言。若要回應，請使用 Webhook 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"
}