Webhook de mensajes de Instagram: el payload de DM, ecos y campos
El campo messages del webhook de Instagram entrega los DM de una cuenta profesional a medida que llegan: texto, adjuntos, publicaciones compartidas, respuestas a historias y menciones, respuestas en línea y eliminaciones. Cada evento está en un array messaging con el ID con alcance de Instagram del remitente, el destinatario, una marca de tiempo y un objeto message, y los mensajes que envía la propia cuenta llegan por el mismo campo con is_echo en true.
easyCoexistence suscribe cada cuenta de Instagram conectada a messages y reenvía sus DM, incluidos los ecos, a tu endpoint HTTPS a medida que llegan, firmados con el secreto de esa cuenta; el reenvío no conserva copia, y los DM no se guardan por defecto.
Se pone en true en un evento de mensaje de un mensaje que envió la propia cuenta.
Ventana de mensajería estándar para la mayoría de las acciones del usuario, durante la cual la app puede responder a la persona.
Tipo de adjunto para una publicación compartida; el antiguo tipo de compartir solo se admitió hasta el 1 de febrero de 2026.
Tipo de adjunto del evento DM que Meta envía cuando alguien menciona la cuenta en su historia.
Subcódigo de error, bajo el código 200, cuando el titular de la cuenta ha desactivado el acceso a los mensajes directos de Instagram.
¿Cuándo se activa el campo messages?
Cuando una persona envía a la cuenta profesional un DM, y cuando la cuenta envía uno. Los ejemplos y referencias de Meta listan estos casos, cada uno un evento de mensajería con un objeto message:
- Texto, y medios como adjuntos: imágenes, video, audio y archivos.
- Una publicación o Reel compartido, como adjunto
ig_post,ig_reelo reel. - Una respuesta a una historia de la cuenta, con
reply_to.story, y una historia que menciona la cuenta, como adjuntostory_mention. - Una respuesta en línea a un mensaje anterior, con
reply_to.mid, y una respuesta rápida, conquick_reply.payload. - Un mensaje que la persona eliminó (
is_deleted), contenido no compatible (is_unsupported) y un mensaje de alguien que hizo clic en un anuncio Click-to-Direct (referral). - Un mensaje que envió la cuenta, que llega con
is_echoen true.
¿Cómo es una notificación de mensajes?
Un POST cuyo JSON tiene object con el valor instagram. A diferencia de un comentario, un mensaje va en un array messaging dentro de la entrada de la cuenta, y cada elemento incluye sender, recipient, timestamp y message. Así se ve una respuesta a una historia de la cuenta:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL_FOR_THE_STORY>",
"id": "<STORY_ID>"
}
}
}
}
]
}
]
}¿Qué significa cada campo?
Los campos que Meta documenta para un evento de mensaje con Instagram Login, de fuera hacia dentro:
- entry[].id: el ID de la cuenta profesional. entry[].time: cuándo envió Meta la notificación; en las muestras de mensajería de Meta aparece en milisegundos.
- sender.id y recipient.id: en un DM entrante, el ID con alcance de Instagram de la persona y el ID de la cuenta; en un eco, los mismos dos al revés.
- timestamp: cuándo se envió el mensaje, en milisegundos en las muestras de Meta. Ordena los mensajes por este campo, no por orden de llegada.
- message.mid: el ID del mensaje, para deduplicar, reaccionar y responder a ese mensaje con
reply_to.mid. - message.text: se incluye cuando el mensaje contiene texto.
- message.attachments[]: cada uno con un type y un payload, normalmente una url. El payload
ig_postde una publicación compartida añadeig_post_media_idy title, su pie de foto. - message.
reply_to: mid para una respuesta en línea, o story con la url y el id de la historia para una respuesta a una historia. - message.
quick_reply.payload y message.referral: la respuesta rápida elegida, y el ref,ad_id, source, type yads_context_datadel anuncio Click-to-Direct. - message.
is_deleted,is_echo,is_selfeis_unsupported: solo se incluyen cuando son true. - message.
admin_textyhandoff_reason: en apps elegibles, un aviso de que una aplicación de Meta, como Meta Business Agent, transfirió la conversación; puede llegar sin mid ni text.
¿Cómo funcionan los ecos?
Cuando la cuenta envía un mensaje, Meta también envía un evento de mensajes para él, con is_echo en true. sender.id es entonces la cuenta y recipient.id el ID con alcance de Instagram de la persona, y un mensaje de prueba que la cuenta se envía a sí misma también lleva is_self. Los ecos registran lo que dijo la cuenta, lo que necesita un registro de conversaciones, pero un manejador que decide si responder debe omitirlos. Meta no envía eco cuando la cuenta reacciona a un mensaje o quita una reacción.
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448061203,
"messaging": [
{
"sender": { "id": "<IG_ID>" },
"recipient": { "id": "<IGSID>" },
"timestamp": 1793448060950,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<REPLY_TEXT>",
"is_echo": true
}
}
]
}
]
}¿A qué ID se responde?
A sender.id, el ID con alcance de Instagram de la persona. Meta lo crea cuando alguien escribe a la cuenta o comenta en sus publicaciones, y es específico de esa persona y esa cuenta. POST /<IG_ID>/messages con recipient.id igual a ese valor envía la respuesta. El evento no incluye nombre ni nombre de usuario; GET /<IGSID> con campos como name y username los devuelve, porque una persona que ha escrito a la cuenta ha dado el consentimiento que requiere esa consulta.
¿Cómo abre un mensaje la ventana de 24 horas?
Una app solo puede escribir a una persona después de que esta le haya escrito a la cuenta, y solo dentro de la ventana de mensajería estándar que abre su acción. En la mayoría de las acciones dura 24 horas, y hasta 7 días desde un primer mensaje enviado tras hacer clic en un anuncio Click-to-Direct. Un nuevo mensaje de la persona abre una nueva ventana, así que hay que seguir su marca de tiempo más reciente; un eco es un mensaje de la propia cuenta y no amplía nada. Las respuestas escritas por una persona pueden usar la ventana aparte de 7 días de Human Agent de Meta, etiquetada como human_agent.
¿Qué no incluye un evento de mensajes?
Faltan algunas cosas que un manejador podría buscar, según las referencias de mensajería de Meta:
- El nombre o nombre de usuario de la persona: solo el ID con alcance de Instagram, que GET /<IGSID> resuelve.
- Medios de visualización única: llegan como adjunto efímero sin URL.
- La imagen exacta del carrusel: una reacción a una imagen de una publicación en carrusel, o un reenvío de ella, informa de la primera imagen.
- Reacciones, ediciones y confirmaciones de lectura, que llegan en campos propios.
- Marca de leído: un mensaje entregado por webhook sigue sin leer en la bandeja de Instagram hasta que se envía una respuesta.
¿Qué otros campos de mensajería enumera Meta?
La lista de campos y ejemplos de Meta para Instagram Login nombra estos además de messages, cada uno un evento de mensajería propio. easyCoexistence suscribe cada cuenta solo a messages, comments y mentions, así que ninguno de ellos forma parte de lo que reenvía:
message_reactions: una persona reacciona a un mensaje o quita la reacción, con reaction.mid, action con el valor react o unreact, y los campos reaction y emoji.message_edit: una persona edita un mensaje, conmessage_edit.mid, el texto nuevo ynum_edit.messaging_postbacks: una persona toca un icebreaker o un botón de plantilla, con postback.mid, title y payload.messaging_referral: una persona que ya está en una conversación abre un enlace ig.me con un parámetro ref.messaging_seen: una persona lee un mensaje, con read.mid.messaging_optins,messaging_handovery standby: los dos últimos para apps que comparten una conversación según el protocolo de handover de Meta.
¿Qué debe activar la cuenta?
Permitir el acceso a los mensajes. Meta exige que una cuenta profesional lo active antes de que sus mensajes puedan gestionarse por API, en la app de Instagram, en Configuración, Mensajes y respuestas a historias, Controles de mensajes, Herramientas conectadas. Mientras está desactivado, los envíos fallan con código 200, subcódigo 2534041. La app también necesita instagram_business_basic e instagram_business_manage_messages, con Acceso avanzado para atender cuentas que no posee ni gestiona.
¿Cómo reenvía easyCoexistence un DM?
Igual que con un comentario: cada entrada que Meta entrega para la cuenta se envía por POST a tu endpoint HTTPS dentro de un sobre con platform, account_id, external_id y entry, firmado en X-EC-Signature con el secreto de la cuenta, una vez y sin conservar copia. Los ecos se reenvían junto con el resto, así que revisa is_echo antes de responder. Para contestar, llama a send_social_dm con el account_id y el sender.id del evento como recipient_id, dentro de la ventana de 24 horas. Las automatizaciones que empiezan con un DM se ejecutan con los mismos eventos.
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<IG_ID>",
"entry": {
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{ "type": "image", "payload": { "url": "<URL_FOR_THE_MEDIA>" } }
]
}
}
]
}
}Errores comunes
- Responder a los ecos. Un evento con is_echo es un mensaje de la propia cuenta, y responderle hace que la cuenta entre en un bucle consigo misma.
- Suponer que un mensaje siempre tiene texto. Los adjuntos, las publicaciones compartidas, las menciones en historias y las eliminaciones llegan sin campo text, así que ramifica según lo que contenga el objeto message.
- Ordenar los mensajes por orden de llegada. Meta puede entregar mensajes desordenados tras un fallo, así que ordénalos por timestamp.
- Interpretar time y timestamp como segundos. Las muestras de mensajería de Meta los dan en milisegundos, y leídos como segundos se convierten en fechas muy lejanas en el futuro.
send_social_dm responde dentro de la ventana de 24 horas, y las automatizaciones pueden responder solas con un texto fijo o con IA. De US$ 9 a US$ 0.75 por conexión al mes, con descenso al añadir conexiones, y los primeros 3 días gratis.
Preguntas frecuentes
¿Los timestamps de los webhooks de mensajes de Instagram están en segundos o en milisegundos?
En milisegundos, según las muestras de mensajería de Meta, tanto en timestamp como en la hora de la entrada. Leídos como segundos, se convierten en fechas muy lejanas en el futuro.
¿Cómo obtengo el nombre de usuario del remitente desde un webhook de DM de Instagram?
Llama a GET /<IGSID> con campos como name y username. El evento solo incluye el ID con alcance de Instagram de la persona.
¿Por qué no llegan mis webhooks de DM de Instagram?
Comprueba que la cuenta activó Permitir el acceso a los mensajes, que está suscrita a messages mediante /subscribed_apps, y que la app está en modo Live con Acceso avanzado para cuentas que no posee.
¿easyCoexistence reenvía las reacciones a los mensajes de Instagram?
No. Las reacciones llegan en message_reactions, y easyCoexistence suscribe las cuentas a messages, comments y mentions.
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