Webhooks para Mensagens do Instagram

Os Webhooks permitem que você receba notificações HTTP em tempo real sobre mudanças em objetos específicos no gráfico social da Meta. Por exemplo, podemos notificar você sempre que um cliente enviar uma mensagem para sua conta profissional do Instagram. As notificações permitem o acompanhamento de alterações em mensagens e evitam limitações de volume que acontecem quando você consulta os pontos de extremidade da plataforma do Messenger para rastrear mudanças.

Requisitos

Se você quer receber notificações de Webhooks para Mensagens do Instagram, implemente os requisitos a seguir.

As permissões instagram_basic, instagram_manage_messages e pages_manage_metadata.
O app precisa ter acesso avançado para você receber notificações de webhooks que incluem dados pertencentes a pessoas sem função no app ou gerenciados por elas.

Observação: é preciso assinar os webhooks de mensagem para todos os apps de mensagem da empresa.

Modos de app

Modo de desenvolvimento: mesmo com o acesso avançado, os webhooks serão enviados somente se a pessoa usando o app tiver uma função nele. Você só pode acessar dados que possui ou administra.
Modo ao vivo: os webhooks serão enviados dependendo do nível de acesso.
- Acesso padrão: os webhooks serão enviados somente se a pessoa usando o app tiver uma função nele. Você só pode acessar dados que possui ou administra.
- Acesso avançado: os webhooks serão enviados quando qualquer pessoa usar seu app, desde que ela tenha as permissões necessárias.

Saiba mais sobre níveis de acesso , modos e funções do app.

Limitações

Quando um cliente encaminha ou reage a uma imagem do carrossel em uma publicação do Instagram, a notificação incluirá a primeira imagem do carrossel, que talvez não seja a mesma da interação.
Apenas a URL da publicação ou mídia compartilhada é incluída na notificação quando um cliente envia uma mensagem com compartilhamento.
Mensagens com GIFs e figurinhas não são compatíveis. Se uma mensagem com um GIF ou uma figurinha for enviada, isso não acionará um webhook nem o envio de uma notificação relacionada.

Eventos de webhook

Campo de webhook	Descrição
`message_reactions`	Uma notificação é enviada quando o cliente reage a uma mensagem ou remove a reação. A v12.0 e posteriores da Graph API são compatíveis com `angry`, `sad`, `wow`, `love`, `like`, `laugh` e `other`.
`messages`	Uma notificação é enviada quando o cliente manda para a empresa: uma mensagem com texto ou mídia (imagem/vídeo/arquivo/áudio); um compartilhamento (de mídia/publicação); uma resposta ou menção em um story. As menções em stories disparam webhooks, mas as marcações em publicações normais não. O webhook de respostas de stories não é compatível com GIF nem com figurinhas; uma resposta ou figurinha em mensagem inline; uma resposta rápida, uma opção de quebra-gelo ou a seleção do botão Modelo genérico; uma exclusão de mensagem; uma mensagem não compatível; uma mensagem da página de detalhes do produto nas Lojas do Instagram; uma mensagem no Instagram após redirecionamento de clique em anúncio (clique para o Instagram Direct). Uma notificação também é enviada quando a empresa manda uma mensagem para o cliente. Quando a empresa reagir a uma mensagem do cliente ou remover a reação, não será enviada nenhuma notificação. O retorno de chamada ocorrerá quando sua conta do Instagram tiver enviado uma mensagem. A sinalização `is_echo` será incluída para indicar que a mensagem foi enviada da própria conta do Instagram. O evento `message_reactions` não entregará um echo webhook.
`messaging_postbacks`	Uma notificação é enviada quando o cliente clica em uma opção de quebra-gelo ou um botão Modelo genérico. Requer v8.0 ou posterior. Requer v11.0 ou posterior para incluir o campo `mid`.
`messaging_seen`	Uma notificação é enviada quando o destinatário lê a mensagem.
`messaging_referral`	Uma notificação é enviada quando o cliente clica em um link `ig.me` com um parâmetro de referência em uma conversa existente.
`standby`	Se o fluxo de mensagens tiver vários apps, uma notificação será enviada quando o cliente mandar uma mensagem para a empresa, mas o app não terá o controle da conversa naquele momento.

Exemplos de notificações

Veja a seguir os exemplos de notificações de webhooks que podem ser recebidas.

Mensagens

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

Reações de mensagem

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

Postbacks de mensagem

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

Referências de mensagem

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

Mensagens visualizadas

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

Veja também

Protocolo de entrega : se tiver mais de um app gerenciando mensagens (por exemplo, um para gerenciar respostas automáticas e outro para encaminhar a um agente humano), você precisará implementar o protocolo de entrega para transferir a conversa entre apps.
Criar anúncios de clique para bate-papos do Instagram no Gerenciador de Anúncios : acesse a Central de Ajuda para Empresas e saiba mais sobre como criar anúncios com clique para o Instagram Direct.

Suporte ao desenvolvedor

Use a ferramenta de Status da Meta para verificar o status e as interrupções dos produtos da Meta para empresas.
Use a ferramenta de Suporte ao Desenvolvedor da Meta para relatar bugs, ver os já relatados, obter ajuda com o Gerenciador de Negócios ou Relatórios de Anúncios da Meta e muito mais.
Visite os Recursos úteis para a plataforma do Messenger para ver mais recursos compatíveis com a plataforma do Messenger.