Iniciar sesiónEmpezar prueba gratis
easyCoexistence APIs oficiales

Webhook messaging_postbacks de Instagram: ice breakers y botones

El campo messaging_postbacks del webhook de Instagram notifica a una app cuando una persona toca una pregunta de ice breaker, un botón postback en una plantilla o un elemento del menú persistente en una conversación con una cuenta profesional. El objeto postback del evento incluye title, el texto que la persona tocó; payload, la cadena que la app definió para esa opción; y mid, el ID del mensaje, desde Graph API v11.0.

easyCoexistence suscribe cada cuenta de Instagram conectada a comments, messages y mentions y reenvía esos eventos, incluidos los toques de respuestas rápidas, a tu endpoint HTTPS a medida que llegan, firmados con el secreto de esa cuenta y sin guardar copia.

4

Máximo 4 preguntas de ice breaker que una cuenta puede configurar mediante la Ice Breaker API de Meta.

v11.0

Versión de Graph API desde la que los eventos postback incluyen mid; el campo en sí requiere v8.0 o posterior.

3

Máximo 3 botones en un mensaje de plantilla de botones, cada uno de tipo postback o web_url.

24 hours

Tiempo para responder después de que una persona toca un elemento del menú persistente, que abre la ventana de mensajería estándar.

13

Máximo de respuestas rápidas que ofrece un mensaje; una respuesta rápida tocada llega en messages, no en messaging_postbacks.

¿Cuándo se dispara messaging_postbacks?

Cuando una persona toca una de las opciones estructuradas de la cuenta en una conversación, una vez que la app y la cuenta están suscritas al campo. Las guías de Meta enumeran estas fuentes:

  • Una pregunta de ice breaker, de hasta 4 que la cuenta ofrece al iniciar una conversación. No disponible en escritorio.
  • Un botón postback en una plantilla de botones, hasta 3 por mensaje, o en una plantilla genérica, hasta 3 por elemento.
  • Un elemento postback del menú persistente de la cuenta.
  • Un ice breaker tocado en una conversación nueva abierta desde un enlace ig.me con un parámetro ref: el postback entonces incluye también referral.
  • Una prueba de automensaje, en la que la cuenta toca su propio botón: el evento añade is_self con valor true.

¿Cómo se ve una notificación de postback?

Un evento de mensajería con un objeto postback donde un DM tendría su mensaje. El ejemplo de Meta para Instagram Login incluye mid, title y payload, y su guía de ice breakers muestra el mismo objeto sin mid. Una notificación se ve así:

A messaging_postbacks notification, as Meta sends it
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448000512,
      "messaging": [
        {
          "sender": { "id": "<IGSID>" },
          "recipient": { "id": "<IG_ID>" },
          "timestamp": 1793447999874,
          "postback": {
            "mid": "<MESSAGE_ID>",
            "title": "<ICE_BREAKER_QUESTION_OR_BUTTON_TITLE>",
            "payload": "<PAYLOAD_SET_FOR_THE_OPTION>"
          }
        }
      ]
    }
  ]
}

¿Qué significa cada campo?

Los campos que Meta documenta para un postback, de fuera hacia dentro:

  • sender.id: el ID con alcance de Instagram de la persona que tocó, el ID al que responder. recipient.id y entry[].id: la cuenta profesional.
  • timestamp: cuándo tocó la persona, según la guía de ice breakers de Meta.
  • postback.title: la pregunta de ice breaker o el título del botón que vio la persona.
  • postback.payload: la cadena definida para esa opción al crearla, elegida por la app.
  • postback.mid: el ID del mensaje que el toque envió a la cuenta, desde Graph API v11.0.
  • postback.referral: ref, source y type, cuando la conversación se abrió desde un enlace ig.me con un parámetro ref.
  • is_self: con valor true, junto a postback, cuando la cuenta toca su propio botón en una prueba de automensaje.

¿Cómo se configuran los ice breakers?

Con POST /<IG_ID>/messenger_profile en graph.instagram.com: platform con valor instagram y un array ice_breakers cuyos call_to_actions contienen hasta 4 pares de pregunta y payload, con un locale para cada conjunto traducido. GET /me/messenger_profile?fields=ice_breakers los lista, y un DELETE con fields igual a ice_breakers los elimina. El payload elegido aquí es lo que messaging_postbacks devuelve cuando se toca la pregunta.

