Facebook Messenger API : Créez des expériences conversationnelles

La Facebook Messenger API permet aux développeurs de créer des expériences conversationnelles qui atteignent plus de 1,3 milliard d'utilisateurs actifs mensuels. Que vous créiez un bot de support client, un assistant e-commerce ou une campagne marketing interactive, la messenger platform api fournit les outils nécessaires pour engager les utilisateurs dans des conversations significatives.

Ce guide vous accompagne à travers tout le processus, de la configuration initiale aux fonctionnalités avancées comme les templates de messages, les réponses rapides et le protocole de transfert humain. Vous trouverez des exemples TypeScript fonctionnels tout au long du guide, prêts à être adaptés pour vos propres projets.

Introduction à la Messenger Platform

La Messenger Platform est le framework de Meta pour créer des bots et des intégrations qui communiquent avec les utilisateurs via Facebook Messenger. Contrairement aux interfaces web traditionnelles, la facebook chat api crée une expérience conversationnelle où les utilisateurs interagissent via des messages, des boutons et des médias enrichis.

Les principales fonctionnalités de la messenger bot api incluent :

La plateforme fonctionne sur une architecture basée sur les webhooks. Votre serveur reçoit les messages entrants via des webhooks, les traite et répond en utilisant la Send API. Ce modèle asynchrone vous permet de créer des expériences réactives sans maintenir de connexions ouvertes.

Configuration de votre application Meta

Avant de pouvoir utiliser la facebook messenger api, vous devez créer et configurer une application Meta. Ce processus établit l'identité de votre application et accorde l'accès à la Messenger Platform.

Étape 1 : Créer une application Meta

Accédez au portail Meta for Developers et créez une nouvelle application. Sélectionnez "Business" comme type d'application, ce qui donne accès aux fonctionnalités Messenger.

// Environment variables you'll need after setup
interface MessengerConfig {
  FACEBOOK_APP_ID: string;
  FACEBOOK_APP_SECRET: string;
  FACEBOOK_PAGE_ID: string;
  FACEBOOK_PAGE_ACCESS_TOKEN: string;
  MESSENGER_VERIFY_TOKEN: string;
}

// Validate your configuration at startup
function validateConfig(): MessengerConfig {
  const required = [
    'FACEBOOK_APP_ID',
    'FACEBOOK_APP_SECRET', 
    'FACEBOOK_PAGE_ID',
    'FACEBOOK_PAGE_ACCESS_TOKEN',
    'MESSENGER_VERIFY_TOKEN'
  ];
  
  const missing = required.filter(key => !process.env[key]);
  
  if (missing.length > 0) {
    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
  }
  
  return {
    FACEBOOK_APP_ID: process.env.FACEBOOK_APP_ID!,
    FACEBOOK_APP_SECRET: process.env.FACEBOOK_APP_SECRET!,
    FACEBOOK_PAGE_ID: process.env.FACEBOOK_PAGE_ID!,
    FACEBOOK_PAGE_ACCESS_TOKEN: process.env.FACEBOOK_PAGE_ACCESS_TOKEN!,
    MESSENGER_VERIFY_TOKEN: process.env.MESSENGER_VERIFY_TOKEN!
  };
}

Étape 2 : Ajouter le produit Messenger

Dans le tableau de bord de votre application, cliquez sur "Ajouter un produit" et sélectionnez Messenger. Cela active les fonctionnalités de la Messenger Platform pour votre application.

Étape 3 : Connecter une page Facebook

Votre bot a besoin d'une page Facebook pour envoyer et recevoir des messages. Dans les paramètres Messenger, cliquez sur "Ajouter ou supprimer des pages" et sélectionnez la page que vous souhaitez connecter. Générez un token d'accès de page, que vous utiliserez pour authentifier les requêtes API.

Note : Les tokens d'accès de page peuvent être de courte ou longue durée. Pour les applications en production, échangez votre token contre une version longue durée qui dure environ 60 jours.

interface TokenExchangeResponse {
  access_token: string;
  token_type: string;
  expires_in?: number;
}

