API de Mensajería de Instagram: Guía Completa para Desarrolladores

The API de Mensajería de Instagram permite a las empresas enviar y recibir mensajes directos de forma programática a través de la API Graph oficial de Instagram. Ya sea que estés desarrollando automatización de atención al cliente, sistemas de notificaciones o flujos de comercio conversacional, esta guía abarca todo lo que necesitas para integrar la API de DM de Instagram en tu aplicación.

Las capacidades de mensajería de Instagram son parte del ecosistema más amplio de la API de Meta Graph. A diferencia de los métodos no oficiales que arriesgan la suspensión de la cuenta, la oficial API de Mensajes Directos de Instagram ofrece mensajería fiable y escalable para cuentas de negocio con la autenticación adecuada y limitación de tasa.

Requisitos y Condiciones Previas

Antes de poder enviar mensajes directos de Instagram de forma programática, necesitas configurar varios componentes. La API de Mensajería de Instagram tiene requisitos específicos que difieren de otras plataformas sociales.

Requisitos de la Cuenta de Empresa

La API de Mensajería de Instagram solo funciona con cuentas de Instagram Business o Creador que estén conectadas a una Página de Facebook. Las cuentas personales no pueden acceder a los puntos finales de mensajería.

Crear una aplicación para desarrolladores de Meta

1. Navegar a developers.facebook.com y crea una nueva aplicación
2. Selecciona "Negocios" como el tipo de aplicación.
3. Añade el producto "Instagram Graph API" a tu aplicación.
4. Configura tus URIs de redirección OAuth.
5. Anota tu ID de aplicación y tu secreto de aplicación.

```typescript
// Variables de entorno necesarias para la integración de la API de Instagram
interface InstagramConfig {
  clientId: string;      // ID de la aplicación de Meta
  clientSecret: string;  // Secreto de la aplicación de Meta
  redirectUri: string;   // Tu URL de callback de OAuth
  webhookVerifyToken: string; // Para la verificación del webhook
}

const config: InstagramConfig = {
  clientId: process.env.INSTAGRAM_CLIENT_ID || '',
  clientSecret: process.env.INSTAGRAM_CLIENT_SECRET || '',
  redirectUri: process.env.INSTAGRAM_REDIRECT_URI || '',
  webhookVerifyToken: process.env.INSTAGRAM_WEBHOOK_VERIFY_TOKEN || '',
};
```

Nota: Almacena todas las credenciales en variables de entorno. Nunca incluyas secretos de API en el control de versiones.

Flujo de Autenticación OAuth 2.0

La API de Mensajería de Instagram utiliza OAuth 2.0 para la autenticación. Necesitarás implementar un proceso de intercambio de tokens en dos pasos para obtener tokens de acceso de larga duración.

Paso 1: Generar URL de Autorización

Dirige a los usuarios a la página de autorización de Instagram con los permisos necesarios:

function getInstagramAuthUrl(state: string): string {
  const scopes = [
    'instagram_business_basic',
    'instagram_business_content_publish',
    'instagram_business_manage_messages', // Requerido para mensajes directos
  ];

  const params = new URLSearchParams({
    client_id: config.clientId,
    redirect_uri: config.redirectUri,
    scope: scopes.join(','),
    response_type: 'code',
    auth_type: 'rerequest', // Forzar el aviso de re-permiso
    state: state, // Protección CSRF
  });

  return `https://www.instagram.com/oauth/authorize?${params.toString()}`;
}

Paso 2: Intercambiar el código por tokens

Después de que el usuario autoriza tu aplicación, Instagram redirige a tu URL de callback con un código de autorización. Intercambia esto por tokens de acceso:

interface TokenResponse {
  accessToken: string;
  refreshToken: string;
  userId: string;
  expiresIn: number;
}

async function exchangeCodeForToken(
  code: string
): Promise {
  // Paso 1: Intercambiar el código por un token de corta duración
  const tokenResponse = await fetch(
    'https://api.instagram.com/oauth/access_token',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        client_id: config.clientId,
        client_secret: config.clientSecret,
        grant_type: 'authorization_code',
        redirect_uri: config.redirectUri,
        code: code,
      }),
    }
  );

  if (!tokenResponse.ok) {
    const error = await tokenResponse.text();
    throw new Error(`Error en el intercambio de tokens: ${error}`);
  }

  const shortLivedData = await tokenResponse.json();
  const shortLivedToken = shortLivedData.access_token;
  const userId = shortLivedData.user_id;

  // Paso 2: Intercambiar por un token de larga duración (60 días)
  const longLivedResponse = await fetch(
    `https://graph.instagram.com/access_token?` +
    `grant_type=ig_exchange_token&` +
    `client_secret=${config.clientSecret}&` +
    `access_token=${shortLivedToken}`,
    { method: 'GET' }
  );

  if (!longLivedResponse.ok) {
    const error = await longLivedResponse.text();
    throw new Error(`Error en el intercambio del token de larga duración: ${error}`);
  }

  const longLivedData = await longLivedResponse.json();

  return {
    accessToken: longLivedData.access_token,
    refreshToken: longLivedData.access_token,
    userId: userId,
    expiresIn: longLivedData.expires_in,
  };
}

Actualización de Tokens de Acceso

