Instagram 訊息的 Webhooks

Webhooks 可讓您接收 Meta 社交關係圖中特定物件變更的即時 HTTP 通知。例如，當顧客傳送訊息到您的 Instagram 專業帳號時，我們就會傳送通知給您。Webhooks 通知可讓您追蹤訊息變更，並避免在查詢 Messenger 開放平台端點以追蹤變更時發生的速率限制。

必備條件

您必須具備下列條件，才能接收 Instagram 訊息的 Webhooks 通知。

• instagram_basic、instagram_manage_messages 和 pages_manage_metadata 權限
• 若要取得的 Webhooks 通知包含非應用程式相關角色用戶所擁有或管理的資料，您的應用程式必須具有進階存取權限

附註：您需要為商家的所有訊息應用程式訂閱訊息 Webhooks。

應用程式模式

• 開發模式 - 只有當使用應用程式的用戶具有應用程式角色時，系統才會傳送 Webhooks，即使應用程式具有進階存取權限也是如此。您只能存取自己擁有或管理的資料。
• 上線模式 - 系統將根據存取權限層級傳送 Webhooks。

  • 一般存取權限 - 只有當使用應用程式的用戶具有應用程式角色時，系統才會傳送 Webhooks。您只能存取自己擁有或管理的資料。
  • 進階存取權限 - 只要已授予先決條件權限，系統就會在任何用戶使用應用程式時傳送 Webhooks。

深入瞭解存取權限層級 、應用程式模式 和應用程式角色

限制

• 如果顧客對 Instagram 貼文中的輪播廣告圖像傳達心情或轉發圖像，通知將包含輪播廣告中的第一張圖像，而該圖像可能不是顧客傳達心情或轉發的圖像。
• 當顧客傳送含有分享內容的訊息時，通知中只會包含所分享之媒體或貼文的網址。
• 不支援包含 GIF 和貼圖的訊息。如果用戶傳送包含 GIF 和貼圖的訊息，將不會觸發 Webhook，也不會傳送 Webhook 通知。

Webhook 事件

通知範例

以下是您可以接收的 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 發訊廣告。