API de Messagerie Instagram : Guide Complet pour Développeurs

The API de messagerie Instagram permet aux entreprises d'envoyer et de recevoir des messages directs de manière programmatique via l'API Graph officielle d'Instagram. Que vous développiez des systèmes d'automatisation du support client, des systèmes de notification ou des flux de commerce conversationnel, ce guide couvre tout ce dont vous avez besoin pour intégrer le API de DM Instagram dans votre application.

Les fonctionnalités de messagerie d'Instagram font partie de l'écosystème plus large de l'API Meta Graph. Contrairement aux méthodes non officielles qui risquent de suspendre votre compte, l'officiel API de message direct Instagram offre une messagerie fiable et évolutive pour les comptes professionnels avec une authentification appropriée et une gestion des limites de taux.

Conditions préalables et exigences

Avant de pouvoir envoyer des messages directs sur Instagram de manière programmatique, vous devez configurer plusieurs composants. L'API de messagerie Instagram a des exigences spécifiques qui diffèrent de celles des autres plateformes sociales.

Exigences pour un compte professionnel

L'API de messagerie Instagram ne fonctionne qu'avec des comptes Instagram Professionnels ou Créateurs connectés à une Page Facebook. Les comptes personnels ne peuvent pas accéder aux points de terminaison de messagerie.

Créer une application pour développeurs Meta

1. Naviguer vers developers.facebook.com et créez une nouvelle application
2. Sélectionnez "Entreprise" comme type d'application.
3. Ajoutez le produit "Instagram Graph API" à votre application.
4. Configurez vos URI de redirection OAuth.
5. Notez votre ID d'application et votre Secret d'application.

```
// Variables d'environnement nécessaires pour l'intégration de l'API Instagram
interface InstagramConfig {
  clientId: string;      // ID de l'application Meta
  clientSecret: string;  // Secret de l'application Meta
  redirectUri: string;   // Votre URL de rappel OAuth
  webhookVerifyToken: string; // Pour la vérification du 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 || '',
};
```

Remarque : Stockez toutes les informations d'identification dans des variables d'environnement. Ne jamais enregistrer les secrets API dans le contrôle de version.

Flux d'authentification OAuth 2.0

L'API de messagerie Instagram utilise OAuth 2.0 pour l'authentification. Vous devrez mettre en place un processus d'échange de jetons en deux étapes pour obtenir des jetons d'accès à long terme.

Étape 1 : Générer l'URL d'autorisation

Dirigez les utilisateurs vers la page d'autorisation d'Instagram avec les autorisations requises :

function getInstagramAuthUrl(state: string): string {
  const scopes = [
    'instagram_business_basic',
    'instagram_business_content_publish',
    'instagram_business_manage_messages', // Nécessaire pour les messages directs
  ];

  const params = new URLSearchParams({
    client_id: config.clientId,
    redirect_uri: config.redirectUri,
    scope: scopes.join(','),
    response_type: 'code',
    auth_type: 'rerequest', // Forcer la demande de ré-autorisation
    state: state, // Protection CSRF
  });

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

Étape 2 : Échangez le code contre des jetons

Après que l'utilisateur ait autorisé votre application, Instagram redirige vers votre URL de rappel avec un code d'autorisation. Échangez ce code contre des jetons d'accès :

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

async function exchangeCodeForToken(
  code: string
): Promise {
  // Étape 1 : Échanger le code contre un jeton à courte durée de vie
  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(`Échec de l'échange de jeton : ${error}`);
  }

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

  // Étape 2 : Échanger contre un jeton à longue durée de vie (60 jours)
  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(`Échec de l'échange du jeton à longue durée de vie : ${error}`);
  }

  const longLivedData = await longLivedResponse.json();

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

Rafraîchissement des jetons d'accès

Les jetons à long terme expirent après 60 jours. Mettez en œuvre le rafraîchissement des jetons pour maintenir l'accès :

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

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`Échec du rafraîchissement du token : ${response.status} ${errorText}`);
  }

  const data = await response.json();

  if (data.error) {
    throw new Error(`Erreur de rafraîchissement du token : ${data.error.message}`);
  }

  if (!data.access_token) {
    throw new Error('Le rafraîchissement du token n\'a pas renvoyé d\'access_token');
  }

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