Los tokens de larga duración expiran después de 60 días. Implementa la renovación de tokens para mantener el acceso:

async function refreshAccessToken(
  currentToken: string
): Promise<{ accessToken: string; expiresIn: number }> {
  const response = await fetch(
    `https://graph.instagram.com/refresh_access_token?` +
    `grant_type=ig_refresh_token&` +
    `access_token=${currentToken}`,
    { method: 'GET' }
  );

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`Error al actualizar el token: ${response.status} ${errorText}`);
  }

  const data = await response.json();

  if (data.error) {
    throw new Error(`Error al actualizar el token: ${data.error.message}`);
  }

  if (!data.access_token) {
    throw new Error('La actualización del token no devolvió un access_token');
  }

  return {
    accessToken: data.access_token,
    expiresIn: data.expires_in,
  };
}

Nota: Programa trabajos de actualización de tokens para que se ejecuten antes de su expiración. Una buena práctica es actualizar los tokens cuando les queden menos de 7 días.

Configuración de Webhooks para Mensajes en Tiempo Real

Para recibir mensajes entrantes en tiempo real, necesitas configurar webhooks. Instagram envía solicitudes POST a tu endpoint cada vez que un usuario envía un mensaje a tu cuenta de negocio.

Endpoint de Verificación de Webhook

Instagram verifica tu URL de webhook con una solicitud GET antes de activarlo:

import { Request, Response } from 'express';

function handleWebhookVerification(
  req: Request,
  res: Response
): void {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];

  if (mode === 'subscribe' && token === config.webhookVerifyToken) {
    console.log('Webhook verificado con éxito');
    res.status(200).send(challenge);
    return;
  }

  console.error('La verificación del webhook ha fallado');
  res.status(403).send('La verificación ha fallado');
}

Envío de mensajes a través de la API de DM de Instagram

La funcionalidad principal de la API de Mensajes Directos de Instagram es enviar mensajes a los usuarios que han iniciado conversaciones con tu negocio.

Envío de Mensajes de Texto

To envía DMs de Instagram de forma programática, utiliza el endpoint de mensajes:

interface SendMessageOptions {
  accessToken: string;
  igUserId: string;      // Tu ID de cuenta de Instagram Business
  recipientId: string;   // El ID del usuario en Instagram
  text: string;
}

interface SendMessageResponse {
  messageId: string;
}

async function sendTextMessage(
  options: SendMessageOptions
): Promise<SendMessageResponse> {
  const { accessToken, igUserId, recipientId, text } = options;

  const response = await fetch(
    `https://graph.instagram.com/${igUserId}/messages`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${accessToken}`,
      },
      body: JSON.stringify({
        recipient: {
          id: recipientId,
        },
        message: {
          text: text,
        },
      }),
    }
  );

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Error al enviar el mensaje: ${error}`);
  }

  const data = await response.json();
  return { messageId: data.message_id };
}

Límites de tasa y mejores prácticas

Entender los límites de tasa es fundamental para crear integraciones de mensajería en Instagram que sean fiables.

Descripción general de los límites de tasa

Mejores Prácticas

1. Implementa un retroceso exponencial. para errores de límite de tasa
2. Almacenar en caché los tokens de usuario para evitar llamadas de autenticación repetidas
3. Utiliza el reconocimiento de webhook inmediatamente, procesar de forma asíncrona
4. Supervisa la expiración del token y actualizar proactivamente
5. Registra todas las interacciones de la API. para depuración

Uso de Late para la integración de mensajería en Instagram

Construir y mantener integraciones con la API de Mensajería de Instagram requiere un esfuerzo de desarrollo considerable. Debes gestionar flujos de OAuth, la renovación de tokens, la gestión de webhooks, la limitación de tasas y el manejo de errores en múltiples plataformas sociales.

Late ofrece una API unificada que simplifica la integración de mensajería de Instagram junto con otras plataformas sociales. En lugar de crear integraciones separadas para cada plataforma, Late ofrece:

• Autenticación UnificadaFlujo OAuth único para Instagram, Facebook, Twitter, LinkedIn y más.
• Gestión Automática de TokensLate gestiona automáticamente la renovación y expiración de tokens.
• Abstracción de WebhooksRecibe eventos de webhook normalizados en todas las plataformas.
• Limitación de tasa integradaColas de solicitudes inteligentes y lógica de reintento
• SDK Seguro por Tipos: Soporte completo de TypeScript con tipos exhaustivos

Con Late, la implementación de mensajería en Instagram se vuelve sencilla:

import { Late } from '@getlate/sdk';

const late = new Late({ apiKey: process.env.LATE_API_KEY });

// Enviar un mensaje a través de la API unificada de Late
await late.messages.send({
  accountId: 'instagram-account-id',
  recipientId: 'user-id',
  content: {
    text: '¡Hola desde Late!',
  },
});

// Manejar mensajes entrantes con eventos normalizados
late.webhooks.on('message.received', (event) => {
  console.log('Plataforma:', event.platform); // 'instagram'
  console.log('Mensaje:', event.content.text);
});

Late se encarga de la complejidad de la API de Mensajería de Instagram para que tú puedas centrarte en desarrollar la funcionalidad principal de tu aplicación. Echa un vistazo a la Documentación de Late para comenzar con la mensajería de Instagram y otras integraciones de plataformas sociales.