Setting two ice breakers
POST https://graph.instagram.com/<IG_ID>/messenger_profile?access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
Content-Type: application/json

{
  "platform": "instagram",
  "ice_breakers": [
    {
      "call_to_actions": [
        { "question": "<QUESTION_1>", "payload": "<PAYLOAD_1>" },
        { "question": "<QUESTION_2>", "payload": "<PAYLOAD_2>" }
      ]
    }
  ]
}

¿Cómo se envían los botones postback?

Dentro de un mensaje que la cuenta envía con POST /<IG_ID>/messages. Una plantilla de botones admite texto de hasta 640 caracteres y de 1 a 3 botones; una plantilla genérica admite hasta 10 elementos, cada uno con hasta 3 botones. Un botón de tipo postback devuelve su payload en messaging_postbacks al tocarlo, mientras que un botón web_url abre una página en el navegador integrado de la app. El menú persistente, configurado en messenger_profile, admite esos mismos dos tipos.

¿Las respuestas rápidas usan messaging_postbacks?

No: llegan en messages. Una respuesta rápida tocada publica su título en la conversación como un mensaje, y el evento messages trae text con ese título y quick_reply.payload con el payload de la opción. Un mensaje puede ofrecer hasta 13 respuestas rápidas de hasta 20 caracteres cada una, solo texto plano. La guía de Instagram Messaging de Meta también incluye las selecciones de ice breaker y de plantilla genérica entre lo que reporta messages, sin un ejemplo de payload.

¿Un toque abre la ventana de mensajería?

En el menú persistente, Meta lo indica: tocar un elemento del menú abre la ventana de mensajería estándar, y la cuenta tiene 24 horas para responder. Responde con POST /<IG_ID>/messages y recipient.id igual al sender.id del postback. La respuesta de la cuenta llega en messages como un echo, con is_echo en true.

¿easyCoexistence reenvía los postbacks?

Solo los toques en respuestas rápidas. Llegan en messages, al que están suscritas la app de easyCoexistence y cada cuenta conectada, así que llegan a tu endpoint con quick_reply.payload. Los toques en ice breakers, botones y menús llegan en messaging_postbacks, al que easyCoexistence no se suscribe, así que no se reenvían.

Errores comunes

  • Esperar respuestas rápidas en messaging_postbacks. Una respuesta rápida llega en messages, con quick_reply.payload junto al texto de la opción tocada.
  • Enrutar según postback.title. El título es lo que vio la persona y puede variar según el locale; enruta según payload, que define la app.
  • Esperar mid en una versión antigua de la API. Meta incluye postback.mid solo desde Graph API v11.0.
  • Configurar más de 4 ice breakers, o probarlos en escritorio. La Ice Breaker API de Meta admite hasta 4 preguntas, y la función no está disponible en escritorio.
Hacerlo con EasyCoexistence

send_social_dm responde a la persona dentro de la ventana de 24 horas. De US$ 9 a US$ 0.75 por conexión al mes, según se añaden conexiones, con los primeros 3 días gratis.

Preguntas frecuentes

¿Qué campo del webhook informa los toques en ice breakers de Instagram?

messaging_postbacks. El objeto postback trae la pregunta como title y el payload definido para ella, además de mid desde Graph API v11.0.

¿Cuántos ice breakers puede tener una cuenta de Instagram?

Hasta 4 preguntas, configuradas con POST /<IG_ID>/messenger_profile y platform con valor instagram, opcionalmente por locale.

¿Cómo respondo a un postback de Instagram?

Con POST /<IG_ID>/messages y recipient.id igual al sender.id del postback, el ID con alcance de Instagram de la persona que tocó. Tras un toque en el menú persistente, Meta da a la cuenta 24 horas para responder.

¿Debo enrutar los postbacks de Instagram según title o payload?

Según payload, la cadena que la app definió para la opción. title es el texto que vio la persona, que puede variar según el locale.

Sigue leyendo

Conecta tu primer canal en dos minutos.

Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.

  • 3 días gratis
  • Cancela cuando quieras
  • Solo APIs oficiales
  • Monitorizado 24/7

Verificado el