Recibe Instagram DMs en tu servidor — configuración del webhook oficial de la Messaging API, identificador IGID, esquemas de payload para DMs, menciones en stories y reacciones, código en Node.js
En esta guía: Por qué solo la API oficial · Requisitos de la cuenta · Permisos necesarios · IGID explicado · Pasos para configurar el webhook · Esquemas de todos los tipos de evento · Menciones y respuestas en stories · Reacciones · Responder con la Send API · Formato normalizado de SocialHook

Por qué la API oficial — y solo la API oficial

La mayoría de los tutoriales de "automatización de DMs de Instagram" usan métodos no oficiales: automatización de navegador, scraping de tokens de sesión, herramientas de automatización de terceros que evitan la API de Instagram. Todos violan los Términos de Servicio de Instagram. Instagram detecta y banea activamente las cuentas que los utilizan — a veces de forma permanente, a menudo sin advertencia ni apelación.

La Instagram Messaging API oficial es el único enfoque que es:

  • Sancionado por Meta y conforme con los ToS de Instagram
  • Elegible para uso empresarial a escala (hasta 1.000 llamadas a la API por hora por usuario)
  • Cubierto por el SLA de Meta y la fiabilidad de su infraestructura
  • Seguro para la cuenta de Instagram de tu negocio a largo plazo

Esta guía cubre exclusivamente la Instagram Messaging API oficial de Meta Graph API v21.0.

Requisitos de la cuenta: lo que necesitas antes de escribir código

La Instagram Messaging API tiene requisitos de cuenta más estrictos que la Messenger API. Los tres siguientes deben cumplirse:

  1. Cuenta profesional de Instagram: Tu cuenta de Instagram debe estar convertida a una cuenta de Negocio o Creador (no una cuenta personal). Hazlo en la app de Instagram → Configuración → Cuenta → Cambiar a cuenta profesional. Las cuentas de Creador tienen funciones ligeramente diferentes a las de Negocio — para la automatización de DMs, ambas funcionan.
  2. Página de Facebook vinculada: Tu cuenta profesional de Instagram debe estar conectada a una Página de Facebook de la que seas propietario y administrador. Esto es obligatorio — la Instagram Messaging API se autentica a través de la infraestructura de Facebook. Conéctalas en Configuración de Instagram → Cuenta → Cuentas vinculadas → Facebook.
  3. App de Desarrollador de Facebook: Una App de Facebook con el producto Instagram añadido. Tu cuenta Instagram Business Account debe estar enlazada en la configuración de Instagram de la App. Aquí es donde generas access tokens y registras tu webhook.
Las cuentas personales de Instagram no pueden usar la Messaging API. Si trabajas con una cuenta personal, primero debes convertirla a Profesional. Es gratis y reversible — cambiar a Profesional no cambia tu contenido, tus seguidores ni tu flujo de publicación. Solo añade funciones empresariales, incluido el acceso a la API.

Permisos necesarios

Permiso¿Obligatorio?Qué permite
instagram_manage_messages Obligatorio Recibir eventos de webhook de DMs y enviar mensajes en nombre de la cuenta de Instagram. Es el permiso central para todo lo que se ve en esta guía.
pages_messaging Obligatorio Suscribirse y recibir eventos de webhook a través de la Página de Facebook vinculada. Sin esto, los webhooks de DMs de Instagram no se disparan.
pages_read_engagement Obligatorio Leer la información de la Instagram Business Account necesaria para la suscripción al webhook y la validación de tokens.
instagram_manage_insights Opcional Acceder a insights y analíticas de la cuenta de Instagram. No se necesita para la recepción/envío puro de DMs.
instagram_basic Opcional Leer la información básica de perfil de la cuenta de Instagram conectada. Útil para verificar la configuración del perfil.
App Review obligatorio para producción. Durante el desarrollo, los permisos funcionan para cuentas añadidas como Test Users en la configuración de tu App. Para producción (recibir DMs de clientes reales que no se han añadido como test users), debes someter la solicitud a App Review. La revisión pide una descripción de tu caso de uso y normalmente tarda entre 5 y 10 días hábiles. Prepara una descripción clara del caso de uso y una grabación de pantalla mostrando tu bot en acción.

Instagram-Scoped ID (IGSID): cómo identifica Instagram a los usuarios

