適用於 Instagram 訊息功能的 Webhooks

Webhooks 讓您可以就 Meta 社交關係圖內特定物件的變更接收即時的 HTTP 通知。例如，當顧客向您的 Instagram 專業帳戶傳送訊息時，我們會傳送通知給您。您可以透過 Webhooks 通知追蹤訊息變更，而且如果您之前是透過查詢 Messenger 平台端點來追蹤變更，使用 Webhooks 通知可避免出現限速問題。

必要條件

您需要符合以下條件，才能接收 Instagram 訊息的 Webhooks 通知。

• instagram_basic、instagram_manage_messages 和 pages_manage_metadata 權限
• 如果 Webhooks 通知包含由沒有任何應用程式角色的用戶擁有或管理的資料，您的應用程式必須具備進階存取權限才能接收此類通知

備註：您需要為企業的所有通訊應用程式訂閱通訊 Webhooks。

應用程式模式

• 開發模式：僅當使用您應用程式的用戶在該應用程式中擁有角色時才會傳送 Webhooks，即使您的應用程式具有進階存取權限也是如此。您僅可存取您擁有或管理的資料。
• 上線模式：系統根據存取權限級別傳送 Webhooks。

  • 一般存取權限：僅當使用您應用程式的用戶在該應用程式中擁有角色時才會傳送 Webhooks。您僅可存取您擁有或管理的資料。
  • 進階存取權限：只要已授予先決條件權限，則在任何用戶使用您的應用程式時都會傳送 Webhooks。

進一步了解存取權限級別 、應用程式模式 和應用程式角色 。

限制

• 當顧客對 Instagram 帖子中的輪播廣告圖片表達心情或轉寄圖片時，通知將會包含輪播廣告中的第一張圖片，而該圖片可能並非顧客表達心情或轉寄的圖片。
• 當顧客傳送包含分享內容的訊息時，通知中僅包含所分享之媒體或帖子的網址。
• 包含 GIF 和貼圖的訊息不受支援。如果用戶傳送包含 GIF 或貼圖的訊息，系統不會觸發 Webhook，也不會傳送 Webhook 通知。

Webhooks 事件

通知範例

以下是您可接收的 Webhooks 通知類型範例。

訊息

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGID",  // ID of your Instagram Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": { "id": "IGSID" },    // Instagram-scoped ID for the customer who sent the message
          "recipient": { "id": "IGID" },  // ID of your Instagram Professional account
          "timestamp": 1569262485349,
          "message": {
            "mid": "MESSAGE-ID",   // ID of the message sent to your business
      
            "text": "MESSAGE-TEXT"     // Included when a customer sends a message containing text
      
            "attachments": [           // Included when a customer sends multiple media attachments or a URL for a story mention or share
              {
                "type":"image",             // Can be audio, file, image (image or sticker), share, story_mention, or video
                "payload":{ "url":"LINK" }  
              },
              {
                "type":"video",
                "payload":{ "url":"LINK" }
              }
            ]
      
            "is_deleted": true         // Included when a customer deletes a message
      
            "is_echo": true            // Included when your business sends a message to the customer

            "is_unsupported": true,    // Included when a customer sends a message with unsupported media
      
            "quick_reply": {           // Included when a customer clicks a quick reply
              "payload": "CUSTOMER-RESPONSE-PAYLOAD"   // The payload with the option selected by the customer
            },      
      
            "referral": {              // Included when a customer clicks an Instagram Shop product
              "product": {
                "id": "PRODUCT-ID"
            }      
      
            "referral": {                   // Included when a customer clicks an CTD ad
              "ref": "REF-DATA-IN-AD-IF-SPECIFIED"
              "ad_id": AD-ID,
              "source": "ADS",
              "type": "OPEN_THREAD",
              "ads_context_data": {
                "ad_title": TITLE-FOR-THE-AD,
                "photo_url": IMAGE-URL-THAT-WAS-CLICKED,
                "video_url": THUMBNAIL-URL-FOR-THE-AD-VIDEO,
              }
            }

            "reply_to":{               // Included when a customer sends an inline reply
              "mid":"MESSAGE-ID"
            } 
      
            "reply_to": {               // Included when a customer replies to a story
              "story": {
                "url":"CDN-URL",
                "id":"STORY-ID"       
              }
            }
          }
        }
      ]
    }
  ]
}

訊息心情

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGID",  // ID for your Instagram Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": {
            "id": "IGSID"  // Instagram-scoped ID for the customer who sent the message
          },
          "recipient": {
            "id": "IGID"  // ID for your Instagram Professional account
          },
          "timestamp": 1569262485349,
          "reaction" :{
            "mid" : "MESSAGE-ID",
            "action": "react",    // or unreact
            "reaction": "love", // optional, to unreact if there is no reaction field
            "emoji": "\u{2764}\u{FE0F}" // optional, to unreact if there is no emoji field
          } 
        }
      ]
    }
  ]
}  

訊息回傳

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGSID",  // ID of your Instagram Professional account
      "time": 1502905976963,
      "messaging": [
        {
          "sender": { "id": "IGSID" },    // Instagram-scoped ID for the customer who sent the message
          "recipient": { "id": "IGID" },  // ID of your Instagram Professional account
          "timestamp": 1502905976377,
          "postback": {
            "mid":"MESSAGE-ID",           // ID for the message sent to your business
            "title": "SELECTED-ICEBREAKER-REPLY-OR-CTA-BUTTON",
            "payload": "CUSTOMER-RESPONSE-PAYLOAD",  // The payload with the option selected by the customer
          }
        }
      ]
    }
  ]
}

訊息轉介

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGSID",  // ID of your Instagram Professional account  
      "time": 1502905976963,
      "messaging": [
        {
          "sender": {
            "id": "IGSID"  // Instagram-scoped ID for the customer who sent the message
          },
          "recipient": {
            "id": "IGID"  // ID of your Instagram Professional account
          },
          "timestamp": 1502905976377,
          "referral": {
                 "ref": "INFORMATION-INCLUDED-IN-REF-PARAMETER-OF-IGME-LINK"
                 "source": "IGME-SOURCE-LINK"  
                 "type":  "OPEN_THREAD"  // Only supported for existing conversations 
          }
        }
      ]
    }
  ]
}
  

已查閱訊息

{
   "object":"instagram",
   "entry":[
      {
         "id":"IGID",  // ID for your Instagram Professional account
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"IGSID"  // Instagram-scoped ID for the customer who sent the message
               },
               "recipient":{
                  "id":"IGID"  // ID for your Instagram Professional account
               },
               "timestamp":1569262485349,
               "read":{
                  "mid":"MESSAGE-ID"
               }
            }
         ]
      }
   ]
}

另請參閱

• Messenger 交接通訊協定 ：如果您使用多個應用程式來處理訊息，例如一個應用程式負責處理自動回覆，另一個負責處理要上報給真人服務人員的內容，您便需要執行交接通訊協定，以將對話從一個應用程式傳遞到另一個應用程式。
• Direct 發訊廣告，CTD ：瀏覽企業幫助中心，詳細了解如何建立 Instagram Direct 發訊廣告。