async function exchangeForLongLivedToken(
  shortLivedToken: string,
  appId: string,
  appSecret: string
): Promise {
  const baseUrl = 'https://graph.facebook.com/v18.0';
  
  const params = new URLSearchParams({
    grant_type: 'fb_exchange_token',
    client_id: appId,
    client_secret: appSecret,
    fb_exchange_token: shortLivedToken,
  });

  const response = await fetch(`${baseUrl}/oauth/access_token?${params.toString()}`);
  
  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Token exchange failed: ${error}`);
  }

  const data = await response.json();
  
  if (!data.access_token) {
    throw new Error('No access token returned from token exchange');
  }

  const expiresInDays = data.expires_in 
    ? Math.floor(data.expires_in / 86400) 
    : 'unknown';
    
  console.log(`Token exchanged successfully (expires in ${expiresInDays} days)`);

  return {
    access_token: data.access_token,
    token_type: data.token_type || 'bearer',
    expires_in: data.expires_in,
  };
}

Étape 4 : Configurer les permissions de l'application

Demandez les permissions nécessaires pour votre bot. Au minimum, vous aurez besoin de :

• pages_messaging : Envoyer et recevoir des messages
• pages_manage_metadata : S'abonner aux webhooks
• pages_read_engagement : Accéder aux données de conversation

Configuration et vérification des webhooks

Les webhooks sont la colonne vertébrale de la messenger platform api. Ils permettent à Facebook de notifier votre serveur lorsque des événements se produisent, comme des messages entrants ou des confirmations de livraison.

Configuration de votre endpoint webhook

Créez un endpoint qui gère à la fois les requêtes GET (pour la vérification) et les requêtes POST (pour recevoir les événements).

import express, { Request, Response } from 'express';
import crypto from 'crypto';

const app = express();

// Parse raw body for signature verification
app.use(express.json({
  verify: (req: any, res, buf) => {
    req.rawBody = buf;
  }
}));

// Webhook verification endpoint
app.get('/webhook', (req: Request, res: Response) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];
  
  const verifyToken = process.env.MESSENGER_VERIFY_TOKEN;
  
  if (mode === 'subscribe' && token === verifyToken) {
    console.log('Webhook verified successfully');
    res.status(200).send(challenge);
  } else {
    console.error('Webhook verification failed');
    res.sendStatus(403);
  }
});

// Webhook event receiver
app.post('/webhook', (req: Request, res: Response) => {
  // Verify request signature
  const signature = req.headers['x-hub-signature-256'] as string;
  
  if (!verifySignature(req, signature)) {
    console.error('Invalid signature');
    return res.sendStatus(401);
  }
  
  const body = req.body;
  
  if (body.object !== 'page') {
    return res.sendStatus(404);
  }
  
  // Process each entry
  body.entry?.forEach((entry: any) => {
    entry.messaging?.forEach((event: any) => {
      handleMessagingEvent(event);
    });
  });
  
  // Always respond with 200 OK quickly
  res.sendStatus(200);
});

function verifySignature(req: any, signature: string): boolean {
  if (!signature) return false;
  
  const appSecret = process.env.FACEBOOK_APP_SECRET!;
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', appSecret)
    .update(req.rawBody)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

async function handleMessagingEvent(event: any): Promise {
  const senderId = event.sender.id;
  
  if (event.message) {
    await handleMessage(senderId, event.message);
  } else if (event.postback) {
    await handlePostback(senderId, event.postback);
  } else if (event.read) {
    console.log(`Message read by ${senderId}`);
  } else if (event.delivery) {
    console.log(`Message delivered to ${senderId}`);
  }
}

S'abonner aux événements webhook

Après avoir configuré votre endpoint, abonnez-vous aux événements que vous souhaitez recevoir. Dans le tableau de bord de l'application Meta, configurez votre URL webhook et sélectionnez les champs d'abonnement pertinents :

• messages : Messages entrants
• messaging_postbacks : Clics sur les boutons et sélections de menu
• messaging_optins : Opt-ins des utilisateurs
• message_deliveries : Confirmations de livraison
• message_reads : Accusés de lecture

Réception des messages

Lorsque les utilisateurs envoient des messages à votre bot, la facebook chat api les livre à votre webhook. Les messages peuvent contenir du texte, des pièces jointes, ou les deux.

interface MessengerMessage {
  mid: string;
  text?: string;
  attachments?: Array<{
    type: 'image' | 'video' | 'audio' | 'file' | 'location' | 'fallback';
    payload: {
      url?: string;
      coordinates?: {
        lat: number;
        long: number;
      };
    };
  }>;
  quick_reply?: {
    payload: string;
  };
  reply_to?: {
    mid: string;
  };
}

async function handleMessage(
  senderId: string, 
  message: MessengerMessage
): Promise {
  console.log(`Received message from ${senderId}:`, message);
  
  // Handle quick reply responses
  if (message.quick_reply) {
    await handleQuickReply(senderId, message.quick_reply.payload);
    return;
  }
  
  // Handle attachments
  if (message.attachments && message.attachments.length > 0) {
    for (const attachment of message.attachments) {
      await handleAttachment(senderId, attachment);
    }
    return;
  }
  
  // Handle text messages
  if (message.text) {
    await processTextMessage(senderId, message.text);
  }
}

async function handleAttachment(
  senderId: string, 
  attachment: MessengerMessage['attachments'][0]
): Promise {
  switch (attachment.type) {
    case 'image':
      await sendTextMessage(senderId, `Thanks for the image! I received: ${attachment.payload.url}`);
      break;
    case 'location':
      const { lat, long } = attachment.payload.coordinates!;
      await sendTextMessage(senderId, `Got your location: ${lat}, ${long}`);
      break;
    default:
      await sendTextMessage(senderId, `Received your ${attachment.type}`);
  }
}

async function processTextMessage(
  senderId: string, 
  text: string
): Promise {
  const lowerText = text.toLowerCase();
  
  if (lowerText.includes('help')) {
    await sendHelpMessage(senderId);
  } else if (lowerText.includes('products')) {
    await sendProductCatalog(senderId);
  } else {
    await sendTextMessage(senderId, `You said: "${text}". How can I help you today?`);
  }
}

Envoi de messages texte

La Send API est votre outil principal pour répondre aux utilisateurs via la messenger bot api. Les messages texte sont la forme de réponse la plus simple.

const GRAPH_API_URL = 'https://graph.facebook.com/v18.0';

interface SendMessageResponse {
  recipient_id: string;
  message_id: string;
}

interface SendMessageError {
  message: string;
  type: string;
  code: number;
  error_subcode?: number;
  fbtrace_id: string;
}

async function sendTextMessage(
  recipientId: string, 
  text: string
): Promise {
  const pageAccessToken = process.env.FACEBOOK_PAGE_ACCESS_TOKEN!;
  
  const response = await fetch(
    `${GRAPH_API_URL}/me/messages?access_token=${pageAccessToken}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        recipient: { id: recipientId },
        message: { text },
        messaging_type: 'RESPONSE'
      }),
    }
  );
  
  const data = await response.json();
  
  if (!response.ok) {
    const error = data.error as SendMessageError;
    throw new Error(`Send failed: ${error.message} (code: ${error.code})`);
  }
  
  return data as SendMessageResponse;
}

