Webhooks для Instagram Messaging

Webhooks позволяют в режиме реального времени получать уведомления HTTP об изменениях определенных объектов в социальном графе Meta. Например, вы можете получить уведомление, когда кто-то из клиентов отправляет сообщение вашему профессиональному аккаунту Instagram. Уведомления Webhooks позволяют отслеживать изменения при отправке сообщений и избегать ограничений числа обращений, которые могут налагаться, если вы отправляли к конечным точкам платформы Messenger запросы об отслеживании изменений.

Требования

Чтобы получать уведомления Webhooks для Instagram Messaging, вам необходимо обеспечить соответствие следующим требованиям:

• Разрешения instagram_basic, instagram_manage_messages и pages_manage_metadata
• Чтобы получать уведомления Webhooks, содержащие данные, которыми владеют или управляют лица, не имеющие роли в вашем приложении, это приложение должно обладать расширенным доступом

Примечание. На Webhooks сообщений необходимо подписать все приложения компании для обмена сообщениями.

Режимы работы приложения

• Режим разработчика: уведомления Webhooks отправляются, только если у пользователя приложения есть роль в этом приложении (даже при наличии расширенного доступа). У вас есть доступ только к тем данным, которыми вы владеете или которые администрируете.
• Рабочий режим: уведомления Webhooks отправляются в зависимости от уровня доступа.

  • Стандартный доступ: уведомления Webhooks отправляются, только если у пользователя приложения есть роль в этом приложении. У вас есть доступ только к данным, которыми вы владеете или которые администрируете.
  • Расширенный доступ: уведомления Webhooks отправляются, когда ваше приложение использует любой человек (при условии, что предоставлены необходимые разрешения).

См. подробную информацию об уровнях доступа , режимах приложения и ролях в приложении .

Ограничения

• Когда клиент реагирует на изображение из кольцевой галереи или пересылает изображение из галереи в публикации Instagram, уведомление будет включать в себя только первое изображение кольцевой галереи, которое может не совпадать с тем изображением, на которое отреагировал или которое переслал клиент.
• Когда клиент отправляет сообщение с публикацией, в уведомление будет добавлен только URL для предоставляемого медиафайла или публикации.
• Сообщения с изображениями в формате .gif и стикерами не поддерживаются. Если пользователь отправляет сообщение, содержащее файл в формате .gif или стикер, Webhooks не активируется и уведомление Webhooks не отправляется.

События 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
          } 
        }
      ]
    }
  ]
}  

Postback сообщений

{
  "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 . При использовании нескольких приложений, работающих с сообщениями, например когда одно приложение обрабатывает автоматические ответы, а другое — обращения к оператору, вам необходимо будет реализовать протокол передачи для перенаправления переписки из одного приложения в другое.
• Click To Direct, CTD . Посетите Справочный центр для компаний, чтобы получить дополнительную информацию о создании рекламных объявлений, при нажатии которых выполняется переход в Instagram Direct.