Cuando un usuario de Instagram envía un DM a tu cuenta de empresa, Instagram lo identifica ante tu webhook usando su IGSID (Instagram-Scoped ID) — una cadena numérica opaca y única, específica de tu Instagram Business Account.

Datos clave sobre los IGSIDs:

  • Específicos del scope. El mismo usuario tiene un IGSID distinto para cada Instagram Business Account a la que envía mensajes. El IGSID del Usuario A en tu cuenta es diferente del IGSID que tiene en la cuenta de un competidor — privacidad por diseño.
  • No es lo mismo que el PSID. Aunque también operes una Página de Facebook conectada a la misma cuenta de Instagram, el PSID del usuario en Facebook Messenger y su IGSID en Instagram son identificadores distintos. No los mezcles en tu base de datos sin una etiqueta de tipo.
  • Almacénalo como string, no como entero. Los IGSIDs son cadenas numéricas que pueden superar el Number.MAX_SAFE_INTEGER de JavaScript. Guárdalos siempre como VARCHAR/TEXT, nunca como INT o BIGINT. Convertirlos a número en JavaScript pierde precisión en los últimos dígitos.
  • Aparece en: entry[0].messaging[0].sender.id dentro del payload sin procesar del webhook — la misma ubicación que los PSIDs de Messenger.
Crea tu App de Facebook y conecta Instagram
  1. Ve a developers.facebook.com → My Apps → Create App → elige el tipo "Business"
  2. Añade el producto Instagram a tu app desde el menú Products
  3. En Instagram → Settings, añade tu Instagram Business Account
  4. Genera un Page Access Token: Graph API Explorer → selecciona tu App → selecciona tu Página de Facebook → Generate Token → concede instagram_manage_messages + pages_messaging + pages_read_engagement
  5. Copia tu Instagram Business Account ID (el ID numérico, no tu username) — encuéntralo en el Graph API Explorer consultando GET /me?fields=id,instagram_business_account
  6. Copia tu App Secret desde Settings → Basic
Shell — project setup
mkdir instagram-dm-bot && cd instagram-dm-bot npm init -y npm install express dotenv cat > .env << EOF IG_PAGE_TOKEN=your_page_access_token_here IG_VERIFY_TOKEN=your_custom_verify_secret IG_APP_SECRET=your_app_secret IG_BUSINESS_ID=your_instagram_business_account_id PORT=3000 EOF # Start ngrok for local webhook testing ngrok http 3000
Endpoint de verificación del webhook

El challenge de verificación es idéntico al de Facebook Messenger — Instagram usa el mismo patrón hub.challenge:

Node.js + Express
index.js
require('dotenv').config(); const express = require('express'); const crypto = require('crypto'); const app = express(); // MUST use express.raw() for HMAC verification on webhook route app.use('/webhook', express.raw({ type: 'application/json' })); app.use(express.json()); // GET /webhook — Instagram verification challenge (same as Messenger) app.get('/webhook', (req, res) => { const mode = req.query['hub.mode']; const token = req.query['hub.verify_token']; const challenge = req.query['hub.challenge']; if (mode === 'subscribe' && token === process.env.IG_VERIFY_TOKEN) { console.log('✓ Instagram webhook verified'); return res.status(200).send(challenge); } res.sendStatus(403); }); app.listen(process.env.PORT || 3000);
Python (Flask)
app.py
import os, hmac, hashlib, json from flask import Flask, request, jsonify app = Flask(__name__) @app.route("/webhook", methods=["GET"]) def verify_webhook(): mode = request.args.get("hub.mode") token = request.args.get("hub.verify_token") challenge = request.args.get("hub.challenge") if mode == "subscribe" and token == os.environ["IG_VERIFY_TOKEN"]: return challenge, 200 return "Forbidden", 403

Después de ejecutar tu servidor, registra el webhook en el Facebook Developer Dashboard: App → Instagram → Webhooks → Add Callback URL. Introduce tu URL de ngrok + /webhook y tu verify token. Suscríbete al campo messages — esta es la suscripción clave para los DMs de Instagram.

Verificación de firma HMAC-SHA256

Instagram usa la misma cabecera X-Hub-Signature-256 y el mismo patrón HMAC que Facebook Messenger. El mismo middleware de verificación funciona para ambos:

