@natyapp/meta 1.6.7 → 1.7.0

package/docs/07-guia-pratico.md

@@ -0,0 +1,1133 @@
+# 07 - Guia Prático de Uso
+
+[⬅️ Voltar ao Índice](README.md)
+
+---
+
+## 📋 Sumário
+- [Setup Inicial](#-setup-inicial)
+- [Exemplos de Envio de Mensagens](#-exemplos-de-envio-de-mensagens)
+- [Exemplos de Recebimento de Mensagens](#-exemplos-de-recebimento-de-mensagens)
+- [Trabalhando com Mídia](#-trabalhando-com-mídia)
+- [Gestão de Conexões](#-gestão-de-conexões)
+- [Gestão de Webhooks](#-gestão-de-webhooks)
+- [Implementando um Chatbot Completo](#-implementando-um-chatbot-completo)
+- [Best Practices](#-best-practices)
+
+---
+
+## 🚀 Setup Inicial
+
+### Passo 1: Instalação
+
+```bash
+# Usando npm
+npm install @natyapp/meta
+
+# Usando pnpm
+pnpm add @natyapp/meta
+
+# Usando yarn
+yarn add @natyapp/meta
+```
+
+### Passo 2: Configuração de Variáveis de Ambiente
+
+Crie um arquivo `.env` na raiz do projeto:
+
+```env
+# Obrigatório
+API_META=https://api.meta.naty.app/v1
+NATY_APP_TOKEN=seu_app_token_aqui
+
+# Opcionais
+NODE_ENV=development
+PORT=3000
+```
+
+**Importante:** Adicione `.env` ao `.gitignore`:
+
+```gitignore
+# .gitignore
+.env
+.env.local
+.env.*.local
+node_modules/
+dist/
+```
+
+### Passo 3: Estrutura de Projeto Recomendada
+
+```
+my-whatsapp-bot/
+├── src/
+│   ├── index.ts              # Ponto de entrada
+│   ├── sdk.ts                # Inicialização do SDK
+│   ├── handlers/             # Handlers de eventos
+│   │   ├── messageHandler.ts
+│   │   └── connectionHandler.ts
+│   ├── services/             # Lógica de negócio
+│   │   ├── chatbotService.ts
+│   │   └── databaseService.ts
+│   └── utils/                # Utilitários
+│       └── logger.ts
+├── .env
+├── .gitignore
+├── package.json
+└── tsconfig.json
+```
+
+### Passo 4: Inicialização Básica
+
+**Arquivo: `src/sdk.ts`**
+
+```typescript
+import { NatyMeta } from '@natyapp/meta';
+import express from 'express';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+// Criar instância Express
+const app = express();
+app.use(express.json());
+
+// Inicializar SDK
+const sdk = new NatyMeta();
+
+export async function initializeSDK() {
+  const result = await sdk.connect({
+    appToken: process.env.NATY_APP_TOKEN!,
+    app: app,
+    pathname: '/webhooks'
+  });
+  
+  if (result.isLeft()) {
+    console.error('Erro ao inicializar SDK:', result.value);
+    process.exit(1);
+  }
+  
+  console.log('✅ SDK inicializado com sucesso!');
+  return sdk;
+}
+
+export { sdk, app };
+```
+
+**Arquivo: `src/index.ts`**
+
+```typescript
+import { initializeSDK, app } from './sdk';
+import './handlers/messageHandler';  // Registra listeners
+import './handlers/connectionHandler';
+
+async function main() {
+  // Inicializar SDK
+  await initializeSDK();
+  
+  // Iniciar servidor
+  const PORT = process.env.PORT || 3000;
+  app.listen(PORT, () => {
+    console.log(`🚀 Servidor rodando na porta ${PORT}`);
+    console.log(`📥 Webhook: http://localhost:${PORT}/webhooks/messages`);
+  });
+}
+
+main().catch(console.error);
+```
+
+### Passo 5: Configuração de Logger (Opcional mas Recomendado)
+
+O SDK suporta loggers customizados para melhor observabilidade em produção.
+
+#### Usando Pino Logger (Recomendado)
+
+**Instalar dependências:**
+```bash
+npm install pino pino-pretty
+```
+
+**Arquivo: `src/utils/logger.ts`**
+
+```typescript
+import pino from 'pino';
+import { createPinoAdapter } from '@natyapp/meta';
+
+export const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  transport: process.env.NODE_ENV === 'development' ? {
+    target: 'pino-pretty',
+    options: {
+      colorize: true,
+      translateTime: 'SYS:HH:MM:ss',
+      ignore: 'pid,hostname'
+    }
+  } : undefined
+});
+
+export const sdkLogger = createPinoAdapter(logger);
+```
+
+**Atualizar `src/sdk.ts`:**
+
+```typescript
+import { NatyMeta } from '@natyapp/meta';
+import { sdkLogger, logger } from './utils/logger';
+
+const sdk = new NatyMeta({
+  logger: sdkLogger  // Injeta logger customizado
+});
+
+export async function initializeSDK() {
+  const result = await sdk.connect({
+    appToken: process.env.NATY_APP_TOKEN!,
+    app: app,
+    pathname: '/webhooks'
+  });
+  
+  if (result.isError) {
+    logger.error({ error: result.isError }, 'Erro ao inicializar SDK');
+    process.exit(1);
+  }
+  
+  logger.info('✅ SDK inicializado com sucesso!');
+  return sdk;
+}
+```
+
+**Logs disponíveis:**
+- ✅ HTTP requests/responses (nível debug)
+- ✅ Token refresh operations (nível info)
+- ✅ Message sending/receiving (nível info)
+- ✅ Webhook processing (nível info)
+- ✅ Errors with context (nível error)
+
+---
+
+## 📤 Exemplos de Envio de Mensagens
+
+### Exemplo 1: Mensagem de Texto Simples
+
+```typescript
+import { sdk } from './sdk';
+
+async function sendTextMessage() {
+  const whatsapp = sdk.Message.WhatsappResponse({
+    companyId: 'abc123',
+    phone_number_id: '123456789012345'
+  });
+  
+  const result = await whatsapp.send_text({
+    to: '5511999999999',
+    message: 'Olá! Bem-vindo ao nosso atendimento.'
+predense: true
+  });
+  
+  if (result.isRight()) {
+    console.log('Mensagem enviada! ID:', result.value.messages[0].id);
+  } else {
+    console.error('Erro:', result.value);
+  }
+}
+```
+
+### Exemplo 2: Mensagem com Link Preview
+
+```typescript
+async function sendTextWithPreview() {
+  const whatsapp = sdk.Message.WhatsappResponse({
+    companyId: 'abc123',
+    phone_number_id: '123456789012345'
+  });
+  
+  const result = await whatsapp.send_text({
+    to: '5511999999999',
+    message: 'Confira nosso site: https://www.minhaempresa.com.br',
+    preview_url: true  // Exibe preview do link
+  });
+  
+  if (result.isRight()) {
+    console.log('Mensagem com preview enviada!');
+  }
+}
+```
+
+### Exemplo 3: Botões Interativos
+
+```typescript
+import { Button } from '@natyapp/meta';
+
+async function sendButtonMessage() {
+  const whatsapp = sdk.Message.WhatsappResponse({
+    companyId: 'abc123',
+    phone_number_id: '123456789012345'
+  });
+  
+  // Construir mensagem com botões
+  const buttonPayload = new Button()
+    .setBody('Como podemos ajudar você hoje?')
+    .addButton({ id: 'suporte', title: '💬 Suporte' })
+    .addButton({ id: 'vendas', title: '🛒 Vendas' })
+    .addButton({ id: 'financeiro', title: '💰 Financeiro' })
+    .build();
+  
+  const result = await whatsapp.send_buttons({
+    to: '5511999999999',
+    ...buttonPayload
+  });
+  
+  if (result.isRight()) {
+    console.log('Botões enviados!');
+  }
+}
+```
+
+### Exemplo 4: Lista de Opções
+
+```typescript
+import { List } from '@natyapp/meta';
+
+async function sendListMessage() {
+  const whatsapp = sdk.Message.WhatsappResponse({
+    companyId: 'abc123',
+    phone_number_id: '123456789012345'
+  });
+  
+  // Construir lista com múltiplas seções
+  const listPayload = new List()
+    .setBody('Confira nossos produtos e serviços:')
+    .setButtonText('📋 Ver Opções')
+    .addSection('Produtos')
+      .addItem({ 
+        id: 'prod_smartphone', 
+        title: '📱 Smartphones', 
+        description: 'Últimos modelos disponíveis' 
+      })
+      .addItem({ 
+        id: 'prod_notebook', 
+        title: '💻 Notebooks', 
+        description: 'Alta performance' 
+      })
+    .addSection('Serviços')
+      .addItem({ 
+        id: 'serv_suporte', 
+        title: '🔧 Suporte Técnico', 
+        description: 'Atendimento especializado' 
+      })
+      .addItem({ 
+        id: 'serv_garantia', 
+        title: '🛡️ Garantia Estendida', 
+        description: 'Proteção completa' 
+      })
+    .build();
+  
+  const result = await whatsapp.send_list({
+    to: '5511999999999',
+    ...listPayload
+  });
+  
+  if (result.isRight()) {
+    console.log('Lista enviada!');
+  }
+}
+```
+
+### Exemplo 5: Imagem com Legenda
+
+```typescript
+async function sendImageMessage() {
+  const whatsapp = sdk.Message.WhatsappResponse({
+    companyId: 'abc123',
+    phone_number_id: '123456789012345'
+  });
+  
+  const result = await whatsapp.send_image({
+    to: '5511999999999',
+    url: 'https://exemplo.com/produtos/smartphone.jpg',
+    caption: '📱 Novo Smartphone X Pro - Disponível agora!'
+  });
+  
+  if (result.isRight()) {
+    console.log('Imagem enviada!');
+  }
+}
+```
+
+### Exemplo 6: Vídeo
+
+```typescript
+async function sendVideoMessage() {
+  const whatsapp = sdk.Message.WhatsappResponse({
+    companyId: 'abc123',
+    phone_number_id: '123456789012345'
+  });
+  
+  const result = await whatsapp.send_video({
+    to: '5511999999999',
+    url: 'https://exemplo.com/videos/tutorial.mp4',
+    caption: '🎥 Tutorial: Como usar nosso produto'
+  });
+  
+  if (result.isRight()) {
+    console.log('Vídeo enviado!');
+  }
+}
+```
+
+### Exemplo 7: Documento PDF
+
+```typescript
+async function sendDocumentMessage() {
+  const whatsapp = sdk.Message.WhatsappResponse({
+    companyId: 'abc123',
+    phone_number_id: '123456789012345'
+  });
+  
+  const result = await whatsapp.send_document({
+    to: '5511999999999',
+    url: 'https://exemplo.com/documentos/catalogo.pdf',
+    filename: 'Catálogo_2026.pdf',
+    caption: '📄 Catálogo completo de produtos'
+  });
+  
+  if (result.isRight()) {
+    console.log('Documento enviado!');
+  }
+}
+```
+
+### Exemplo 8: Localização
+
+```typescript
+async function sendLocationMessage() {
+  const whatsapp = sdk.Message.WhatsappResponse({
+    companyId: 'abc123',
+    phone_number_id: '123456789012345'
+  });
+  
+  const result = await whatsapp.send_location({
+    to: '5511999999999',
+    latitude: -23.5505199,
+    longitude: -46.6333094,
+    name: 'Minha Empresa LTDA',
+    address: 'Av. Paulista, 1000 - São Paulo, SP'
+  });
+  
+  if (result.isRight()) {
+    console.log('Localização enviada!');
+  }
+}
+```
+
+### Exemplo 9: Template Aprovado
+
+```typescript
+async function sendTemplateMessage() {
+  const whatsapp = sdk.Message.WhatsappResponse({
+    companyId: 'abc123',
+    phone_number_id: '123456789012345'
+  });
+  
+  const result = await whatsapp.send_text_template({
+    to: '5511999999999',
+    template: {
+      name: 'confirmacao_pedido',  // Nome do template aprovado pela Meta
+      language: 'pt_BR',
+      components: [
+        {
+          type: 'body',
+          parameters: [
+            { type: 'text', text: 'João Silva' },       // {{1}}
+            { type: 'text', text: '#12345' },           // {{2}}
+            { type: 'text', text: 'R$ 250,00' }         // {{3}}
+          ]
+        }
+      ]
+    }
+  });
+  
+  if (result.isRight()) {
+    console.log('Template enviado!');
+  }
+}
+```
+
+### Exemplo 10: Marcar como Lido
+
+```typescript
+async function markAsRead(messageId: string) {
+  const whatsapp = sdk.Message.WhatsappResponse({
+    companyId: 'abc123',
+    phone_number_id: '123456789012345'
+  });
+  
+  const result = await whatsapp.mark_as_read(messageId);
+  
+  if (result.isRight()) {
+    console.log('Mensagem marcada como lida!');
+  }
+}
+```
+
+---
+
+## 📥 Exemplos de Recebimento de Mensagens
+
+### Exemplo 1: Handler Básico
+
+**Arquivo: `src/handlers/messageHandler.ts`**
+
+```typescript
+import { sdk } from '../sdk';
+
+sdk.on('message', async (data) => {
+  console.log('=== Nova Mensagem ===');
+  console.log('De:', data.sender);
+  console.log('Tipo:', data.message.type);
+  console.log('Mensagem:', data.message);
+  
+  // Responder automaticamente
+  await data.whatsappResponse.send_text({
+    to: data.sender,
+    message: 'Mensagem recebida! Em breve responderemos.'
+  });
+});
+```
+
+### Exemplo 2: Processamento por Tipo de Mensagem
+
+```typescript
+import { sdk } from '../sdk';
+
+sdk.on('message', async (data) => {
+  const { message, sender, whatsappResponse } = data;
+  
+  switch (message.type) {
+    case 'text':
+      await handleTextMessage(message.text.body, sender, whatsappResponse);
+      break;
+    
+    case 'image':
+      await handleImageMessage(message.image, sender, whatsappResponse);
+      break;
+    
+    case 'interactive':
+      await handleInteractiveMessage(message.interactive, sender, whatsappResponse);
+      break;
+    
+    default:
+      console.log(`Tipo não tratado: ${message.type}`);
+  }
+});
+
+async function handleTextMessage(text: string, sender: string, whatsapp: any) {
+  console.log(`Texto recebido: "${text}"`);
+  
+  const lowerText = text.toLowerCase();
+  
+  if (lowerText.includes('oi') || lowerText.includes('olá')) {
+    await whatsapp.send_text({
+      to: sender,
+      message: 'Olá! Bem-vindo. Como posso ajudar?'
+    });
+  } else if (lowerText.includes('preço') || lowerText.includes('valor')) {
+    await whatsapp.send_text({
+      to: sender,
+      message: 'Para consultar preços, digite CATALOGO.'
+    });
+  }
+}
+
+async function handleImageMessage(image: any, sender: string, whatsapp: any) {
+  console.log(`Imagem recebida: ${image.id}`);
+  
+  // Download automático
+  const downloadResult = await whatsapp.download_media(image.id);
+  
+  if (downloadResult.isRight()) {
+    console.log('Imagem baixada com sucesso!');
+    // Processar imagem (ex: análise, OCR, salvar em disco)
+  }
+  
+  await whatsapp.send_text({
+    to: sender,
+    message: 'Imagem recebida! Estamos analisando.'
+  });
+}
+
+async function handleInteractiveMessage(interactive: any, sender: string, whatsapp: any) {
+  const buttonId = interactive.button_reply?.id || interactive.list_reply?.id;
+  
+  console.log(`Botão/Item selecionado: ${buttonId}`);
+  
+  // Processar seleção
+  switch (buttonId) {
+    case 'suporte':
+      await whatsapp.send_text({
+        to: sender,
+        message: 'Você foi direcionado para o suporte. Aguarde...'
+      });
+      break;
+    
+    case 'vendas':
+      await whatsapp.send_text({
+        to: sender,
+        message: 'Equipe de vendas: (11) 99999-9999'
+      });
+      break;
+  }
+}
+```
+
+### Exemplo 3: Sistema de Contextos/Conversação
+
+```typescript
+import { sdk } from '../sdk';
+
+// Armazenar contextos de conversação
+const userContexts = new Map<string, ConversationContext>();
+
+interface ConversationContext {
+  state: string;
+  data: Record<string, any>;
+  lastInteraction: Date;
+}
+
+sdk.on('message', async (data) => {
+  const { sender, message, whatsappResponse } = data;
+  
+  // Obter ou criar contexto
+  let context = userContexts.get(sender);
+  if (!context) {
+    context = {
+      state: 'initial',
+      data: {},
+      lastInteraction: new Date()
+    };
+    userContexts.set(sender, context);
+  }
+  
+  // Atualizar last interaction
+  context.lastInteraction = new Date();
+  
+  // Processar baseado no estado
+  await processConversation(context, message, sender, whatsappResponse);
+});
+
+async function processConversation(
+  context: ConversationContext, 
+  message: any, 
+  sender: string, 
+  whatsapp: any
+) {
+  const text = message.text?.body.toLowerCase() || '';
+  
+  switch (context.state) {
+    case 'initial':
+      await whatsapp.send_text({
+        to: sender,
+        message: 'Olá! Para começar, qual é o seu nome?'
+      });
+      context.state = 'collecting_name';
+      break;
+    
+    case 'collecting_name':
+      context.data.name = message.text.body;
+      await whatsapp.send_text({
+        to: sender,
+        message: `Prazer, ${context.data.name}! Qual é o seu email?`
+      });
+      context.state = 'collecting_email';
+      break;
+    
+    case 'collecting_email':
+      context.data.email = message.text.body;
+      await whatsapp.send_text({
+        to: sender,
+        message: `Perfeito! Seu cadastro foi completo.\n\nNome: ${context.data.name}\nEmail: ${context.data.email}`
+      });
+      
+      // Salvar no banco de dados
+      await saveUserToDatabase(context.data);
+      
+      // Resetar contexto
+      userContexts.delete(sender);
+      break;
+  }
+}
+
+async function saveUserToDatabase(data: any) {
+  console.log('Salvando usuário:', data);
+  // Implementar lógica de salvamento
+}
+
+// Limpar contextos antigos a cada 30 minutos
+setInterval(() => {
+  const now = new Date();
+  for (const [sender, context] of userContexts.entries()) {
+    const diffMinutes = (now.getTime() - context.lastInteraction.getTime()) / 1000 / 60;
+    if (diffMinutes > 30) {
+      userContexts.delete(sender);
+      console.log(`Contexto expirado para ${sender}`);
+    }
+  }
+}, 30 * 60 * 1000);
+```
+
+---
+
+## 🎞 Trabalhando com Mídia
+
+### Upload de Arquivo Local
+
+```typescript
+import fs from 'fs';
+import { sdk } from './sdk';
+
+async function uploadLocalFile() {
+  const whatsapp = sdk.Message.WhatsappResponse({
+    companyId: 'abc123',
+    phone_number_id: '123456789012345'
+  });
+  
+  // Criar stream de leitura
+  const stream = fs.createReadStream('./assets/product.jpg');
+  
+  // Upload
+  const uploadResult = await whatsapp.createMedia(stream);
+  
+  if (uploadResult.isRight()) {
+    const mediaId = uploadResult.value.id;
+    console.log('Upload concluído! Media ID:', mediaId);
+    
+    // Enviar usando media_id
+    const sendResult = await whatsapp.send_image({
+      to: '5511999999999',
+      media_id: mediaId,
+      caption: 'Produto em destaque!'
+    });
+    
+    if (sendResult.isRight()) {
+      console.log('Imagem enviada!');
+    }
+  }
+}
+```
+
+### Download de Mídia Recebida
+
+```typescript
+import fs from 'fs';
+import { sdk } from './sdk';
+
+sdk.on('message', async (data) => {
+  if (data.message.type === 'image') {
+    const mediaId = data.message.image.id;
+    
+    // Download como buffer
+    const downloadResult = await data.whatsappResponse.download_media(mediaId);
+    
+    if (downloadResult.isRight()) {
+      const imageBuffer = downloadResult.value;
+      
+      // Salvar em disco
+      const filename = `./downloads/${Date.now()}_${mediaId}.jpg`;
+      fs.writeFileSync(filename, imageBuffer);
+      console.log(`Imagem salva em: ${filename}`);
+      
+      // Ou processar diretamente
+      await processImage(imageBuffer);
+    }
+  }
+});
+
+async function processImage(buffer: Buffer) {
+  // Exemplo: Análise com IA, OCR, etc.
+  console.log(`Processando imagem de ${buffer.length} bytes`);
+}
+```
+
+---
+
+## 🔧 Gestão de Conexões
+
+### Criar Nova Conexão
+
+```typescript
+import { sdk } from './sdk';
+
+async function createNewConnection() {
+  const result = await sdk.Connection.create({
+    companyId: 'abc123',
+    phoneNumberId: '123456789012345',
+    phoneNumber: '+5511999999999',
+    accessToken: 'EAAxxxxxxxxxxxxxxxxx',
+    appId: '123456789',
+    appSecret: 'abcdef1234567890',
+    accountId: '987654321',
+    businessId: '456789123'
+  });
+  
+  if (result.isRight()) {
+    console.log('Conexão criada:', result.value);
+  } else {
+    console.error('Erro ao criar conexão:', result.value);
+  }
+}
+```
+
+### Buscar Conexão
+
+```typescript
+async function getConnectionInfo() {
+  const result = await sdk.Connection.get({
+    companyId: 'abc123',
+    phoneNumberId: '123456789012345'
+  });
+  
+  if (result.isRight()) {
+    const connection = result.value;
+    console.log('Conexão encontrada:');
+    console.log('ID:', connection.id);
+    console.log('Número:', connection.phoneNumber);
+    console.log('Ativa:', connection.isActive);
+  }
+}
+```
+
+### Atualizar Token
+
+```typescript
+async function updateConnectionToken(connectionId: string, newToken: string) {
+  const result = await sdk.Connection.update(connectionId, {
+    accessToken: newToken
+  });
+  
+  if (result.isRight()) {
+    console.log('Token atualizado com sucesso!');
+  }
+}
+```
+
+### Listar Todas as Conexões
+
+```typescript
+async function listAllConnections(companyId: string) {
+  const result = await sdk.Connection.list({ companyId });
+  
+  if (result.isRight()) {
+    const connections = result.value;
+    console.log(`Total de conexões: ${connections.length}`);
+    
+    connections.forEach(conn => {
+      console.log(`- ${conn.phoneNumber} (${conn.isActive ? 'Ativa' : 'Inativa'})`);
+    });
+  }
+}
+```
+
+---
+
+## 🪝 Gestão de Webhooks
+
+### Configurar Webhooks
+
+```typescript
+import { sdk } from './sdk';
+
+async function setupWebhooks() {
+  const result = await sdk.Webhook.create({
+    companyId: 'abc123',
+    connection: {
+      url: 'https://meuapp.com/webhooks/connections',
+      active: true
+    },
+    messages: {
+      url: 'https://meuapp.com/webhooks/messages',
+      active: true
+    }
+  });
+  
+  if (result.isRight()) {
+    console.log('Webhooks configurados:', result.value);
+  }
+}
+```
+
+### Desativar Webhook Temporariamente
+
+```typescript
+async function disableMessageWebhook(webhookId: string) {
+  const result = await sdk.Webhook.update(webhookId, {
+    messages: {
+      url: 'https://meuapp.com/webhooks/messages',
+      active: false  // Desativa
+    }
+  });
+  
+  if (result.isRight()) {
+    console.log('Webhook de mensagens desativado');
+  }
+}
+```
+
+---
+
+## 🤖 Implementando um Chatbot Completo
+
+### Chatbot com IA (Exemplo Completo)
+
+```typescript
+import { sdk } from './sdk';
+import { Button, List } from '@natyapp/meta';
+
+// Simulação de serviço de IA
+async function getAIResponse(userMessage: string): Promise<string> {
+  // Aqui você integraria com OpenAI, DialogFlow, etc.
+  const responses: Record<string, string> = {
+    'horário': 'Atendemos de segunda a sexta, das 9h às 18h.',
+    'preço': 'Nossos produtos variam de R$ 50 a R$ 5.000.',
+    'entrega': 'Entregamos em todo o Brasil em até 7 dias úteis.',
+  };
+  
+  for (const [key, response] of Object.entries(responses)) {
+    if (userMessage.toLowerCase().includes(key)) {
+      return response;
+    }
+  }
+  
+  return 'Desculpe, não entendi. Digite MENU para ver as opções disponíveis.';
+}
+
+// Handler principal
+sdk.on('message', async (data) => {
+  const { sender, message, whatsappResponse } = data;
+  
+  // Logs
+  console.log(`[${new Date().toISOString()}] Mensagem de ${sender}`);
+  
+  // Processar por tipo
+  if (message.type === 'text') {
+    const userText = message.text.body.trim();
+    
+    // Comandos especiais
+    if (userText.toUpperCase() === 'MENU') {
+      await sendMainMenu(sender, whatsappResponse);
+      return;
+    }
+    
+    if (userText.toUpperCase() === 'CATALOGO') {
+      await sendCatalog(sender, whatsappResponse);
+      return;
+    }
+    
+    // Processar com IA
+    const aiResponse = await getAIResponse(userText);
+    await whatsappResponse.send_text({
+      to: sender,
+      message: aiResponse
+    });
+    
+  } else if (message.type === 'interactive') {
+    await handleInteractiveSelection(message.interactive, sender, whatsappResponse);
+  }
+  
+  // Marcar como lido
+  await whatsappResponse.mark_as_read(message.id);
+});
+
+async function sendMainMenu(to: string, whatsapp: any) {
+  const buttons = new Button()
+    .setBody('🏠 *Menu Principal*\n\nEscolha uma opção:')
+    .addButton({ id: 'products', title: '🛍️ Produtos' })
+    .addButton({ id: 'support', title: '💬 Suporte' })
+    .addButton({ id: 'about', title: 'ℹ️ Sobre Nós' })
+    .build();
+  
+  await whatsapp.send_buttons({ to, ...buttons });
+}
+
+async function sendCatalog(to: string, whatsapp: any) {
+  const list = new List()
+    .setBody('📱 *Catálogo de Produtos*\n\nSelecione uma categoria:')
+    .setButtonText('Ver Catálogo')
+    .addSection('Eletrônicos')
+      .addItem({ id: 'cat_smartphones', title: 'Smartphones', description: 'Últimos modelos' })
+      .addItem({ id: 'cat_notebooks', title: 'Notebooks', description: 'Alta performance' })
+    .addSection('Acessórios')
+      .addItem({ id: 'cat_fones', title: 'Fones de Ouvido', description: 'Som premium' })
+      .addItem({ id: 'cat_capas', title: 'Capas e Películas', description: 'Proteção total' })
+    .build();
+  
+  await whatsapp.send_list({ to, ...list });
+}
+
+async function handleInteractiveSelection(interactive: any, sender: string, whatsapp: any) {
+  const selectedId = interactive.button_reply?.id || interactive.list_reply?.id;
+  
+  console.log(`Usuário selecionou: ${selectedId}`);
+  
+  switch (selectedId) {
+    case 'products':
+      await sendCatalog(sender, whatsapp);
+      break;
+    
+    case 'support':
+      await whatsapp.send_text({
+        to: sender,
+        message: '💬 *Suporte*\n\nWhatsApp: (11) 99999-9999\nEmail: suporte@empresa.com\nHorário: Seg-Sex, 9h-18h'
+      });
+      break;
+    
+    case 'about':
+      await whatsapp.send_text({
+        to: sender,
+        message: 'ℹ️ *Sobre Nós*\n\nSomos uma empresa especializada em tecnologia desde 2020.\n\nMissão: Levar tecnologia de qualidade a todos.'
+      });
+      break;
+    
+    case 'cat_smartphones':
+      await whatsapp.send_text({
+        to: sender,
+        message: '📱 *Smartphones*\n\n1. iPhone 14 Pro - R$ 7.999\n2. Samsung S23 - R$ 5.499\n3. Xiaomi 13 - R$ 3.999\n\nPara mais info, digite o número do produto.'
+      });
+      break;
+  }
+}
+```
+
+---
+
+## ✅ Best Practices
+
+### 1. Tratamento de Erros Robusto
+
+```typescript
+async function sendMessageSafely(to: string, message: string) {
+  try {
+    const whatsapp = sdk.Message.WhatsappResponse({
+      companyId: 'abc123',
+      phone_number_id: '123456789012345'
+    });
+    
+    const result = await whatsapp.send_text({ to, message });
+    
+    if (result.isLeft()) {
+      // Log estruturado
+      console.error('Erro ao enviar mensagem:', {
+        to,
+        error: result.value,
+        timestamp: new Date().toISOString()
+      });
+      
+      // Alertar equipe (ex: Slack, email)
+      await notifyTeam(`Falha no envio para ${to}`);
+      
+      return false;
+    }
+    
+    return true;
+  } catch (error) {
+    console.error('Exceção não tratada:', error);
+    return false;
+  }
+}
+```
+
+### 2. Rate Limiting
+
+```typescript
+import PQueue from 'p-queue';
+
+// Fila com limite
+const messageQueue = new PQueue({
+  interval: 1000,    // 1 segundo
+  intervalCap: 10    // 10 mensagens por segundo
+});
+
+async function sendWithQueue(to: string, message: string) {
+  return messageQueue.add(() => 
+    whatsapp.send_text({ to, message })
+  );
+}
+```
+
+### 3. Timeout para Webhooks
+
+```typescript
+sdk.on('message', async (data) => {
+  // Responder imediatamente à Meta (evitar timeout de 15s)
+  setImmediate(async () => {
+    try {
+      await processMessageAsync(data);
+    } catch (error) {
+      console.error('Erro no processamento:', error);
+    }
+  });
+});
+
+async function processMessageAsync(data: any) {
+  // Processamento demorado aqui
+  const analysis = await deepAnalysis(data.message);
+  await sendResponse(data.sender, analysis);
+}
+```
+
+### 4. Logging Estruturado
+
+```typescript
+import winston from 'winston';
+
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.json(),
+  transports: [
+    new winston.transports.File({ filename: 'error.log', level: 'error' }),
+    new winston.transports.File({ filename: 'combined.log' })
+  ]
+});
+
+sdk.on('message', (data) => {
+  logger.info('message_received', {
+    sender: data.sender,
+    type: data.message.type,
+    timestamp: new Date().toISOString()
+  });
+});
+```
+
+### 5. Validação de Números
+
+```typescript
+import { parsePhoneNumber } from 'libphonenumber-js';
+
+function validateAndFormatPhone(phone: string, countryCode: string = 'BR'): string | null {
+  try {
+    const phoneNumber = parsePhoneNumber(phone, countryCode);
+    if (phoneNumber.isValid()) {
+      return phoneNumber.format('E.164'); // +5511999999999
+    }
+  } catch (error) {
+    console.error('Número inválido:', phone);
+  }
+  return null;
+}
+
+// Uso
+const formattedPhone = validateAndFormatPhone('11999999999', 'BR');
+if (formattedPhone) {
+  await whatsapp.send_text({ to: formattedPhone, message: 'Olá!' });
+}
+```
+
+---
+
+## 🔗 Próximos Passos
+
+- **[Troubleshooting](08-troubleshooting.md)** - Resolva problemas comuns
+- **[Integrações](05-integracoes.md)** - Aprofunde-se nas APIs
+- **[Fluxos Funcionais](04-fluxos-funcionais.md)** - Entenda os processos internos
+
+---
+
+[⬅️ Anterior: Entidades](06-entidades.md) | [⬆️ Voltar ao Índice](README.md) | [➡️ Próximo: Troubleshooting](08-troubleshooting.md)