Facebook Messenger API: Crie Experiências Conversacionais

A Facebook Messenger API permite que desenvolvedores criem experiências conversacionais que alcançam mais de 1,3 bilhão de usuários ativos mensais. Seja criando um bot de suporte ao cliente, um assistente de e-commerce ou uma campanha de marketing interativa, a messenger platform api fornece as ferramentas necessárias para engajar usuários em conversas significativas.

Este guia orienta você em tudo, desde a configuração inicial até recursos avançados como templates de mensagem, respostas rápidas e o protocolo de transferência para humanos. Você encontrará exemplos funcionais em TypeScript ao longo do texto, prontos para adaptar aos seus próprios projetos.

Introdução à Messenger Platform

A Messenger Platform é o framework da Meta para construir bots e integrações que se comunicam com usuários através do Facebook Messenger. Diferente de interfaces web tradicionais, a facebook chat api cria uma experiência conversacional onde usuários interagem através de mensagens, botões e mídia rica.

As principais capacidades da messenger bot api incluem:

A plataforma opera em uma arquitetura baseada em webhook. Seu servidor recebe mensagens de entrada via webhooks, processa-as e responde usando a Send API. Este modelo assíncrono permite construir experiências responsivas sem manter conexões abertas.

Configurando Seu Meta App

Antes de usar a facebook messenger api, você precisa criar e configurar um Meta App. Este processo estabelece a identidade da sua aplicação e concede acesso à Messenger Platform.

Passo 1: Criar um Meta App

Navegue até o portal Meta for Developers e crie um novo app. Selecione "Business" como tipo de app, que fornece acesso aos recursos do 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!
  };
}

Passo 2: Adicionar o Produto Messenger

No painel do seu app, clique em "Add Product" e selecione Messenger. Isso habilita os recursos da Messenger Platform para seu app.

Passo 3: Conectar uma Página do Facebook

Seu bot precisa de uma Página do Facebook para enviar e receber mensagens. Nas configurações do Messenger, clique em "Add or Remove Pages" e selecione a página que deseja conectar. Gere um Page Access Token, que você usará para autenticar requisições à API.

Nota: Page Access Tokens podem ser de curta ou longa duração. Para aplicações em produção, troque seu token por uma versão de longa duração que dura aproximadamente 60 dias.

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

Passo 4: Configurar Permissões do App

Solicite as permissões necessárias para seu bot. No mínimo, você precisará de:

• pages_messaging: Enviar e receber mensagens
• pages_manage_metadata: Inscrever-se em webhooks
• pages_read_engagement: Acessar dados de conversas

Configuração e Verificação de Webhook

Webhooks são a espinha dorsal da messenger platform api. Eles permitem que o Facebook notifique seu servidor quando eventos ocorrem, como mensagens recebidas ou entregas de mensagens.

Configurando Seu Endpoint de Webhook

Crie um endpoint que lide tanto com requisições GET (para verificação) quanto POST (para receber eventos).

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

Inscrevendo-se em Eventos de Webhook

Após configurar seu endpoint, inscreva-se nos eventos que deseja receber. No Painel do Meta App, configure sua URL de webhook e selecione os campos de inscrição relevantes:

• messages: Mensagens recebidas
• messaging_postbacks: Cliques em botões e seleções de menu
• messaging_optins: Opt-ins de usuários
• message_deliveries: Confirmações de entrega
• message_reads: Confirmações de leitura

Recebendo Mensagens

Quando usuários enviam mensagens para seu bot, a facebook chat api as entrega ao seu webhook. Mensagens podem conter texto, anexos ou ambos.

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

Enviando Mensagens de Texto

A Send API é sua ferramenta principal para responder aos usuários através da messenger bot api. Mensagens de texto são a forma mais simples de resposta.

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 Mensagem (Generic, Button, Receipt)

Templates de mensagem criam experiências ricas e interativas que vão além do texto simples. A facebook messenger api suporta vários tipos de template, cada um projetado para casos de uso específicos.

Generic Template

O Generic Template exibe um carrossel de itens, perfeito para listagens de produtos ou feeds de conteúdo.

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