// Send typing indicator for better UX
async function sendTypingIndicator(
  recipientId: string, 
  isTyping: boolean
): Promise {
  const pageAccessToken = process.env.FACEBOOK_PAGE_ACCESS_TOKEN!;
  
  await fetch(
    `${GRAPH_API_URL}/me/messages?access_token=${pageAccessToken}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        recipient: { id: recipientId },
        sender_action: isTyping ? 'typing_on' : 'typing_off'
      }),
    }
  );
}

// Helper function to send messages with typing indicator
async function sendMessageWithTyping(
  recipientId: string,
  text: string,
  typingDuration: number = 1000
): Promise {
  await sendTypingIndicator(recipientId, true);
  await new Promise(resolve => setTimeout(resolve, typingDuration));
  return sendTextMessage(recipientId, text);
}

Templates de messages (Generic, Button, Receipt)

Les templates de messages créent des expériences riches et interactives qui vont au-delà du texte simple. La facebook messenger api prend en charge plusieurs types de templates, chacun conçu pour des cas d'utilisation spécifiques.

Template Generic

Le template Generic affiche un carrousel d'éléments, parfait pour les listes de produits ou les flux de contenu.

interface GenericTemplateElement {
  title: string;
  subtitle?: string;
  image_url?: string;
  default_action?: {
    type: 'web_url';
    url: string;
    webview_height_ratio?: 'compact' | 'tall' | 'full';
  };
  buttons?: Array;
}

type TemplateButton = 
  | { type: 'web_url'; url: string; title: string }
  | { type: 'postback'; title: string; payload: string }
  | { type: 'phone_number'; title: string; payload: string }
  | { type: 'account_link'; url: string }
  | { type: 'ac