Menciones y respuestas a historias de Instagram en el webhook
Instagram entrega las menciones y respuestas a historias como mensajes directos en el campo messages del webhook. Una mención llega como un mensaje cuyos attachments contienen un elemento de tipo story_mention, con la URL CDN de la historia en payload.url. Una respuesta trae el texto de la persona y reply_to.story con la url y el id de la historia y, si la historia tiene un sticker de enlace, link_sticker_url.
easyCoexistence suscribe cada cuenta de Instagram a messages, reenvía las menciones y respuestas a Stories a tu endpoint HTTPS, firmadas por cuenta y sin almacenarse por defecto, y send_social_dm responde dentro de la ventana de 24 horas.
Tipo de adjunto del evento messages que Meta envía cuando alguien menciona la cuenta en su historia.
Campo que Meta añadió a reply_to.story el 12 de diciembre de 2025, con la URL del sticker de enlace de la historia respondida.
Duración de una historia; una vez que caduca o se elimina, su URL de mención deja de mostrarse.
Cuentas cuyas menciones en historias llegan; la mención de una cuenta privada solo llega si sigue a la cuenta profesional.
Respuestas a historias que el webhook no admite, según la guía de mensajería de Instagram de Meta.
¿Cómo llega una mención en una historia?
Como mensaje directo. Cuando alguien menciona la cuenta profesional en su historia, Instagram coloca en la bandeja de entrada de la cuenta un mensaje que hace referencia a esa historia, y Meta envía para él un evento messages. sender.id es el ID de Instagram con ámbito de la persona, y message.attachments contiene un elemento de tipo story_mention cuyo payload.url es la URL CDN de la historia. Los ejemplos de Meta no muestran texto, así que hay que leer el adjunto:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{
"type": "story_mention",
"payload": { "url": "<CDN_URL>" }
}
]
}
}
]
}
]
}¿Cómo llega una respuesta a una historia?
También como mensaje directo, con el texto de la persona y un objeto reply_to que apunta a la historia de la cuenta. reply_to.story trae la url CDN de la historia y su id. La referencia de webhooks de Meta incluye además link_sticker_url, añadido en diciembre de 2025 para respuestas a historias con sticker de enlace, que Meta sugiere usar para enrutar automatizaciones por enlace. Una respuesta en línea a un mensaje anterior usa reply_to.mid en su lugar.
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL>",
"id": "<STORY_ID>"
}
}
}¿Qué significa cada campo?
Los campos que Meta documenta para estos dos eventos, de fuera hacia dentro:
- entry[].id y recipient.id: la cuenta profesional. sender.id: el ID de Instagram con ámbito de la persona, al que se dirige una respuesta.
- timestamp: cuándo se envió el mensaje, en milisegundos en los ejemplos de Meta; entry[].time es cuándo Meta envió la notificación.
- message.mid: el ID del mensaje, para deduplicar reintentos y para responder con
reply_to.mid. - attachments[].type
story_mentiony payload.url: una mención, y la URL CDN de la historia que la originó. reply_to.story.url yreply_to.story.id: la historia de la cuenta a la que respondió la persona.reply_to.story.link_sticker_url: la URL del sticker de enlace de esa historia.- message.text: las palabras de la respuesta, incluidas cuando el mensaje contiene texto.
¿Cuánto tiempo funciona la URL de la historia?
Mientras dure la historia. Una historia desaparece a las 24 horas o cuando su autor la elimina, y la guía de menciones en historias de Meta indica que entonces la URL deja de mostrarse; su resumen añade que las URL CDN de Instagram tienen en cuenta la privacidad y no devuelven nada para contenido eliminado o caducado. La misma guía permite conservar la URL CDN pero no el medio: una aplicación no debe almacenar ni guardar en caché el contenido de la historia en sus servidores, y debe mostrar un marcador de posición cuando la historia ya no existe.
¿Cuándo no se dispara ninguno de los dos eventos?
Las guías de Meta señalan estos casos, en los que un manejador que espera un evento de historia no recibe nada:
- Una mención en historia de una cuenta privada que no sigue a la cuenta profesional.
- Una etiqueta en una publicación normal: Meta indica que solo las menciones en historias disparan el webhook de mensajes, no el etiquetado en publicaciones.
- Una respuesta a una historia hecha con un GIF o un sticker, que el webhook no admite.
- Historias a través de la API de menciones: GET /<
IG_ID>/tags y POST /<IG_ID>/mentions no las admiten, así que el mensaje directo es la forma en que llega una mención en historia.
¿Las menciones y respuestas en historias abren la ventana de mensajería?
Una respuesta es un mensaje de la persona, y Meta incluye las menciones en historias entre los canales por los que una persona inicia una conversación. La ventana que abre su acción dura 24 horas para la mayoría de acciones, así que la cuenta puede responder con POST /<IG_ID>/messages y recipient.id igual al sender.id del evento mientras esté abierta. La respuesta de la cuenta vuelve en messages como un eco, con is_echo en true.
¿Cómo reenvía easyCoexistence estos eventos?
Por el campo messages, al que se suscribe cada cuenta conectada, de modo que las menciones y respuestas en historias llegan a tu endpoint junto con los demás mensajes directos de la cuenta: cada entrada dentro de un sobre con platform, account_id, external_id y entry, firmada en X-EC-Signature con el secreto de la cuenta, enviada una sola vez y sin conservar copia. send_social_dm responde a la persona usando el sender.id del evento como recipient_id, dentro de la ventana de 24 horas.
POST <YOUR_ENDPOINT>
Content-Type: application/json
X-EC-Signature: t=1793448001,v1=<HEX_HMAC_SHA256>
{
"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": "story_mention", "payload": { "url": "<CDN_URL>" } }
]
}
}
]
}
}Errores comunes
- Almacenar el medio de la historia. La guía de menciones en historias de Meta permite conservar la URL CDN, no el contenido, que no debe guardarse ni cachearse en tus servidores.
- Leer solo message.text. Una mención en historia trae un adjunto de tipo story_mention y, en los ejemplos de Meta, ningún texto, así que un manejador que solo lee texto ve un mensaje vacío.
- Mostrar la URL de la historia días después. Deja de funcionar cuando la historia caduca a las 24 horas o se elimina, así que a partir de entonces muestra un marcador de posición.
- Buscar menciones en historias en el campo comments o en la API de menciones. Meta las entrega como mensajes directos en messages.
easyCoexistence se suscribe a messages en cada cuenta de Instagram conectada, de modo que las menciones y respuestas en historias llegan a tu endpoint HTTPS junto con sus demás mensajes directos en cuanto se producen, firmadas con el secreto de esa cuenta y sin conservar copia. send_social_dm responde a la persona dentro de la ventana de 24 horas, desde Claude, ChatGPT o tu propio código. 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
¿Un evento de mención en una historia de Instagram incluye texto?
No en los ejemplos de Meta. Una mención en historia trae un adjunto de tipo story_mention con la URL CDN de la historia, así que un manejador que solo lee message.text recibe un mensaje vacío.
¿Qué es link_sticker_url en una respuesta a una historia de Instagram?
Es la URL del sticker de enlace de la historia a la que respondió la persona, en reply_to.story.link_sticker_url. Meta lo añadió el 12 de diciembre de 2025 y sugiere usarlo para enrutar automatizaciones por enlace.
¿Las respuestas con GIF o sticker a una historia disparan el webhook?
No. La guía de mensajería de Instagram de Meta indica que el webhook no admite respuestas a historias hechas con un GIF o un sticker.
¿Las cuentas privadas disparan webhooks de menciones en historias?
Solo cuando la cuenta privada sigue a la cuenta profesional. Las menciones de cuentas públicas llegan en cuanto ocurren.
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