API di Messaggistica di Instagram: Guida Completa per Sviluppatori

The API di Messaggistica di Instagram consente alle aziende di inviare e ricevere messaggi diretti in modo programmato tramite l'API Graph ufficiale di Instagram. Che tu stia sviluppando automazioni per il supporto clienti, sistemi di notifica o flussi di commercio conversazionale, questa guida copre tutto ciò di cui hai bisogno per integrare il API DM di Instagram nella tua applicazione.

Le funzionalità di messaggistica di Instagram fanno parte del più ampio ecosistema del Meta Graph API. A differenza dei metodi non ufficiali che rischiano la sospensione dell'account, l'ufficiale API di Messaggi Diretti di Instagram offre un messaggistica affidabile e scalabile per gli account aziendali con una corretta autenticazione e limitazione della frequenza.

Requisiti e Condizioni Necessarie

Prima di poter inviare messaggi diretti su Instagram in modo programmatico, è necessario configurare diversi componenti. L'API di Messaggistica di Instagram ha requisiti specifici che differiscono da altre piattaforme social.

Requisiti per l'Account Aziendale

L'API di Messaggistica di Instagram funziona solo con account Business o Creator di Instagram collegati a una Pagina Facebook. Gli account personali non possono accedere agli endpoint di messaggistica.

Creare un'app per sviluppatori Meta

1. Naviga a developers.facebook.com e crea una nuova app
2. Seleziona "Business" come tipo di app.
3. Aggiungi il prodotto "Instagram Graph API" alla tua app
4. Configura gli URI di reindirizzamento OAuth
5. Annota il tuo ID App e il tuo Segreto App.