Node.js — HMAC middleware (same as Messenger)
verifySignature.js
const crypto = require('crypto'); function verifyInstagramSignature(req, res, next) { const signature = req.headers['x-hub-signature-256']; if (!signature) return res.sendStatus(401); const hash = crypto .createHmac('sha256', process.env.IG_APP_SECRET) .update(req.body) .digest('hex'); const expected = Buffer.from(signature.split('=')[1], 'hex'); const computed = Buffer.from(hash, 'hex'); if (expected.length !== computed.length || !crypto.timingSafeEqual(expected, computed)) { return res.sendStatus(401); } req.body = JSON.parse(req.body.toString('utf8')); next(); } module.exports = { verifyInstagramSignature };
Handler POST completo del webhook
Node.js — full Instagram webhook POST handler
webhook.js
const { verifyInstagramSignature } = require('./verifySignature'); app.post('/webhook', verifyInstagramSignature, async (req, res) => { res.sendStatus(200); // acknowledge immediately const body = req.body; // Instagram DMs arrive with object: "instagram" // (contrast: Messenger uses object: "page") if (body.object !== 'instagram') return; for (const entry of body.entry) { const igBusinessId = entry.id; // your Instagram Business Account ID for (const event of (entry.messaging || [])) { const igsid = event.sender.id; // user's IGSID — store as string if (event.message) { const { text, attachments, mid, reply_to } = event.message; if (reply_to?.story) { // User replied to your story await handleStoryReply(igsid, reply_to.story, text); } else if (attachments) { // Image, video, audio, sticker, or share for (const att of attachments) { await handleAttachment(igsid, att); } } else if (text) { // Standard text DM await handleTextDM(igsid, text, mid); } } else if (event.reaction) { // User reacted to one of your messages const { reaction, action, mid } = event.reaction; await handleReaction(igsid, action, reaction, mid); // action: 'react' | 'unreact' } else if (event.read) { // User read your messages await handleRead(igsid, event.read.mid); } else if (event.referral) { // User arrived via story mention or ad CTA await handleReferral(igsid, event.referral); } } } });
Python (Flask)
app.py
@app.route("/webhook", methods=["POST"]) def receive_webhook(): # Verify HMAC signature sig = request.headers.get("X-Hub-Signature-256", "") expected = hmac.new( os.environ["IG_APP_SECRET"].encode(), request.data, hashlib.sha256 ).hexdigest() if not hmac.compare_digest(sig, f"sha256={expected}"): return "Forbidden", 401 body = request.get_json() if body.get("object") != "instagram": return "OK", 200 for entry in body.get("entry", []): for event in entry.get("messaging", []): igsid = event["sender"]["id"] # IGSID — store as string msg = event.get("message") react = event.get("reaction") if msg: reply_to = msg.get("reply_to", {}) if reply_to.get("story"): handle_story_reply(igsid, reply_to["story"], msg.get("text")) elif msg.get("text"): handle_text_dm(igsid, msg["text"]) elif msg.get("attachments"): handle_attachment(igsid, msg["attachments"]) elif react: handle_reaction(igsid, react["action"], react.get("reaction")) return "OK", 200

Todos los esquemas de eventos de DMs de Instagram

DM de texto
messages
event.message.text
Mensaje de texto estándar de un usuario. El tipo de evento más común. Contiene el cuerpo del texto y un message ID (mid) que puedes usar para acuses de lectura y reacciones.
Imagen / Vídeo / Audio
attachments
event.message.attachments
Multimedia enviado en un DM. Cada attachment tiene un type (image, video, audio, file) y una payload.url para descargarlo. Las URLs son temporales — descárgalas de inmediato.
Respuesta a Story
reply_to.story
event.message.reply_to.story
El usuario respondió a una de tus Stories de Instagram. Contiene el ID de la story y la URL del CDN del medio. También incluye el texto de respuesta del usuario en event.message.text.
Sticker
attachments
event.message.attachments[0].type === 'story_mention'
El usuario envió un sticker o una reacción de corazón/like (como sticker). El tipo de attachment es sticker. El sticker_id identifica el sticker específico usado.
Reacción con emoji
reaction
event.reaction.action
El usuario reaccionó (o quitó la reacción) a uno de tus mensajes. action es "react" o "unreact". reaction es el carácter emoji. mid es el ID del mensaje al que reaccionaron.
Mención en Story
referral
event.referral.source === 'STORY_MENTION'
El usuario mencionó tu cuenta en su Story y luego te envió un DM. Llega como un evento referral con source: "STORY_MENTION". La URL de la story del usuario está en event.referral.story.url.

El JSON exacto para los tres tipos de evento más comunes:

Raw webhook payloads — all key event types
// ── Text DM ───────────────────────────────────────────────────────────── { "object": "instagram", // CRITICAL: "instagram" not "page" like Messenger "entry": [{ "id": "987654321098765", // your Instagram Business Account ID "messaging": [{ "sender": { "id": "12345678901234" }, // user's IGSID — store as string "recipient": { "id": "987654321098765" }, // your IG Business Account ID "timestamp": 1747231892, "message": { "mid": "aWdtc2c...", "text": "Hey, do you ship internationally?" } }] }] } // ── Story Reply ───────────────────────────────────────────────────────── { "message": { "mid": "aWdtc2c...", "text": "Wow, this looks amazing!", // the user's reply text "reply_to": { "story": { "id": "17893310459840806", // story ID they replied to "url": "https://lookaside.fbsbx.com/..." // story media URL (CDN) } } } } // ── Emoji Reaction ────────────────────────────────────────────────────── { "reaction": { "action": "react", // 'react' | 'unreact' "reaction": "❤️", // the emoji character "mid": "aWdtc2c..." // which of your messages they reacted to } }

Menciones en stories: cuando los usuarios destacan tu cuenta

Cuando un usuario menciona tu Instagram Business Account en su Story (etiquetándote), Instagram dispara un evento referral hacia tu webhook. Es una señal de alto valor — el usuario está respaldando tu marca ante sus seguidores y a menudo espera que reacciones (enviarle un DM, repostear su story, etc.).

Story mention event schema
{ "sender": { "id": "USER_IGSID" }, "recipient": { "id": "YOUR_IG_BUSINESS_ID" }, "timestamp": 1747231892, "referral": { // present for story mentions "ref": "STORY_MENTION", // your tracking string (if set) "source": "STORY_MENTION", "type": "OPEN_THREAD", "story": { "id": "17893310459840806", // story ID from the user's account "url": "https://lookaside...", // story media URL (CDN, may expire) "mention": { "page_id": "YOUR_IG_BUSINESS_ID" // confirms it's your account mentioned } } }, "message": { // often empty for pure story mentions "mid": "aWdtc2c..." } } // Subscribe to messaging_referrals webhook field to receive story mentions // WITHOUT this subscription, story mentions never arrive at your webhook

Enviar respuestas con la Instagram Send API

La Instagram Send API usa la misma URL base que Messenger pero con un endpoint distinto — tu Instagram Business Account ID en lugar de /me:

Node.js — Instagram Send API
sendDM.js
const GRAPH = 'https://graph.facebook.com/v21.0'; const IG_BIZ_ID = process.env.IG_BUSINESS_ID; // numeric IG Business Account ID const TOKEN = process.env.IG_PAGE_TOKEN; async function sendInstagramDM(igsid, messageText) { // NOTE: endpoint uses IG_BUSINESS_ID, NOT /me (contrast: Messenger uses /me) const res = await fetch( `${GRAPH}/${IG_BIZ_ID}/messages?access_token=${TOKEN}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ recipient: { id: igsid }, // user's IGSID message: { text: messageText }, }), } ); if (!res.ok) { const err = await res.json(); throw new Error(`Instagram DM send failed: ${err.error?.message}`); } return await res.json(); // { recipient_id: igsid, message_id: "..." } } // Usage await sendInstagramDM('12345678901234', 'Thanks for reaching out! 🙏');
Python — Instagram Send API
send_dm.py
import os, requests GRAPH = "https://graph.facebook.com/v21.0" IG_BIZ_ID = os.environ["IG_BUSINESS_ID"] # numeric IG Business Account ID TOKEN = os.environ["IG_PAGE_TOKEN"] def send_instagram_dm(igsid: str, text: str) -> dict: # NOTE: endpoint uses IG_BIZ_ID not /me res = requests.post( f"{GRAPH}/{IG_BIZ_ID}/messages", params={ "access_token": TOKEN }, json={ "recipient": { "id": igsid }, "message": { "text": text }, } ) res.raise_for_status() return res.json()

SocialHook: DMs de Instagram pre-parseados en formato normalizado

Cuando conectas tu cuenta de Instagram a SocialHook, todo el pipeline de entrada — verificación HMAC, parseo de object: "instagram", extracción del IGSID, detección del tipo de evento — se gestiona antes de que el evento llegue a tu servidor. Recibes:

FAQ

Preguntas frecuentes

¿Qué permisos necesito para la Instagram Messaging API?
Tres obligatorios: instagram_manage_messages (recibir/enviar DMs), pages_messaging (suscribirse a webhooks a través de la Página vinculada) y pages_read_engagement (leer información de la cuenta). Durante el desarrollo, estos funcionan para las cuentas añadidas como test users en la configuración de tu App. Para producción (DMs de clientes reales), debes someter los tres permisos a Meta App Review.
¿Qué es un IGSID y en qué se diferencia de un PSID de Facebook?
Un IGSID (Instagram-Scoped ID) es el identificador único de un usuario de Instagram en el contexto de tu Instagram Business Account específica — análogo al PSID en Messenger. Un PSID identifica a un usuario en una Página de Facebook; un IGSID identifica al mismo usuario en tu cuenta de Instagram. Son identificadores diferentes aunque tu cuenta de Instagram y tu Página de Facebook estén vinculadas. Almacena siempre los IGSIDs como strings (VARCHAR) — pueden superar el Number.MAX_SAFE_INTEGER de JavaScript.
¿En qué se diferencia el endpoint de la Instagram Send API del de Facebook Messenger?
Messenger: POST /me/messages (donde "me" se resuelve como tu Página). Instagram: POST /{IG_BUSINESS_ID}/messages (donde IG_BUSINESS_ID es el ID numérico de tu Instagram Business Account, no tu username). Ambos usan la misma URL base y el mismo Page Access Token. La estructura del cuerpo del mensaje es idéntica — recipient.id recibe el IGSID, message.text contiene tu respuesta.
¿Cómo recibo menciones en stories en mi webhook de Instagram?
Debes suscribirte al campo de webhook messaging_referrals además de messages. Cuando un usuario menciona tu cuenta en su Story, Instagram dispara un evento referral con source: "STORY_MENTION" y una URL de la story en el payload. El evento te permite responder al usuario por DM (dentro de la ventana de 24 horas) para agradecerle, pedir permiso de reposteo o ofrecer un descuento.
¿Puedo recibir DMs de Instagram de cualquier usuario o solo de mis seguidores?
Puedes recibir DMs de cualquier usuario de Instagram que pueda enviar mensajes a tu cuenta — no solo de seguidores. Por defecto, los DMs de no seguidores van a una carpeta de "Solicitudes de mensajes" y no disparan webhooks hasta que se acepta la solicitud. En tu Configuración de Instagram → Privacidad → Mensajes, ajusta "Otros usuarios en Instagram" a "No requerir aprobación" para que los DMs fluyan inmediatamente a tu webhook. Las cuentas de empresa que habilitan la API de Solicitudes de Mensajes también pueden gestionar los eventos de solicitudes de forma programática.
¿En qué se diferencia el tipo de objeto del webhook de Instagram respecto al de Facebook Messenger?
Los webhooks de Instagram llegan con "object": "instagram" en el sobre del payload. Los webhooks de Messenger llegan con "object": "page". Este es el primer campo que comprobar en tu handler — si gestionas ambos canales, ramifica según este campo. La estructura anidada del payload (entry[0].messaging[0].sender.id) es la misma para ambos, pero el tipo de identificador de usuario difiere: IGSID en Instagram, PSID en Messenger.
Función
Integración de DMs de Instagram
Eventos de DMs de Instagram pre-parseados entregados a tu webhook. IGSID extraído, respuestas a stories marcadas. $50/mes plano.
Tutorial
Construye un chatbot para Messenger
Aplican los mismos patrones de webhook — verificación HMAC, enrutamiento de eventos, Send API. Añade Instagram junto a Messenger.
Tutorial
Recibe mensajes de WhatsApp
El tercer canal del pipeline normalizado de SocialHook — mismo handler, distinto campo platform.
Instagram DMs

DMs pre-parseados entregados
a tu handler.

Conecta tu Instagram Business Account a SocialHook. Cada DM, respuesta a story y mención en story llega como JSON normalizado — IGSID extraído, tipo de evento etiquetado, HMAC ya verificado. Mismo formato que tus eventos de Messenger y WhatsApp.

Conecta Instagram gratis → Lee la documentación
Sin tarjeta de crédito · $50/mes tras la prueba · Instagram + Messenger + WhatsApp