Adjuntos de DM de Instagram en el webhook de mensajes
El webhook de mensajes de Instagram transporta el contenido multimedia de los DM en message.attachments: un arreglo de objetos, cada uno con un type y un payload que normalmente contiene una URL de CDN. La lista de Meta para Instagram Login incluye image, video, audio, file, ig_post, ig_reel, reel, story_mention, media, story, ig_story y el tipo heredado share, y el contenido de una sola vista llega como un adjunto efímero sin URL.
easyCoexistence se suscribe a messages en cada cuenta de Instagram conectada y reenvía los DM con sus adjuntos a tu endpoint HTTPS tal como los envía Meta, firmados con el secreto de esa cuenta y sin conservar copia, para que tu agente o código descargue el contenido que necesite.
Tipo de adjunto para una publicación compartida; su payload añade ig_post_media_id y title, el texto de la publicación, junto a url.
Cuándo dejó de admitirse para Instagram el antiguo tipo de adjunto share en las publicaciones compartidas.
Tipo de adjunto para contenido temporal de una sola vista, que llega sin URL.
Se establece en true en un evento de mensaje cuando el mensaje contiene contenido multimedia no compatible.
Lo que informa una notificación cuando alguien reacciona o reenvía una imagen de una publicación en carrusel.
¿Qué tipos de adjunto puede traer un evento de DM?
Los ejemplos de Meta para Instagram Login enumeran estos valores de message.attachments[].type, cada uno con un objeto payload. La mayoría de los payloads contienen una url al contenido en el CDN de Meta, y Meta documenta campos adicionales en el payload solo para ig_post, así que lee primero el type y después el payload.
¿Cómo es un DM con adjuntos?
Un evento de mensajes cuyo objeto message contiene attachments en lugar de texto, o junto con él. El ejemplo de Meta envía dos elementos multimedia en un mismo mensaje, cada uno con su propio type y payload.url, así que el manejador debe recorrer el arreglo en lugar de leer solo su primer elemento:
{
"object": "instagram",
"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": "<CDN_URL>" } },
{ "type": "video", "payload": { "url": "<CDN_URL>" } }
]
}
}
]
}
]
}¿Cómo es una publicación compartida?
Un adjunto ig_post. Desde el 3 de noviembre de 2025 Meta envió las publicaciones compartidas con los adjuntos share e ig_post a la vez; share se admitió para publicaciones hasta el 1 de febrero de 2026, y Meta indica que las nuevas integraciones deben admitir ig_post. Su payload añade el ID de medio de la publicación y su texto como title:
"attachments": [
{
"type": "ig_post",
"payload": {
"ig_post_media_id": "<MEDIA_ID>",
"title": "<POST_CAPTION>",
"url": "<CDN_URL>"
}
}
]¿Qué significa cada campo?
Los campos de adjuntos que Meta documenta para un evento de DM, desde el arreglo hacia abajo:
- message.attachments[]: un objeto por cada elemento multimedia; el ejemplo de Meta trae dos en un mismo mensaje.
- type: qué es el elemento, de la lista anterior. Ramifica según el type antes de leer el payload.
- payload.url: una URL de CDN para el contenido. La descripción general de Meta llama a estas URL que respetan la privacidad: no devuelven nada una vez que el contenido se elimina o caduca.
- payload.
ig_post_media_idy payload.title: solo enig_post, el ID de medio de la publicación compartida y su texto. - message.text: presente solo cuando el mensaje también contiene texto.
- message.
is_unsupported: true cuando el mensaje contiene contenido multimedia que el webhook no admite.
¿Cuánto tiempo funcionan las URLs de los adjuntos?
Meta las vincula al contenido. Su descripción general dice que las URLs del CDN de Instagram respetan la privacidad y dejan de devolver contenido cuando el material se elimina o caduca, y su guía de menciones en historias indica que la URL de una historia deja de mostrarse cuando la historia caduca o se elimina. Una aplicación que necesita un archivo debe descargarlo al llegar el evento, dentro de las reglas de Meta: el contenido de historias, por ejemplo, no puede almacenarse ni guardarse en caché.
¿Qué contenido omite el webhook?
La guía de mensajería de Instagram de Meta menciona estas excepciones, que un manejador debe esperar y no tratar como errores:
- Contenido temporal, de una sola vista o que permite repetir: un adjunto de tipo ephemeral, sin URL.
- Contenido no compatible: el mensaje llega con
is_unsupporteden true. - GIF y stickers: esa guía dice que no disparan ningún webhook, mientras que los ejemplos de Instagram Login de Meta los listan bajo image.
- La imagen elegida del carrusel: una reacción o un reenvío de una imagen de una publicación en carrusel informa la primera imagen.
- Compartidos en general: las guías de mensajería de Meta aún dicen que solo se incluye la URL del contenido compartido, aunque
ig_postahora añade el ID de medio y el texto.
¿Cómo reenvía easyCoexistence los adjuntos?
Sin cambios, dentro de entry: un DM con contenido multimedia llega a tu endpoint con el array attachments de Meta tal como Meta lo envió, en un sobre de platform, account_id, external_id y entry, firmado con X-EC-Signature. Los adjuntos no se descargan, y los eventos no se guardan por defecto: una cuenta con una automatización activada conserva el texto de un DM, no su contenido multimedia, durante 7 días. Descarga el contenido que necesites desde payload.url cuando llegue el evento, y no almacenes el contenido de historias.
Errores comunes
- Leer solo el primer adjunto. message.attachments es un arreglo, y el ejemplo de Meta trae dos elementos en un mismo mensaje, así que recórrelo.
- Seguir comparando con el type share en las publicaciones compartidas. Meta lo admitió para publicaciones hasta el 1 de febrero de 2026; lee ig_post, con el ID de medio y el texto en su payload.
- Guardar payload.url para descargarlo más tarde. Deja de devolver contenido cuando el material se elimina o caduca, así que descarga lo necesario al llegar, excepto el contenido de historias.
- Leer payload.url sin revisar el type. El contenido de una sola vista llega como ephemeral sin URL, y el contenido no compatible activa is_unsupported en su lugar.
send_social_dm responde dentro de la ventana 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
¿Puedo guardar contenido de un adjunto de DM de Instagram?
Descarga lo que necesites cuando llegue el evento, ya que payload.url deja de devolver contenido cuando el material se elimina o caduca. El contenido de historias es la excepción: las reglas de Meta indican que no puede almacenarse ni guardarse en caché.
¿Por qué un webhook de DM de Instagram no tiene URL de contenido?
Normalmente porque el contenido es de una sola vista, que llega como un adjunto ephemeral sin URL, o porque no es compatible, lo que pone is_unsupported en true.
¿Los GIF y stickers de Instagram disparan el webhook de mensajes?
Los documentos de Meta no coinciden: sus ejemplos de Instagram Login listan los GIF y stickers bajo image, mientras que su guía de mensajería de Instagram dice que no disparan ningún webhook. Pruébalo con una cuenta real.
¿Un mismo evento de DM de Instagram puede traer varios adjuntos?
Sí. message.attachments es un arreglo, y el ejemplo de Meta muestra dos elementos multimedia en un solo mensaje.
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