Webhooks für Instagram Messaging

Mit Webhooks erhältst du HTTP-Benachrichtigungen in Echtzeit, die dich über Änderungen an bestimmten Objekten im Meta Social Graph informieren. Wir können dir beispielsweise eine Benachrichtigung senden, wenn ein*e Kund*in deinem professionellem Instagram-Konto eine Nachricht sendet. Mit Webhooks-Benachrichtigungen kannst du Messaging-Änderungen nachverfolgen und Ratenbegrenzungen vermeiden, die auftreten können, wenn du die Endpunkte der Messenger-Plattform abfragst, um Änderungen nachzuverfolgen.

Anforderungen

Du musst die folgenden Anforderungen implementieren, um Webhooks-Benachrichtigungen für Instagram Messaging zu erhalten.

• Die Berechtigungen instagram_basic, instagram_manage_messages und pages_manage_metadata.
• Um Webhook-Benachrichtigungen zu erhalten, die Daten enthalten, die Personen gehören oder von diesen verwaltet werden, die keine Rolle in deiner App haben, muss deine App über erweiterten Zugriff verfügen.

Hinweis: Du musst alle Messaging-Apps für dein Unternehmen im Messaging-Webhook abonnieren.

App-Modi

• Entwicklungsmodus – Webhooks werden nur gesendet, wenn die Person, die deine App verwendet, eine Rolle in der App hat, auch wenn deine App über erweiterten Zugriff verfügt. Du kannst nur auf Daten zugreifen, die dir gehören oder die du verwaltest.
• Live-Modus – Webhooks werden je nach Zugriffslevel gesendet.

  • Standardzugriff – Webhooks werden nur gesendet, wenn die Person, die deine App verwendet, eine Rolle in der App hat. Du kannst nur auf Daten zugreifen, die dir gehören oder die du verwaltest.
  • Erweiterter Zugriff – Webhooks werden gesendet, wenn eine Person deine App nutzt, sofern die erforderlichen Berechtigungen erteilt wurden.

Erfahre mehr über Zugriffslevels , App-Modi und App-Rollen.

Einschränkungen

• Wenn ein*e Kund*in auf ein Bild aus einem Carousel in einem Instagram-Beitrag reagiert oder es weiterleitet, enthält die Benachrichtigung das erste Bild im Carousel, bei dem es sich möglicherweise nicht um das Bild handelt, auf das der*die Kund*in reagiert oder das er*sie weitergeleitet hat.
• Wenn Kund*innen eine Nachricht mit geteilten Medien oder einem geteilten Beitrag senden, wird nur die URL für den geteilten Inhalt in die Benachrichtigung eingeschlossen.
• Nachrichten mit GIFs und Stickern werden nicht unterstützt. Wenn eine Person eine Nachricht mit einem GIF oder einem Sticker sendet, wird kein Webhook ausgelöst und es wird keine Webhook-Benachrichtigung gesendet.

Webhook-Events

Beispielbenachrichtigungen

Es folgen Beispiele für die Arten von Webhook-Benachrichtigungen, die du erhalten kannst.

Nachrichten

{
  "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"       
              }
            }
          }
        }
      ]
    }
  ]
}

Nachrichtenreaktionen

{
  "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
          } 
        }
      ]
    }
  ]
}  

Nachrichten-Postbacks

{
  "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
          }
        }
      ]
    }
  ]
}

Nachrichtenweiterleitung

{
  "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 
          }
        }
      ]
    }
  ]
}
  

Nachrichten angesehen

{
   "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"
               }
            }
         ]
      }
   ]
}

Siehe auch

• Messenger Messenger-Übergabeprotokoll  – Wenn du für die Verarbeitung von Nachrichten mehr als eine App verwendest, z. B. eine App zum Verarbeiten automatisierter Antworten und eine andere App für Eskalationen an eine*n Mitarbeiter*in, musst du das Übergabeprotokoll implementieren, um die Unterhaltung von einer App zur anderen zu übergeben.
• Click To Direct, CTD  – Besuche den Hilfebereich für Unternehmen, um mehr über das Erstellen von Werbeanzeigen zu erfahren, die per Klick zu Instagram Direct weiterleiten.