設定 Instagram 專用 Webhooks

有了 Instagram 專用 Webhooks，當有人在您應用程式用戶的媒體物件留言、@ 提及了您的應用程式用戶，或應用程式用戶的限時動態過期時，您便會收到即時通知。

獲取即時 Webhook 通知

如要獲取即時 Webhook 通知，必須符合以下條件：

• 您的應用程式必須已配置 Instagram Webhooks，並且已在應用程式管理中心訂閱合適的欄位。
• 如果是消費者應用程式，則必須為已發佈模式。
• 如果是商業應用程式，則必須擁有 Advanced Access 級別的權限。您可以按照下列方法申請 Advanced Access 級別的權限：

• 應用程式用戶必須向您的應用程式授予合適的權限（限時動態的為 instagram_manage_insights，留言和 @ 提及的為 instagram_manage_comments）。
• 連結應用程式用戶帳戶的專頁必須已啟用專頁訂閱功能。
• 連接至應用程式用戶專頁的企業必須已通過驗證。
• 收到留言或獲 @ 提及的媒體物件擁有者必須尚未將其帳戶設定為不公開。

限制

• 相簿留言的 Webhook 通知不會包含相簿編號。如要獲取相簿編號，請查詢 Webhook 中包含的留言編號，並要求獲取其 media 欄位。
• 如果收到留言或 @ 提及回應的媒體是由不公開帳戶所建立，應用程式將不會收到 Webhook 通知。
• 如果限時動態的洞察報告衡量數據數目少於 5，系統將傳回 -1。
• 如果直播 Instagram 媒體正在直播，應用程式只會在該媒體收到留言時取得 Webhooks 通知。
• 不支援 Reels 連續短片。
• 您的應用程式必須已成功完成應用程式審查（進階存取權限）才能接收有關 comments 和 live_comments Webhooks 欄位的 Webhooks 通知。

步驟 1：建立端點

建立用於接收和處理 Webhooks 的端點。在配置期間，選擇 Instagram Graph 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 欄位，在限時動態過期後，我們便會向您的端點傳送一則包含限時動態用戶互動衡量數據的 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 通知裝載範例：

說明文字 @ 提及內容的 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"
}