Webhooks para mensajes de Instagram

Gracias a los webhooks, podrás recibir notificaciones HTTP en tiempo real sobre los cambios que se produzcan en determinados objetos de la gráfica social de Meta. Por ejemplo, te podemos enviar una notificación cuando un cliente envíe un mensaje a tu cuenta profesional de Instagram. Gracias a las notificaciones de los webhooks, podrás hacer un seguimiento de los cambios en los mensajes y evitar los límites de frecuencia que se podrían producir si consultas los extremos de la plataforma de Messenger para hacer un seguimiento de los cambios.

Requisitos

Deberás implementar los requisitos siguientes para recibir las notificaciones de los webhooks para los mensajes de Instagram.

Los permisos instagram_basic, instagram_manage_messages y pages_manage_metadata.
Para recibir notificaciones de webhooks que incluyan datos que sean propiedad de usuarios que no tengan un rol en la aplicación o que estén administrados por ellos, la aplicación debe tener Advanced Access.

Nota: Deberás suscribir todas las aplicaciones de mensajes para tu empresa a los webhooks de mensajes.

Modos de aplicación

Modo de desarrollo: solo se enviarán webhooks si la persona que usa la aplicación tiene un rol en ella, incluso si la aplicación tiene acceso avanzado. Solo puedes acceder a los datos que te pertenezcan o que administres.
Modo activo: los webhooks se enviarán en función del nivel de acceso.
- Acceso estándar: solo se enviarán webhooks si la persona que usa la aplicación tiene un rol en ella. Solo puedes acceder a los datos que te pertenezcan o que administres.
- Acceso avanzado: los webhooks se enviarán cuando cualquier usuario utilice la aplicación siempre que se hayan concedido los permisos de los requisitos previos.

Obtén más información sobre los niveles de acceso , los modos de aplicaciones y los roles de las aplicaciones.

Limitaciones

Cuando un cliente reaccione a una imagen de una secuencia en una publicación de Instagram o la reenvíe, la notificación incluirá la primera imagen de la secuencia, que podría no ser la imagen a la que ha reaccionado o que ha reenviado el cliente.
Cuando un cliente comparte contenido mediante un mensaje, en la notificación solo se incluye la URL del contenido multimedia o la publicación compartidos.
No se admiten los mensajes con GIF y stickers. Si un usuario envía un mensaje con un GIF o un sticker, no se activará ningún webhook y no se enviará ninguna notificación de webhooks.

Eventos de webhooks

Campo de webhooks	Descripción
`message_reactions`	Se envía una notificación cuando un cliente reacciona a un mensaje o anula su reacción. La versión 12.0 de la API Graph y las versiones posteriores admiten las reacciones `angry`, `sad`, `wow`, `love`, `like`, `laugh` y `other`.
`messages`	Se envía una notificación cuando un cliente envía a tu empresa: Un mensaje con texto o contenido multimedia (imagen, vídeo, archivo o audio). Contenido compartido (publicaciones o contenido multimedia compartidos). Una respuesta o mención de una historia. Solo activarán un webhook las menciones en las historias. El etiquetado en publicaciones periódicas no activará ningún webhook. El webhook de respuestas a historias actualmente no admite GIF ni stickers. Un sticker o una respuesta a un mensaje en línea. Se selecciona una respuesta rápida, una opción de pregunta para romper el hielo o el botón de plantilla genérica. Un cliente elimina un mensaje. No se admite el mensaje de un cliente. Un cliente envía un mensaje desde la página de información de un producto de tiendas de Instagram. Un cliente hace clic en un anuncio que conduce a una conversación con mensajes de Instagram (clic para dirigir, CTD). También se envía una notificación cuando tu empresa envía un mensaje a un cliente. No se enviará ninguna notificación cuando tu empresa reaccione a un mensaje de un cliente o anule la reacción. Esta devolución de llamada se producirá cuando tu cuenta de Instagram envíe un mensaje. La marca `is_echo` se incluirá para indicar que el mensaje se ha enviado desde la cuenta de Instagram. No se entregará ningún webhook de eco para el evento `message_reactions`.
`messaging_postbacks`	Se envía una notificación cuando un cliente hace clic en una opción de pregunta para romper el hielo o el botón de plantilla genérica. Requiere la versión 8.0 o posteriores. Requiere la versión 11.0 o posteriores para incluir el campo `mid`.
`messaging_seen`	Se envía una notificación cuando el destinatario ha leído un mensaje.
`messaging_referral`	Se envía una notificación cuando un cliente hace clic en un enlace `ig.me` con un parámetro de referencia en una conversación existente.
`standby`	Cuando el flujo de mensajes tiene varias aplicaciones, se envía una notificación cuando un cliente envía un mensaje a tu empresa, pero la aplicación no controla la conversación en el momento en que se envió el mensaje.

Notificaciones de ejemplo

A continuación, se incluyen ejemplos de los tipos de notificaciones de webhooks que puedes recibir.

Mensajes

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

Reacciones a mensajes

{
  "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 mensajes

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

Referencia de mensajes

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

Mensajes vistos

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

Más información

Protocolo de traspaso de Messenger : si los mensajes se gestionan mediante más de una aplicación (por ejemplo, una aplicación gestiona las respuestas automáticas y otra gestiona las remisiones a un agente humano), tendrás que implementar el protocolo de traspaso para pasar la conversación de una aplicación a otra.
Clic para dirigir, CTD : visita el Servicio de ayuda para empresas si necesitas más información sobre la creación de anuncios de clic a Instagram Direct.

Ayuda para desarrolladores

Usa la herramienta Meta Status para comprobar el estado y las interrupciones de los productos de Meta para empresas.
Usa la herramienta Ayuda para desarrolladores de Meta para notificar errores y consultar los errores notificados, obtener ayuda con el Administrador de anuncios o Business Manager, etc.
Visita Recursos de ayuda de la plataforma de Messenger para ver más recursos de ayuda para la plataforma de Messenger.