Facebook Messenger API: Konversationelle Erlebnisse entwickeln

Die Facebook Messenger API ermöglicht es Entwicklern, konversationelle Erlebnisse zu schaffen, die über 1,3 Milliarden monatlich aktive Nutzer erreichen. Ob Sie einen Kundensupport-Bot, einen E-Commerce-Assistenten oder eine interaktive Marketingkampagne erstellen – die messenger platform api bietet Ihnen die Werkzeuge, die Sie benötigen, um Nutzer in bedeutungsvolle Gespräche einzubinden.

Dieser Leitfaden führt Sie durch alles, von der ersten Einrichtung bis hin zu erweiterten Funktionen wie Nachrichtenvorlagen, Quick Replies und dem Human Handover Protocol. Sie finden durchgehend funktionierende TypeScript-Beispiele, die Sie für Ihre eigenen Projekte anpassen können.

Einführung in die Messenger Platform

Die Messenger Platform ist Metas Framework zum Erstellen von Bots und Integrationen, die über Facebook Messenger mit Nutzern kommunizieren. Im Gegensatz zu traditionellen Web-Oberflächen schafft die facebook chat api ein konversationelles Erlebnis, bei dem Nutzer über Nachrichten, Buttons und Rich Media interagieren.

Wichtige Funktionen der messenger bot api umfassen:

Die Plattform basiert auf einer webhook-basierten Architektur. Ihr Server empfängt eingehende Nachrichten über webhooks, verarbeitet sie und antwortet über die Send API. Dieses asynchrone Modell ermöglicht es Ihnen, reaktionsschnelle Erlebnisse zu schaffen, ohne Verbindungen offen halten zu müssen.

Einrichtung Ihrer Meta App

Bevor Sie die facebook messenger api nutzen können, müssen Sie eine Meta App erstellen und konfigurieren. Dieser Prozess etabliert die Identität Ihrer Anwendung und gewährt Zugriff auf die Messenger Platform.

Schritt 1: Meta App erstellen

Navigieren Sie zum Meta for Developers-Portal und erstellen Sie eine neue App. Wählen Sie "Business" als App-Typ, der Zugriff auf Messenger-Funktionen bietet.

// 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!
  };
}

Schritt 2: Messenger-Produkt hinzufügen

Klicken Sie in Ihrem App-Dashboard auf "Produkt hinzufügen" und wählen Sie Messenger. Dies aktiviert die Messenger Platform-Funktionen für Ihre App.

Schritt 3: Facebook-Seite verbinden

Ihr Bot benötigt eine Facebook-Seite zum Senden und Empfangen von Nachrichten. Klicken Sie in den Messenger-Einstellungen auf "Seiten hinzufügen oder entfernen" und wählen Sie die Seite aus, die Sie verbinden möchten. Generieren Sie ein Page Access Token, das Sie zur Authentifizierung von API-Anfragen verwenden werden.

Hinweis: Page Access Tokens können kurzlebig oder langlebig sein. Für Produktionsanwendungen tauschen Sie Ihr Token gegen eine langlebige Version aus, die etwa 60 Tage gültig ist.

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,
  };
}

Schritt 4: App-Berechtigungen konfigurieren

Fordern Sie die erforderlichen Berechtigungen für Ihren Bot an. Mindestens benötigen Sie:

• pages_messaging: Nachrichten senden und empfangen
• pages_manage_metadata: webhooks abonnieren
• pages_read_engagement: Zugriff auf Konversationsdaten

Webhook-Konfiguration und Verifizierung

Webhooks sind das Rückgrat der messenger platform api. Sie ermöglichen es Facebook, Ihren Server zu benachrichtigen, wenn Ereignisse auftreten, wie eingehende Nachrichten oder Nachrichtenzustellungen.

Einrichtung Ihres Webhook-Endpunkts

Erstellen Sie einen Endpunkt, der sowohl GET-Anfragen (zur Verifizierung) als auch POST-Anfragen (zum Empfangen von Ereignissen) verarbeitet.

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}`);
  }
}

Webhook-Ereignisse abonnieren

Nach der Einrichtung Ihres Endpunkts abonnieren Sie die Ereignisse, die Sie empfangen möchten. Konfigurieren Sie im Meta App Dashboard Ihre webhook-URL und wählen Sie die relevanten Abonnementfelder aus:

• messages: Eingehende Nachrichten
• messaging_postbacks: Button-Klicks und Menüauswahlen
• messaging_optins: Nutzer-Opt-ins
• message_deliveries: Zustellbestätigungen
• message_reads: Lesebestätigungen

Nachrichten empfangen

Wenn Nutzer Nachrichten an Ihren Bot senden, liefert die facebook chat api diese an Ihren webhook. Nachrichten können Text, Anhänge oder beides enthalten.

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?`);
  }
}

Textnachrichten senden

Die Send API ist Ihr primäres Werkzeug, um Nutzern über die messenger bot api zu antworten. Textnachrichten sind die einfachste Form der Antwort.

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);
}

Nachrichtenvorlagen (Generic, Button, Receipt)

Nachrichtenvorlagen schaffen reichhaltige, interaktive Erlebnisse, die über einfachen Text hinausgehen. Die facebook messenger api unterstützt mehrere Vorlagentypen, die jeweils für spezifische Anwendungsfälle konzipiert sind.

Generic Template

Das Generic Template zeigt ein Karussell von Elementen an, perfekt für Produktlisten oder Content-Feeds.

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