```
// Variabili d'ambiente necessarie per l'integrazione con l'API di Instagram
interface InstagramConfig {
  clientId: string;      // ID App Meta
  clientSecret: string;  // Segreto App Meta
  redirectUri: string;   // Il tuo URL di callback OAuth
  webhookVerifyToken: string; // Per la verifica 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: Memorizza tutte le credenziali nelle variabili d'ambiente. Non commettere mai segreti API nel controllo di versione.

Flusso di autenticazione OAuth 2.0

L'API di Messaggistica di Instagram utilizza OAuth 2.0 per l'autenticazione. Dovrai implementare un processo di scambio di token in due fasi per ottenere token di accesso a lungo termine.

Passo 1: Genera l'URL di autorizzazione

Reindirizza gli utenti alla pagina di autorizzazione di Instagram con gli ambiti richiesti:

function getInstagramAuthUrl(state: string): string {
  const scopes = [
    'instagram_business_basic',
    'instagram_business_content_publish',
    'instagram_business_manage_messages', // Necessario per i DM
  ];

  const params = new URLSearchParams({
    client_id: config.clientId,
    redirect_uri: config.redirectUri,
    scope: scopes.join(','),
    response_type: 'code',
    auth_type: 'rerequest', // Forza la richiesta di ri-autorizzazione
    state: state, // Protezione CSRF
  });

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

Passo 2: Scambia il Codice con i Token

Dopo che l'utente ha autorizzato la tua app, Instagram reindirizza all'URL di callback con un codice di autorizzazione. Scambia questo codice per ottenere i token di accesso:

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

async function exchangeCodeForToken(
  code: string
): Promise {
  // Passo 1: Scambia il codice per un token a breve termine
  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(`Scambio del token fallito: ${error}`);
  }

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

  // Passo 2: Scambia per un token a lungo termine (60 giorni)
  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(`Scambio del token a lungo termine fallito: ${error}`);
  }

  const longLivedData = await longLivedResponse.json();

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

Aggiornamento dei Token di Accesso

I token a lungo termine scadono dopo 60 giorni. Implementa il refresh del token per mantenere l'accesso:

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(`Il rinnovo del token è fallito: ${response.status} ${errorText}`);
  }

  const data = await response.json();

  if (data.error) {
    throw new Error(`Errore nel rinnovo del token: ${data.error.message}`);
  }

  if (!data.access_token) {
    throw new Error('Il rinnovo del token non ha restituito un access_token');
  }

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

Nota: Pianifica i lavori di aggiornamento dei token per eseguirli prima della scadenza. Una buona prassi è quella di aggiornare i token quando mancano meno di 7 giorni alla scadenza.

Impostazione dei Webhook per Messaggi in Tempo Reale

Per ricevere messaggi in tempo reale, è necessario configurare i webhook. Instagram invia richieste POST al tuo endpoint ogni volta che un utente invia un messaggio al tuo profilo aziendale.

Endpoint di Verifica del Webhook

Instagram verifica il tuo URL del webhook con una richiesta GET prima di attivarlo:

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 verificato con successo');
    res.status(200).send(challenge);
    return;
  }

  console.error('Verifica del webhook fallita');
  res.status(403).send('Verifica fallita');
}

Inviare messaggi tramite l'API DM di Instagram

La funzionalità principale di API di Messaggi Diretti di Instagram inviare messaggi agli utenti che hanno avviato conversazioni con la tua azienda.

Invio di Messaggi di Testo

To inviare DM su Instagram in modo programmato, utilizza l'endpoint dei messaggi:

interface SendMessageOptions {
  accessToken: string;
  igUserId: string;      // Il tuo ID dell'account aziendale Instagram
  recipientId: string;   // L'ID dell'utente su 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(`Invio del messaggio non riuscito: ${error}`);
  }

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

Limiti di Richiesta e Migliori Pratiche

Comprendere i limiti di utilizzo è fondamentale per creare integrazioni affidabili per la messaggistica su Instagram.

Panoramica dei Limiti di Richiesta

Migliori Pratiche

1. Implementa il backoff esponenziale per errori di limite di frequenza
2. Memorizza i token degli utenti per evitare chiamate di autenticazione ripetute
3. Utilizza il riconoscimento del webhook immediatamente, elabora in modo asincrono
4. Monitora la scadenza del token e aggiorna in modo proattivo
5. Registra tutte le interazioni API per il debug

Utilizzare Late per l'integrazione dei messaggi su Instagram

Costruire e mantenere integrazioni con l'API di messaggistica di Instagram richiede un notevole impegno di sviluppo. È necessario gestire i flussi OAuth, il rinnovo dei token, la gestione dei webhook, il limite di velocità e la gestione degli errori su più piattaforme social.

Late fornisce un'API unificata che semplifica l'integrazione della messaggistica su Instagram insieme ad altre piattaforme social. Invece di creare integrazioni separate per ogni piattaforma, Late offre:

• Autenticazione UnificataFlusso OAuth unico per Instagram, Facebook, Twitter, LinkedIn e altro ancora
• Gestione Automatica dei TokenLate gestisce automaticamente il rinnovo e la scadenza dei token.
• Astrazione dei WebhookRicevi eventi webhook normalizzati su tutte le piattaforme.
• Limitazione della velocità integrata: Coda intelligente per la gestione delle richieste e logica di ripetizione
• SDK a Tipi SicuriSupporto completo per TypeScript con tipi dettagliati

Con Late, l'implementazione della messaggistica su Instagram diventa semplice:

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

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

// Invia un messaggio tramite l'API unificata di Late
await late.messages.send({
  accountId: 'instagram-account-id',
  recipientId: 'user-id',
  content: {
    text: 'Ciao da Late!',
  },
});

// Gestisci i messaggi in arrivo con eventi normalizzati
late.webhooks.on('message.received', (event) => {
  console.log('Piattaforma:', event.platform); // 'instagram'
  console.log('Messaggio:', event.content.text);
});

Late gestisce la complessità dell'API di Messaggistica di Instagram, così puoi concentrarti sullo sviluppo delle funzionalità principali della tua applicazione. Scopri il Documentazione di Late per iniziare con la messaggistica di Instagram e altre integrazioni con i social media.