Webhooks para mensajes de Instagram

Los webhooks te permiten recibir notificaciones HTTP en tiempo real sobre cambios en objetos específicos en la gráfica social de Meta. Por ejemplo, podemos enviarte una notificación cuando un cliente envía un mensaje a tu cuenta profesional de Instagram. Las notificaciones de webhooks te permiten hacer un seguimiento de los cambios en los mensajes y evitar los límites de frecuencia que podrían alcanzarse si enviaras consultas a puntos de conexión de la plataforma de Messenger para supervisar cambios.

Requisitos

Es necesario que cumplas los siguientes requisitos para recibir notificaciones de webhooks de los mensajes de Instagram.

Los permisos instagram_basic, instagram_manage_messages y pages_manage_metadata.
Para obtener una notificación de webhooks que incluya datos que pertenezcan o que administren personas que no tienen un ron en la app, es necesario que la app cuente con acceso avanzado.

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

Modos de las apps

Modo de desarrollo: los webhooks solo se envían si la persona que usa la app tiene un rol en ella, incluso si tu app tiene acceso avanzado. Solo puedes acceder a los datos que te pertenecen o que administras.
Modo en vivo: los webhooks se envían según el nivel de acceso.
- Acceso estándar: los webhooks solo se envían sil a persona que usa tu app tiene un rol en ella. Solo puedes acceder a los datos que te pertenecen o que administras.
- Acceso avanzado: los webhooks solo se envían cuando una persona usa tu app, siempre y cuando se hayan otorgado los permisos que figuran en los requisitos previos.

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

Limitaciones

Cuando un cliente reacciona a una imagen de una secuencia de una publicación de Instagram o la reenvía, se incluye en la notificación la primera imagen de la secuencia, que podría ser la imagen que generó la reacción del cliente o la que reenvió.
En la notificación, solo se incluye la URL de la publicación o del contenido multimedia compartido cuando un cliente envía un mensaje con contenido compartido.
No se admiten los mensajes con gif y stickers. Si una persona envía un mensaje con un gif o un sticker, no se activa un webhook ni se envía una notificación de webhook.

Eventos de webhook

Campo "Webhook"	Descripción
`message_reactions`	Se envía una notificación cuando un cliente reacciona a un mensaje o deja de hacerlo. La versión 12.0 de la API Graph y posteriores admiten las reacciones `angry`, `sad`, `wow`, `love`, `like`, `laugh` y `other`.
`messages`	Se envía una notificación cuando un cliente envía lo siguiente a tu empresa: Un mensaje con texto o contenido multimedia (imagen, video, archivo y audio). Un contenido compartido (contenido multimedia y publicaciones). Una mención o respuesta a una historia. Solo las menciones de historias activan un webhook. Sin embargo, no se activa un webhook si se etiqueta una publicación normal. El webhook de respuestas a las historias no admite actualmente ni GIF ni sticker. Una respuesta a un mensaje directo o sticker. Una respuesta rápida, una opción de pregunta para romper el hielo o un botón de plantilla genérica. Un cliente elimina un mensaje. No se admiten los mensajes de los clientes. Un cliente envía un mensaje desde la página de información detallada de un producto de la tienda de Instagram. Un cliente hace clic en un anuncio que dirige a una conversación de mensajes de Instagram (clic a Instagram Direct, CTD) También se envía una notificación cuando una empresa envía un mensaje a un cliente. En cambio, no se envía una notificación cuando una empresa reacciona al mensaje de un cliente o deja de hacerlo. Se devolverá la llamada cuando tu cuenta de Instagram haya enviado un mensaje. Se mostrará la marca `is_echo` para indicarte que el mensaje se envió desde la propia cuenta de Instagram. No se le entregará un webhook eco al 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 botón de plantilla genérica. Se requiere la versión 8.0 o posterior. Se requiere la versión 11.0 o posterior para incluir el campo `mid`.
`messaging_seen`	Se envía una notificación cuando el destinatario lee el mensaje.
`messaging_referral`	Se envía una notificación cuando el cliente hace clic en un enlace `ig.me` con un parámetro de referencia en una conversación actual.
`standby`	Si el flujo de mensajes tiene apps múltiples, se envía una notificación cuando el cliente envía un mensaje a la empresa, aunque la app no controla la conversación en el momento en que se envía el mensaje.

Ejemplo de notificaciones

A continuación, encontrarás ejemplos de 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"       
              }
            }
          }
        }
      ]
    }
  ]
}

Reacción a los 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 
          }
        }
      ]
    }
  ]
}

Mensaje visto

{
   "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 tienes más de una app que procesa mensajes, por ejemplo, una app que procesa respuestas automáticas y otra procesa que escalamientos a un agente humano, deberás implementar el protocolo de traspaso para pasar la conversación de una app a la otra.
Clic a Instagram Direct, CTD : visita el centro de ayuda para empresas a fin de obtener más información sobre la creación de anuncios de clic a Instagram Direct.

Ayuda para desarrolladores

Usa la herramienta Meta Status para revisar el estado y las interrupciones de los productos empresariales de Meta.
Usa la herramienta de ayuda para desarrolladores de Meta a fin de reportar errores y ver los errores reportados, obtener ayuda relacionada con anuncios o el administrador comercial, y más.
Visita los recursos de ayuda de la plataforma de Messenger si quieres ver más recursos de ayuda de la plataforma.