Remarque : Programmez des tâches de rafraîchissement de jetons pour qu'elles s'exécutent avant leur expiration. Une bonne pratique consiste à rafraîchir les jetons lorsqu'il leur reste moins de 7 jours.

Configuration des Webhooks pour des Messages en Temps Réel

Pour recevoir des messages entrants en temps réel, vous devez configurer des webhooks. Instagram envoie des requêtes POST à votre point de terminaison chaque fois qu'un utilisateur envoie un message à votre compte professionnel.

Point de vérification du Webhook

Instagram vérifie votre URL de webhook avec une requête GET avant de l'activer :

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 vérifié avec succès');
    res.status(200).send(challenge);
    return;
  }

  console.error('Échec de la vérification du webhook');
  res.status(403).send('Échec de la vérification');
}

Envoi de messages via l'API DM d'Instagram

La fonctionnalité principale de la API de message direct Instagram envoyer des messages aux utilisateurs qui ont engagé une conversation avec votre entreprise.

Envoi de messages texte

To envoyer des DMs Instagram par programme, utilisez le point de terminaison messages :

interface SendMessageOptions {
  accessToken: string;
  igUserId: string;      // Votre identifiant de compte professionnel Instagram
  recipientId: string;   // L'identifiant de l'utilisateur sur 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(`Échec de l'envoi du message : ${error}`);
  }

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

Limites de taux et meilleures pratiques

Comprendre les limites de taux est essentiel pour créer des intégrations de messagerie Instagram fiables.

Aperçu des limites de taux

Meilleures Pratiques

1. Implémentez un mécanisme de retour exponentiel. pour les erreurs de limite de taux
2. Mettre en cache les jetons d'utilisateur pour éviter les appels d'authentification répétés
3. Utilisez la reconnaissance de webhook immédiatement, traiter de manière asynchrone
4. Surveillez l'expiration des jetons et actualisez de manière proactive
5. Enregistrez toutes les interactions API. pour le débogage

Utiliser Late pour l'intégration de la messagerie Instagram

La création et la maintenance des intégrations de l'API de messagerie Instagram nécessitent un effort de développement considérable. Vous devez gérer les flux OAuth, le rafraîchissement des jetons, la gestion des webhooks, la limitation de débit et la gestion des erreurs sur plusieurs plateformes sociales potentiellement.

Late propose une API unifiée qui simplifie l'intégration de la messagerie Instagram ainsi que d'autres plateformes sociales. Au lieu de créer des intégrations séparées pour chaque plateforme, Late offre :

• Authentification unifiéeFlux OAuth unique pour Instagram, Facebook, Twitter, LinkedIn, et bien d'autres.
• Gestion automatique des jetonsLate gère automatiquement le rafraîchissement et l'expiration des tokens.
• Abstraction des WebhooksRecevez des événements webhook normalisés sur toutes les plateformes.
• Limitation de taux intégréeGestion intelligente des files d'attente de requêtes et logique de réessai
• SDK sécurisé par typeSupport complet de TypeScript avec des types exhaustifs

Avec Late, l'intégration de la messagerie Instagram devient simple :

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

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

// Envoyer un message via l'API unifiée de Late
await late.messages.send({
  accountId: 'instagram-account-id',
  recipientId: 'user-id',
  content: {
    text: 'Bonjour de Late !',
  },
});

// Gérer les messages entrants avec des événements normalisés
late.webhooks.on('message.received', (event) => {
  console.log('Plateforme :', event.platform); // 'instagram'
  console.log('Message :', event.content.text);
});

Late gère la complexité de l'API de messagerie Instagram afin que vous puissiez vous concentrer sur le développement des fonctionnalités essentielles de votre application. Découvrez le Documentation de Late pour commencer avec la messagerie Instagram et d'autres intégrations de plateformes sociales.