La respuesta en una frase
graph.facebook.com/v21.0), el mismo sistema de autenticación y la misma configuración de App. "Instagram Messaging API" es la etiqueta de marketing que Meta da a las capacidades específicas de DM dentro de la Graph API más amplia.La confusión surge porque Meta comercializa diferentes capacidades de API bajo distintos nombres de producto: "Instagram Graph API" para la plataforma completa, "Instagram Messaging API" o "Messenger API for Instagram" para el subconjunto específico de DM. Las personas desarrolladoras que buscan "Instagram Messaging API" a menudo encuentran documentación que parece describir un sistema completamente distinto. No lo es. Configuras una sola Facebook App, obtienes un único conjunto de tokens y usas endpoints y permisos diferentes según lo que estés construyendo.
¿Qué es la Instagram Graph API?
La Instagram Graph API es la API oficial y completa para cuentas de Instagram Business y Creator. Es la única vía legítima para acceder de forma programática a los datos y la funcionalidad de Instagram: desde publicar contenido hasta leer analíticas o responder DMs, todo fluye a través de ella.
La Graph API cubre seis grandes áreas de capacidades:
- Gestión de contenido — crea, publica y recupera posts, reels, historias y carruseles en nombre de una cuenta de negocio
- Insights de medios — lee impresiones, alcance, engagement y datos de audiencia para medios individuales y métricas a nivel de cuenta
- Comentarios — lee comentarios en posts, responde, elimina y oculta comentarios
- Búsqueda por hashtag — busca posts públicos por hashtag (con límites de tasa importantes)
- Menciones — detecta cuándo otras cuentas mencionan o etiquetan a tu cuenta de negocio en posts o historias
- Mensajes directos — recibe y envía DMs, gestiona respuestas a historias y menciones en historias (este es el subconjunto de la "Messaging API")
Las seis áreas forman parte de la misma Graph API. La URL base, el sistema de autenticación, el proceso de App Review y el tipo de token son idénticos en todas ellas. Las diferencias están en qué endpoints llamas, qué permisos solicitas y a qué campos de webhook te suscribes.
¿Qué es específicamente la "Instagram Messaging API"?
Cuando Meta (y la mayoría de la documentación de terceros) se refiere a la "Instagram Messaging API" o "Messenger API for Instagram", se refiere al subconjunto de la Graph API que permite:
- Recibir DMs — eventos de webhook cuando los usuarios envían un mensaje directo a tu cuenta de negocio
- Enviar DMs — llamar a
POST /{ig-user-id}/messagespara enviar una respuesta al IGSID de un usuario - Respuestas a historias — eventos de webhook cuando los usuarios responden a tu historia mediante DM (llegan con
message.reply_to.story) - Menciones en historias — eventos de webhook cuando los usuarios etiquetan a tu cuenta en su historia (llegan como un evento de referral)
- Reacciones con emoji — eventos de webhook cuando los usuarios reaccionan a uno de tus mensajes
- Confirmaciones de lectura — eventos de webhook cuando los usuarios leen tus mensajes
Este es un subconjunto enfocado, solo de DMs, de todo lo que puede hacer la Graph API completa. Requiere permisos de mensajería específicos (instagram_manage_messages), suscripciones de webhook específicas (messages, messaging_referrals) y su propio endpoint de envío. Pero corre sobre la misma infraestructura, la misma autenticación y la misma App que el resto.
Mapa completo de endpoints: Graph API vs Messaging API
Aquí tienes un mapa completo de los endpoints de la Instagram Graph API, etiquetados según si son exclusivos de la Graph API, exclusivos de la Messaging API (el subconjunto "Messaging API") o aplican a ambas:
Permisos: qué necesitas para cada capacidad
Los permisos son la forma más clara de distinguir qué requiere la "Messaging API" frente a lo que necesita el resto de la Graph API. Cada permiso requiere App Review para usarse en producción más allá de cuentas de prueba.
| Permiso | Categoría | Qué habilita |
|---|---|---|
| instagram_manage_messages | Messaging API | Recibir eventos de webhook de DM. Enviar respuestas de DM vía /{ig-user-id}/messages. Acceder al historial de conversaciones. Requerido para toda automatización de DM. |
| pages_messaging | Messaging API | Suscribir y recibir eventos de webhook a través de la Facebook Page vinculada. Sin esto, los webhooks de DM de Instagram no se disparan, sin importar qué otros permisos tengas. |
| pages_read_engagement | Ambas | Leer información básica sobre la Facebook Page vinculada y la cuenta de Instagram. Requerido tanto por las funciones de mensajería como de Graph API para verificar la cuenta. |
| instagram_manage_insights | Graph API | Leer datos analíticos a nivel de cuenta y de medio, incluidos impresiones, alcance, engagement y demografía de seguidores. Para dashboards de analítica y herramientas de reporting. |
| instagram_content_publish | Graph API | Crear y publicar posts, reels, historias y carruseles en nombre de una cuenta de negocio. Para herramientas de programación y publicación de contenido. |
| instagram_manage_comments | Graph API | Leer, responder, ocultar y eliminar comentarios en posts. Para herramientas de gestión de comentarios y automatizaciones comment-to-DM (también necesita instagram_manage_messages para el paso de envío del DM). |
| instagram_basic | Graph API | Leer información básica de perfil y lista de posts. Suele incluirse como permiso base junto con permisos más específicos en la mayoría de casos de uso de la Graph API. |
Suscripciones de webhook: mensajería vs todo lo demás
Las suscripciones a campos de webhook son donde la Messaging API y el resto de la Graph API se separan con más claridad. Todas las suscripciones pasan por la configuración de Instagram Webhooks de tu Facebook App, pero los campos a los que te suscribes determinan qué eventos recibes:
El solapamiento más confuso: los eventos relacionados con historias se reparten entre dos campos de webhook distintos. Un usuario que responde a tu historia es un evento de mensajería (campo messages). Un usuario que etiqueta a tu cuenta en su propia historia es un evento de referral (campo messaging_referrals). Una cuenta que te menciona en un pie de foto es un evento ajeno a mensajería (campo mentions). Tres campos de webhook distintos para tres interacciones aparentemente similares.
La antigua Instagram API obsoleta: qué era y por qué importa
La pregunta de Stack Overflow de 2019 que suele aparecer en esta búsqueda comparaba dos cosas que ya no existen en su forma actual: la "Instagram API" (hoy totalmente obsoleta) y la "Instagram Graph API" (la vigente). Entender esta historia explica por qué tantas respuestas en línea están equivocadas.
Matriz de decisión: qué usar según tu caso de uso
instagram_manage_messages, pages_messaging. Campos de webhook: messages, messaging_referrals.instagram_manage_insights, instagram_basic.instagram_content_publish, instagram_basic.instagram_manage_comments.instagram_manage_comments + instagram_manage_messages.Preguntas frecuentes
graph.facebook.com/v21.0), el mismo sistema de autenticación y la misma configuración de Facebook App. "Instagram Messaging API" es el nombre de producto de Meta para las capacidades específicas de DM dentro del marco más amplio de la Graph API.instagram_manage_messages + pages_messaging + pages_read_engagement. Analíticas (Graph API): instagram_manage_insights + instagram_basic. Publicación de contenido (Graph API): instagram_content_publish + instagram_basic. Comentarios (Graph API): instagram_manage_comments. Todos requieren App Review para uso en producción.api.instagram.com. Permitía el acceso a cuentas personales y usaba un OAuth específico de Instagram. Se apagó por completo en marzo de 2020 y ya no funciona. Todas las integraciones actuales de Instagram deben usar la Instagram Graph API (graph.facebook.com). Cualquier tutorial que mencione "api.instagram.com" describe un sistema roto y obsoleto.messages. Para menciones en historias (cuando los usuarios etiquetan tu cuenta en su historia): campo messaging_referrals. Para @menciones en pies de foto o comentarios de posts: campo mentions (ajeno a mensajería, Graph API). Para comentarios en posts: campo comments (Graph API). Suscríbete a todos los campos que necesites en la configuración de Instagram Webhooks de tu Facebook App.POST /v21.0/{ig-user-id}/messages llamado contra graph.facebook.com. El ig-user-id es el ID numérico de tu Instagram Business Account (también el valor entry[0].id en los webhooks entrantes). El cuerpo de la petición: {"recipient": {"id": "USER_IGSID"}, "message": {"text": "your reply"}}. Autenticado con un Page Access Token que tenga el permiso instagram_manage_messages.La capa del webhook de la Messaging API,
resuelta por ti.
Ahora que sabes que la Messaging API es un subconjunto de la Graph API, el siguiente paso es recibir esos eventos en tu servidor. SocialHook se encarga de la verificación HMAC, del parseo del payload crudo y de la normalización de eventos: cada DM, respuesta a historia y mención en historia llega como JSON limpio a tu endpoint.