Webhook message_reactions de Instagram: el payload de react y unreact
El campo de webhook message_reactions de Instagram avisa a una app cuando una persona reacciona a un mensaje de su conversación con una cuenta profesional, o cuando quita esa reacción. El evento va en el array messaging, con un objeto reaction: mid, el ID del mensaje al que se reaccionó; action, react o unreact; y, solo en un react, reaction, como love, y emoji, el emoji en sí.
easyCoexistence suscribe cada cuenta de Instagram conectada a comments, messages y mentions, y reenvía esos eventos a tu endpoint HTTPS en cuanto llegan, firmados con el secreto de esa cuenta, y cada mensaje con su mid.
Los dos valores de reaction.action: se añade una reacción, o se quita una reacción.
Versión de Graph API desde la que Meta admite angry, sad, wow, love, like, laugh y otras reacciones en este webhook.
Meta no envía ninguna notificación cuando la propia cuenta reacciona a un mensaje de una persona o quita su reacción.
message_reactions está entre los campos a los que se suscribe por defecto un nuevo producto de Instagram en el App Dashboard.
Llamadas por segundo por cuenta a la Send API para texto, enlaces, reacciones y stickers.
¿Cuándo se dispara message_reactions?
Cuando una persona reacciona a un mensaje de su conversación con la cuenta profesional, y de nuevo cuando quita esa reacción, una vez que la app y la cuenta están suscritas al campo. La guía de mensajería de Instagram de Meta es explícita en la otra dirección: cuando la propia cuenta reacciona o quita una reacción, no se envía ninguna notificación, y messages tampoco entrega ecos para ella.
¿Cómo es una notificación de reacción?
Un POST con object igual a instagram, cuya entry contiene un array messaging. A diferencia de un DM, el evento no lleva objeto message: la reacción va en su propio objeto reaction, junto a sender, recipient y timestamp. Este es el ejemplo de Meta para Instagram Login:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"reaction": {
"mid": "<MESSAGE_ID>",
"action": "react",
"reaction": "love",
"emoji": "\u{2764}\u{FE0F}"
}
}
]
}
]
}¿Qué significa cada campo?
Los campos que Meta documenta para un evento de reacción, de fuera hacia dentro:
- entry[].id y recipient.id: la cuenta profesional. sender.id: el ID con alcance de Instagram de la persona que reaccionó.
- timestamp: cuándo se disparó el evento, en milisegundos en los ejemplos de Meta; entry[].time es cuándo Meta envió la notificación.
- reaction.mid: el ID del mensaje al que se reaccionó, el mismo mid que ese mensaje tenía en su evento messages.
- reaction.action: react cuando se añade una reacción, unreact cuando se quita.
- reaction.reaction: el nombre de la reacción, como love; Meta enumera angry, sad, wow, love, like, laugh y other.
- reaction.emoji: el emoji como cadena Unicode, como \u{2764}\u{FE0F} para love.
- En unreact, reaction y emoji se omiten.
¿Cómo es un unreact?
El mismo evento con action igual a unreact y sin reaction ni emoji, ya que no queda nada que nombrar. Asócialo a la reacción que quita mediante reaction.mid y sender.id, y elimina la reacción de esa persona en el mensaje de tus registros.
"reaction": {
"mid": "<MESSAGE_ID>",
"action": "unreact"
}¿A qué mensaje apunta mid?
Al mensaje al que la persona reaccionó, bajo el mismo mid que tenía en su evento messages, incluidos los ecos de los propios mensajes de la cuenta. Un handler que guarde los mid puede asociar la reacción a la línea correcta de la conversación. Meta señala una limitación: una reacción a una imagen de una publicación en carrusel informa la primera imagen del carrusel, que puede no ser la elegida.
¿Cómo reacciona una cuenta a un mensaje?
Con POST /<IG_ID>/messages: recipient.id igual al ID con alcance de Instagram de la persona, sender_action igual a react, y un payload con message_id y reaction, un emoji o su forma UTF-8. Repetir la llamada con otro emoji cambia la reacción, y sender_action igual a unreact con solo message_id la quita. Ninguna de las dos llamadas genera un webhook.
POST https://graph.instagram.com/<IG_ID>/messages
Authorization: Bearer <INSTAGRAM_USER_ACCESS_TOKEN>
Content-Type: application/json
{
"recipient": { "id": "<IGSID>" },
"sender_action": "react",
"payload": {
"message_id": "<MESSAGE_ID>",
"reaction": "<EMOJI>"
}
}¿Qué necesita message_reactions?
Con Instagram Login, instagram_business_basic e instagram_business_manage_messages, y Advanced Access para cuentas que el desarrollador no posee ni gestiona. Un nuevo producto de Instagram en el App Dashboard se suscribe por defecto a message_reactions, y cada cuenta se suscribe mediante POST /<IG_ID>/subscribed_apps. La guía Send Messages de Meta lo enumera como messaging_reactions, pero su tabla de campos, los valores por defecto del panel y la referencia de webhooks dicen message_reactions.
¿easyCoexistence reenvía las reacciones?
No. La app de easyCoexistence y cada cuenta conectada están suscritas solo a comments, messages y mentions, así que los eventos message_reactions no se reenvían a tu endpoint. Los DM y ecos a los que apuntan las reacciones por su mid sí llegan, firmados con el secreto de la cuenta.
Errores comunes
- Buscar la reacción dentro de message. Un evento de reacción no tiene objeto message; lee el objeto reaction junto a sender y recipient.
- Leer reaction o emoji sin revisar action. Ambos se omiten en unreact, así que el código que los da por hechos falla cuando se quita una reacción.
- Esperar un webhook cuando la cuenta reacciona. Meta no envía ninguno para las reacciones propias de la cuenta, ni siquiera un eco, así que regístralas cuando tu app las envíe.
- Copiar el nombre messaging_reactions de la guía Send Messages de Meta. El campo en su tabla de campos, en los valores por defecto del panel y en la referencia de webhooks es message_reactions.
Tu agente responde a una persona con send_social_dm dentro de la ventana de atención de 24 horas. De US$ 9 a US$ 0.75 por conexión al mes, bajando a medida que añades conexiones, con los primeros 3 días gratis.
Preguntas frecuentes
¿Por qué una reacción en una publicación en carrusel apunta a la primera imagen?
Meta informa la primera imagen del carrusel cuando alguien reacciona a una de sus imágenes, que puede no ser la imagen que la persona eligió.
¿Instagram envía un webhook cuando la empresa reacciona a un mensaje?
No. Meta no envía ninguna notificación message_reactions ni eco cuando la cuenta reacciona o quita una reacción a un mensaje.
¿Qué reacciones puede informar el webhook de Instagram?
La guía de mensajería de Instagram de Meta enumera angry, sad, wow, love, like, laugh y other desde Graph API v12.0, con el propio emoji en reaction.emoji.
¿El campo del webhook es message_reactions o messaging_reactions?
message_reactions. La guía Send Messages de Meta escribe messaging_reactions, pero su tabla de campos, los valores por defecto del App Dashboard y la referencia de webhooks usan message_reactions.
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