@natyapp/meta 1.6.6 → 1.7.0

package/docs/04-fluxos-funcionais.md

@@ -0,0 +1,887 @@
+# 04 - Fluxos Funcionais
+
+[⬅️ Voltar ao Índice](README.md)
+
+---
+
+## 📋 Sumário
+- [Fluxo 1: Inicialização do SDK](#fluxo-1-inicialização-do-sdk)
+- [Fluxo 2: Envio de Mensagens](#fluxo-2-envio-de-mensagens)
+- [Fluxo 3: Recebimento de Mensagens (Webhooks)](#fluxo-3-recebimento-de-mensagens-webhooks)
+- [Fluxo 4: Verificação de Conexão](#fluxo-4-verificação-de-conexão)
+- [Fluxo 5: Upload e Download de Mídia](#fluxo-5-upload-e-download-de-mídia)
+- [Fluxo 6: Gestão de Tokens](#fluxo-6-gestão-de-tokens)
+- [Fluxos Alternativos e Tratamento de Erros](#fluxos-alternativos-e-tratamento-de-erros)
+
+---
+
+## Fluxo 1: Inicialização do SDK
+
+### Objetivo
+Autenticar a aplicação no SDK e preparar o ambiente para envio/recepção de mensagens.
+
+### Pré-condições
+- Aplicação possui um `appToken` válido fornecido pela plataforma Naty
+- Variável de ambiente `API_META` configurada
+- (Opcional) Instância do Express.js para webhooks
+
+### Atores
+- **Desenvolvedor/Aplicação:** Inicializa e configura o SDK
+- **SDK Naty Meta:** Processa autenticação e configuração
+- **Naty Meta API:** Valida credenciais
+
+### Fluxo Principal
+
+```mermaid
+sequenceDiagram
+    participant Dev as Desenvolvedor
+    participant App as Aplicação
+    participant SDK as NatyMeta SDK
+    participant Interceptor as Axios Interceptor
+    participant Naty as Naty Meta API
+    participant Express as Express App
+    
+    Note over Dev,App: 1. Instanciação
+    Dev->>App: Implementa código de inicialização
+    App->>SDK: new NatyMeta()
+    SDK-->>App: Instância criada (não autenticada)
+    
+    Note over App,Naty: 2. Autenticação
+    App->>SDK: connect({ appToken, app?, pathname? })
+    SDK->>SDK: Valida parâmetros obrigatórios
+    
+    SDK->>Naty: POST /validate/validateAppToken<br/>{ appToken }
+    alt Token válido
+        Naty-->>SDK: 200 OK { valid: true, data }
+        
+        Note over SDK,Interceptor: 3. Configuração
+        SDK->>Interceptor: updateAxiosInterceptor(appToken)
+        Interceptor->>Interceptor: Injeta header 'x-access-token'
+        
+        alt Express fornecido
+            SDK->>Express: app.use(pathname, webhookRoutes)
+            Express-->>SDK: Rotas registradas
+        end
+        
+        SDK->>SDK: Inicializa managers<br/>(Connection, Message, Webhook, Log)
+        
+        SDK-->>App: Either.right({ success: true })
+        App-->>Dev: SDK pronto para uso
+    else Token inválido
+        Naty-->>SDK: 401 Unauthorized
+        SDK-->>App: Either.left(Error: 'Invalid appToken')
+        App-->>Dev: Erro de autenticação
+    end
+```
+
+### Código Exemplo
+
+```typescript
+import express from 'express';
+import { NatyMeta } from '@natyapp/meta';
+
+const app = express();
+app.use(express.json());
+
+// Inicializar SDK
+const sdk = new NatyMeta();
+const result = await sdk.connect({
+  appToken: process.env.NATY_APP_TOKEN,
+  app: app,                              // (Opcional) Express para webhooks
+  pathname: '/webhooks'                  // (Opcional) Base path
+});
+
+if (result.isRight()) {
+  console.log('SDK inicializado com sucesso!');
+  
+  // Acessar módulos
+  const connectionManager = sdk.Connection;
+  const messageManager = sdk.Message;
+  
+  app.listen(3000, () => {
+    console.log('Servidor rodando na porta 3000');
+  });
+} else {
+  console.error('Erro ao inicializar SDK:', result.value);
+  process.exit(1);
+}
+```
+
+### Pós-condições (Sucesso)
+- ✅ SDK autenticado com appToken válido
+- ✅ Interceptores configurados (header automático)
+- ✅ Webhooks registrados (se Express fornecido)
+- ✅ Managers disponíveis para uso
+
+### Pós-condições (Falha)
+- ❌ SDK não autenticado
+- ❌ Managers não disponíveis
+- ❌ Erro retornado via Either.left
+
+---
+
+## Fluxo 2: Envio de Mensagens
+
+### Objetivo
+Enviar mensagem de qualquer tipo (texto, mídia, interativa) para um número WhatsApp.
+
+### Pré-condições
+- SDK inicializado e conectado
+- Conexão WhatsApp cadastrada no sistema (companyId + phoneNumberId)
+- Número destinatário no formato E.164
+
+### Atores
+- **Aplicação:** Solicita envio de mensagem
+- **WhatsappResponse:** Orquestra o fluxo de envio
+- **Connection Manager:** Busca e atualiza credenciais
+- **Meta Graph API:** Entrega mensagem ao WhatsApp
+
+### Fluxo Principal
+
+```mermaid
+sequenceDiagram
+    participant App as Aplicação
+    participant WR as WhatsappResponse
+    participant ConnMgr as Connection Manager
+    participant NatyAPI as Naty Meta API
+    participant MetaAPI as Meta Graph API
+    participant WA as WhatsApp
+    
+    Note over App,WR: 1. Criação da Instância
+    App->>WR: new WhatsappResponse({<br/>companyId, phone_number_id })
+    
+    Note over WR,NatyAPI: 2. Buscar Conexão
+    WR->>ConnMgr: getConnection(companyId, phoneNumberId)
+    ConnMgr->>NatyAPI: GET /connection?companyId&phoneNumberId
+    NatyAPI-->>ConnMgr: ConnectionEntity { accessToken, appId, appSecret }
+    ConnMgr-->>WR: ConnectionEntity
+    
+    Note over WR,MetaAPI: 3. Refresh Token (se necessário)
+    WR->>WR: update_long_lived_token(connection)
+    WR->>MetaAPI: POST /oauth/access_token<br/>{ grant_type, client_id, client_secret, fb_exchange_token }
+    MetaAPI-->>WR: { access_token: newToken, expires_in: 5184000 }
+    WR->>NatyAPI: PUT /connection { accessToken: newToken }
+    
+    Note over WR,WR: 4. Criar Cliente Meta
+    WR->>WR: createMetaAxios(newAccessToken, phoneNumberId)
+    
+    Note over App,MetaAPI: 5. Enviar Mensagem
+    App->>WR: send_text({ to: '5511999999999', message: 'Olá!' })
+    WR->>WR: Monta payload JSON<br/>{ messaging_product: 'whatsapp', to, type: 'text', text: { body } }
+    WR->>MetaAPI: POST /{phoneNumberId}/messages<br/>Authorization: Bearer {accessToken}
+    
+    MetaAPI->>WA: Processa e entrega
+    WA-->>MetaAPI: Mensagem entregue
+    
+    MetaAPI-->>WR: 200 OK { messages: [{ id: 'wamid.xxx' }] }
+    WR-->>App: Either.right({ id: 'wamid.xxx' })
+    
+    Note over App: 6. Mensagem enviada com sucesso
+```
+
+### Código Exemplo - Texto Simples
+
+```typescript
+// Criar instância WhatsappResponse
+const whatsapp = sdk.Message.WhatsappResponse({
+  companyId: 'abc123',
+  phone_number_id: '123456789012345'
+});
+
+// Enviar mensagem de texto
+const result = await whatsapp.send_text({
+  to: '5511999999999',
+  message: 'Olá! Como posso ajudar você hoje?'
+});
+
+if (result.isRight()) {
+  console.log('Mensagem enviada! ID:', result.value.messages[0].id);
+} else {
+  console.error('Erro ao enviar:', result.value);
+}
+```
+
+### Código Exemplo - Botões Interativos
+
+```typescript
+import { Button } from '@natyapp/meta';
+
+// Construir mensagem com botões
+const buttonPayload = new Button()
+  .setBody('Escolha uma opção:')
+  .addButton({ id: 'opt_suporte', title: '💬 Suporte' })
+  .addButton({ id: 'opt_vendas', title: '🛒 Vendas' })
+  .addButton({ id: 'opt_financeiro', title: '💰 Financeiro' })
+  .build();
+
+// Enviar
+const result = await whatsapp.send_buttons({
+  to: '5511999999999',
+  ...buttonPayload
+});
+```
+
+### Código Exemplo - Lista de Opções
+
+```typescript
+import { List } from '@natyapp/meta';
+
+const listPayload = new List()
+  .setBody('Confira nossos produtos:')
+  .setButtonText('Ver Produtos')
+  .addSection('Eletrônicos')
+    .addItem({ id: 'prod_001', title: 'Smartphone', description: 'R$ 2.000,00' })
+    .addItem({ id: 'prod_002', title: 'Notebook', description: 'R$ 4.500,00' })
+  .addSection('Eletrodomésticos')
+    .addItem({ id: 'prod_101', title: 'Geladeira', description: 'R$ 3.200,00' })
+    .addItem({ id: 'prod_102', title: 'Máquina Lavar', description: 'R$ 2.800,00' })
+  .build();
+
+const result = await whatsapp.send_list({
+  to: '5511999999999',
+  ...listPayload
+});
+```
+
+### Pós-condições (Sucesso)
+- ✅ Mensagem enviada ao WhatsApp do destinatário
+- ✅ ID da mensagem retornado (`wamid.xxx`)
+- ✅ Token atualizado (se estava próximo de expirar)
+
+### Pós-condições (Falha)
+- ❌ Mensagem não enviada
+- ❌ Erro retornado via Either.left com contexto
+
+---
+
+## Fluxo 3: Recebimento de Mensagens (Webhooks)
+
+### Objetivo
+Receber mensagens enviadas por clientes via WhatsApp e disponibilizá-las à aplicação via eventos.
+
+### Pré-condições
+- SDK inicializado com Express integrado
+- Webhook URL configurada no Meta for Developers
+- Aplicação possui listener para evento `'message'`
+
+### Atores
+- **Cliente WhatsApp:** Envia mensagem
+- **Meta WhatsApp Platform:** Recebe mensagem e envia webhook
+- **Webhook Route:** Processa payload e emite evento
+- **Aplicação:** Escuta evento e processa mensagem
+
+### Fluxo Principal
+
+```mermaid
+sequenceDiagram
+    participant Client as Cliente WhatsApp
+    participant WA as WhatsApp Platform
+    participant Meta as Meta Webhook Service
+    participant Route as Webhook Route<br/>(SDK)
+    participant SDK as NatyMeta EventEmitter
+    participant App as Aplicação
+    
+    Note over Client,Meta: 1. Cliente Envia Mensagem
+    Client->>WA: Envia mensagem pelo WhatsApp
+    WA->>Meta: Processa e prepara webhook
+    
+    Note over Meta,Route: 2. Meta Envia Webhook
+    Meta->>Route: POST /webhooks/messages<br/>{ object: 'whatsapp_business_account', entry: [...] }
+    
+    Note over Route: 3. Processamento do Payload
+    Route->>Route: Valida estrutura do payload
+    Route->>Route: Extrai dados:<br/>- companyId (de phoneNumberId)<br/>- sender (número do cliente)<br/>- message (conteúdo)
+    
+    Route->>Route: Cria WhatsappMessage entity
+    Route->>Route: Instancia WhatsappResponse<br/>(para responder)
+    
+    Note over SDK,App: 4. Emissão de Evento
+    Route->>SDK: emit('message', {<br/>companyId, sender, message, whatsappResponse })
+    SDK->>App: Dispara listeners registrados
+    
+    Note over App: 5. Processamento pela Aplicação
+    App->>App: Executa lógica de negócio<br/>(chatbot, IA, regras)
+    
+    alt Resposta Automática
+        App->>Route: whatsappResponse.send_text({ to: sender, message })
+        Route->>Meta: POST /messages
+        Meta->>WA: Envia resposta
+        WA->>Client: Cliente recebe resposta
+    end
+    
+    Route-->>Meta: 200 OK (confirma recebimento)
+```
+
+### Estrutura do Payload (Meta)
+
+<details>
+<summary>Ver payload completo de exemplo (clique para expandir)</summary>
+
+```json
+{
+  "object": "whatsapp_business_account",
+  "entry": [
+    {
+      "id": "123456789",
+      "changes": [
+        {
+          "value": {
+            "messaging_product": "whatsapp",
+            "metadata": {
+              "display_phone_number": "5511999999999",
+              "phone_number_id": "123456789012345"
+            },
+            "contacts": [
+              {
+                "profile": { "name": "João Silva" },
+                "wa_id": "5511888888888"
+              }
+            ],
+            "messages": [
+              {
+                "from": "5511888888888",
+                "id": "wamid.HBgNNTUxMTk4ODg4ODg4OBUCABIYIDNBNjdGMzQ5QzE5MEFCMTY1MjU0",
+                "timestamp": "1709740800",
+                "type": "text",
+                "text": { "body": "Olá, preciso de ajuda!" }
+              }
+            ]
+          },
+          "field": "messages"
+        }
+      ]
+    }
+  ]
+}
+```
+</details>
+
+### Código Exemplo - Listener
+
+```typescript
+// Registrar listener para mensagens
+sdk.on('message', async (data) => {
+  console.log(`Nova mensagem de ${data.sender}:`);
+  console.log(`Tipo: ${data.message.type}`);
+  
+  // Processar diferentes tipos de mensagem
+  if (data.message.type === 'text') {
+    const userText = data.message.text.body.toLowerCase();
+    
+    // Lógica de chatbot simples
+    let response = '';
+    
+    if (userText.includes('oi') || userText.includes('olá')) {
+      response = 'Olá! Como posso ajudar você hoje?';
+    } else if (userText.includes('horário')) {
+      response = 'Atendemos de segunda a sexta, das 9h às 18h.';
+    } else if (userText.includes('preço')) {
+      response = 'Para consultar preços, envie "CATALOGO".';
+    } else {
+      response = 'Desculpe, não entendi. Digite MENU para ver as opções.';
+    }
+    
+    // Responder automaticamente
+    await data.whatsappResponse.send_text({
+      to: data.sender,
+      message: response
+    });
+  } else if (data.message.type === 'interactive') {
+    // Cliente clicou em botão ou selecionou item de lista
+    const buttonId = data.message.interactive.button_reply?.id || 
+                     data.message.interactive.list_reply?.id;
+    
+    console.log(`Cliente selecionou: ${buttonId}`);
+    
+    // Processar seleção
+    await handleInteraction(buttonId, data);
+  } else if (data.message.type === 'image') {
+    // Cliente enviou imagem
+    const mediaId = data.message.image.id;
+    
+    // Download da imagem
+    const imageResult = await data.whatsappResponse.download_media(mediaId);
+    
+    if (imageResult.isRight()) {
+      const buffer = imageResult.value;
+      // Salvar ou processar imagem (ex: OCR, análise de IA)
+      await processImage(buffer);
+    }
+  }
+});
+```
+
+### Código Exemplo - Sistema Avançado de Roteamento
+
+```typescript
+// Gerenciador de conversação
+class ConversationManager {
+  private contexts = new Map<string, string>(); // sender -> context
+  
+  async handleMessage(data: MessageEventData) {
+    const sender = data.sender;
+    const context = this.contexts.get(sender) || 'initial';
+    
+    // Máquina de estados
+    switch (context) {
+      case 'initial':
+        await this.showMainMenu(data);
+        this.contexts.set(sender, 'menu');
+        break;
+      
+      case 'menu':
+        await this.handleMenuSelection(data);
+        break;
+      
+      case 'collecting_name':
+        await this.collectName(data);
+        this.contexts.set(sender, 'collecting_email');
+        break;
+      
+      case 'collecting_email':
+        await this.collectEmail(data);
+        this.contexts.set(sender, 'completed');
+        break;
+      
+      default:
+        this.contexts.delete(sender);
+        await this.showMainMenu(data);
+    }
+  }
+  
+  private async showMainMenu(data: MessageEventData) {
+    const buttons = new Button()
+      .setBody('Bem-vindo! Escolha uma opção:')
+      .addButton({ id: 'info', title: 'Informações' })
+      .addButton({ id: 'support', title: 'Suporte' })
+      .addButton({ id: 'register', title: 'Cadastrar' })
+      .build();
+    
+    await data.whatsappResponse.send_buttons({
+      to: data.sender,
+      ...buttons
+    });
+  }
+  
+  // ... outros métodos
+}
+
+const conversationMgr = new ConversationManager();
+
+sdk.on('message', (data) => {
+  conversationMgr.handleMessage(data);
+});
+```
+
+### Pós-condições (Sucesso)
+- ✅ Mensagem recebida e processada
+- ✅ Evento emitido para todos os listeners
+- ✅ Webhook confirmado (200 OK) para Meta
+- ✅ Resposta enviada (se aplicável)
+
+### Pós-condições (Falha)
+- ❌ Se webhook falhar (erro 5xx), Meta retentar até 3x
+- ❌ Se timeout (>15s), Meta considerar falha
+
+---
+
+## Fluxo 4: Verificação de Conexão
+
+### Objetivo
+Validar se uma conexão WhatsApp está ativa e obter informações da conta.
+
+### Pré-condições
+- Conexão criada no sistema (ConnectionEntity)
+- Webhook de verificação configurado na Meta
+
+### Fluxo Principal
+
+```mermaid
+sequenceDiagram
+    participant Meta as Meta Webhook<br/>Verification
+    participant Route as Webhook Route<br/>/webhooks/connections
+    participant NatyAPI as Naty Meta API
+    participant MetaAPI as Meta Graph API
+    participant SDK as NatyMeta EventEmitter
+    participant App as Aplicação
+    
+    Note over Meta,Route: 1. Verification Request (GET)
+    Meta->>Route: GET /webhooks/connections?<br/>hub.mode=subscribe&<br/>hub.challenge=xyz&<br/>hub.verify_token=conn_abc123
+    
+    Route->>Route: Extrai connectionId do verify_token
+    Route-->>Meta: 200 OK { challenge: 'xyz' }
+    
+    Note over Meta,Route: 2. Connection Event (POST)
+    Meta->>Route: POST /webhooks/connections<br/>{ verify_token: 'conn_abc123', ... }
+    
+    Note over Route,MetaAPI: 3. Buscar Informações
+    Route->>Route: Extrai connectionId
+    Route->>NatyAPI: GET /connection?id=conn_abc123
+    NatyAPI-->>Route: ConnectionEntity { phoneNumberId, accessToken }
+    
+    Route->>MetaAPI: GET /{phoneNumberId}<br/>Authorization: Bearer {accessToken}
+    MetaAPI-->>Route: {<br/>  id: '123',<br/>  verified_name: 'Minha Empresa',<br/>  display_phone_number: '+55...',<br/>  quality_rating: 'GREEN'<br/>}
+    
+    Note over SDK,App: 4. Emitir Evento
+    Route->>SDK: emit('connection', {<br/>connectionId, accountInfo })
+    SDK->>App: Dispara listener
+    
+    App->>App: Confirma conexão ativa<br/>Atualiza dashboard
+    
+    Route-->>Meta: 200 OK
+```
+
+### Código Exemplo
+
+```typescript
+sdk.on('connection', (data) => {
+  console.log('=== Conexão Verificada ===');
+  console.log(`Connection ID: ${data.connectionId}`);
+  console.log(`Nome Verificado: ${data.accountInfo.verified_name}`);
+  console.log(`Número: ${data.accountInfo.display_phone_number}`);
+  console.log(`Quality Rating: ${data.accountInfo.quality_rating}`);
+  
+  // Atualizar status no banco de dados
+  updateConnectionStatus(data.connectionId, 'active');
+  
+  // Alertar equipe se quality rating estiver baixo
+  if (data.accountInfo.quality_rating !== 'GREEN') {
+    notifyAdmins(`ALERTA: Quality rating ${data.accountInfo.quality_rating} para ${data.accountInfo.display_phone_number}`);
+  }
+});
+```
+
+### Pós-condições
+- ✅ Conexão confirmada como ativa
+- ✅ Informações da conta atualizadas
+- ✅ Quality rating monitorado
+
+---
+
+## Fluxo 5: Upload e Download de Mídia
+
+### Objetivo
+Fazer upload de mídia (imagem, vídeo, documento) e fazer download de mídia recebida.
+
+### Fluxo 5A: Upload de Mídia
+
+```mermaid
+sequenceDiagram
+    participant App as Aplicação
+    participant WR as WhatsappResponse
+    participant MetaAPI as Meta Graph API
+    
+    Note over App,WR: 1. Preparar Stream
+    App->>App: Ler arquivo do disco<br/>const stream = fs.createReadStream('image.jpg')
+    
+    Note over App,MetaAPI: 2. Upload
+    App->>WR: createMedia(stream)
+    WR->>WR: Prepara FormData<br/>{ file: stream, messaging_product: 'whatsapp' }
+    WR->>MetaAPI: POST /{phoneNumberId}/media<br/>Content-Type: multipart/form-data
+    MetaAPI-->>WR: 200 OK { id: 'media_123abc' }
+    WR-->>App: Either.right({ id: 'media_123abc' })
+    
+    Note over App,MetaAPI: 3. Usar Media ID
+    App->>WR: send_image({<br/>  to: '5511999999999',<br/>  media_id: 'media_123abc',<br/>  caption: 'Veja esta imagem!'<br/>})
+    WR->>MetaAPI: POST /messages { type: 'image', image: { id: 'media_123abc' } }
+    MetaAPI-->>WR: Mensagem enviada
+    WR-->>App: Either.right({ id: 'wamid.xxx' })
+```
+
+#### Código Exemplo - Upload
+
+```typescript
+import fs from 'fs';
+
+// Upload de imagem
+const stream = fs.createReadStream('./assets/product.jpg');
+const uploadResult = await whatsapp.createMedia(stream);
+
+if (uploadResult.isRight()) {
+  const mediaId = uploadResult.value.id;
+  console.log('Mídia enviada! ID:', mediaId);
+  
+  // Enviar imagem usando media_id
+  const sendResult = await whatsapp.send_image({
+    to: '5511999999999',
+    media_id: mediaId,
+    caption: 'Confira nosso novo produto!'
+  });
+} else {
+  console.error('Erro no upload:', uploadResult.value);
+}
+```
+
+### Fluxo 5B: Download de Mídia
+
+```mermaid
+sequenceDiagram
+    participant App as Aplicação
+    participant WR as WhatsappResponse
+    participant MetaAPI as Meta Graph API
+    
+    Note over App: 1. Receber Media ID (via webhook)
+    App->>App: message.image.id = 'media_123abc'
+    
+    Note over App,MetaAPI: 2. Obter URL Temporária
+    App->>WR: get_media_url('media_123abc')
+    WR->>MetaAPI: GET /media_123abc<br/>Authorization: Bearer {token}
+    MetaAPI-->>WR: 200 OK {<br/>  url: 'https://mmg.whatsapp.net/d/...',<br/>  mime_type: 'image/jpeg',<br/>  file_size: 52431<br/>}
+    WR-->>App: Either.right({ url, mime_type, file_size })
+    
+    Note over App,MetaAPI: 3. Download do Arquivo
+    App->>WR: download_media('media_123abc')
+    WR->>MetaAPI: GET {url} (URL temporária, válida ~5min)
+    MetaAPI-->>WR: Binary data (Buffer)
+    WR-->>App: Either.right(Buffer)
+    
+    Note over App: 4. Salvar ou Processar
+    App->>App: fs.writeFileSync('downloads/image.jpg', buffer)<br/>ou processImage(buffer)
+```
+
+#### Código Exemplo - Download
+
+```typescript
+sdk.on('message', async (data) => {
+  if (data.message.type === 'image') {
+    const mediaId = data.message.image.id;
+    
+    // Método 1: Obter URL temporária
+    const urlResult = await data.whatsappResponse.get_media_url(mediaId);
+    if (urlResult.isRight()) {
+      console.log('URL da mídia:', urlResult.value.url);
+      console.log('MIME Type:', urlResult.value.mime_type);
+      console.log('Tamanho:', urlResult.value.file_size, 'bytes');
+    }
+    
+    // Método 2: Download direto como Buffer
+    const downloadResult = await data.whatsappResponse.download_media(mediaId);
+    if (downloadResult.isRight()) {
+      const imageBuffer = downloadResult.value;
+      
+      // Salvar no disco
+      fs.writeFileSync(`./downloads/${mediaId}.jpg`, imageBuffer);
+      console.log('Imagem salva!');
+      
+      // Ou processar (ex: análise de IA, OCR)
+      const analysis = await analyzeImage(imageBuffer);
+      await data.whatsappResponse.send_text({
+        to: data.sender,
+        message: `Análise da imagem: ${analysis}`
+      });
+    }
+  }
+});
+```
+
+### Pós-condições
+- ✅ Mídia enviada/baixada com sucesso
+- ✅ Media ID retornado para uso posterior
+
+---
+
+## Fluxo 6: Gestão de Tokens
+
+### Objetivo
+Garantir que tokens de acesso estejam sempre válidos através de refresh automático.
+
+### Fluxo Principal
+
+```mermaid
+sequenceDiagram
+    participant App as Aplicação
+    participant WR as WhatsappResponse
+    participant Conn as Connection Manager
+    participant NatyAPI as Naty Meta API
+    participant MetaAPI as Meta OAuth API
+    
+    Note over App,WR: 1. Aplicação Solicita Envio
+    App->>WR: new WhatsappResponse({ companyId, phone_number_id })
+    
+    Note over WR,NatyAPI: 2. Buscar Token Atual
+    WR->>Conn: getConnection(companyId, phoneNumberId)
+    Conn->>NatyAPI: GET /connection
+    NatyAPI-->>Conn: { accessToken: 'token_antigo', appId, appSecret }
+    Conn-->>WR: ConnectionEntity
+    
+    Note over WR,MetaAPI: 3. Refresh Automático
+    WR->>WR: Verifica se token precisa refresh<br/>(executado sempre por segurança)
+    WR->>MetaAPI: POST /oauth/access_token<br/>{<br/>  grant_type: 'fb_exchange_token',<br/>  client_id: appId,<br/>  client_secret: appSecret,<br/>  fb_exchange_token: token_antigo<br/>}
+    
+    alt Token Refreshed com Sucesso
+        MetaAPI-->>WR: {<br/>  access_token: 'token_novo',<br/>  token_type: 'bearer',<br/>  expires_in: 5184000<br/>}
+        
+        Note over WR,NatyAPI: 4. Salvar Novo Token
+        WR->>Conn: updateConnection(id, { accessToken: 'token_novo' })
+        Conn->>NatyAPI: PUT /connection { accessToken: 'token_novo' }
+        NatyAPI-->>Conn: ConnectionEntity atualizada
+        
+        WR->>WR: Usa token_novo para requisição
+    else Token Expirado Definitivamente
+        MetaAPI-->>WR: 401 Unauthorized { error: 'invalid_grant' }
+        WR-->>App: Either.left(Error: 'Token expirado, reautenticação necessária')
+        App->>App: Alertar administrador<br/>Solicitar novo short-lived token da Meta
+    end
+```
+
+### Ciclo de Vida do Token
+
+```mermaid
+stateDiagram-v2
+    [*] --> ShortLived: Meta gera token inicial
+    ShortLived --> LongLived: Exchange via OAuth (1h)
+    LongLived --> Refreshed: Auto-refresh a cada uso
+    Refreshed --> LongLived: Token atualizado (60 dias)
+    LongLived --> Expired: Sem uso por >60 dias
+    Expired --> ShortLived: Reautenticação manual
+    Expired --> [*]
+```
+
+### Código Exemplo - Detecção de Expiração
+
+```typescript
+// O SDK faz refresh automaticamente, mas você pode monitorar
+sdk.on('error', (error) => {
+  if (error.message.includes('Token expirado')) {
+    // Alertar equipe
+    sendAlert({
+      priority: 'HIGH',
+      message: 'Token WhatsApp expirado! Reautenticação necessária.',
+      connectionId: error.context?.connectionId
+    });
+    
+    // Desativar conexão temporariamente
+    disableConnection(error.context?.connectionId);
+  }
+});
+```
+
+---
+
+## Fluxos Alternativos e Tratamento de Erros
+
+### Cenário 1: Número Inválido
+
+**Trigger:** Aplicação tenta enviar para número mal formatado.
+
+```typescript
+// Número sem código do país
+const result = await whatsapp.send_text({
+  to: '11999999999',  // ❌ Falta +55
+  message: 'Teste'
+});
+
+// Meta API retorna erro
+if (result.isLeft()) {
+  console.error(result.value); 
+  // Error: [Meta API] Invalid phone number format
+}
+```
+
+**Solução:** Sempre usar formato E.164 (`+5511999999999`).
+
+---
+
+### Cenário 2: Rate Limit Excedido
+
+**Trigger:** Envio de mensagens acima do limite diário (Tier).
+
+```typescript
+// Meta retorna 429 Too Many Requests
+const result = await whatsapp.send_text({
+  to: '5511999999999',
+  message: 'Mensagem 1001'  // Excedeu limite do Tier 1
+});
+
+if (result.isLeft()) {
+  const error = result.value;
+  if (error.statusCode === 429) {
+    console.log('Rate limit atingido. Aguardar até amanhã.');
+    // Implementar fila com retry após 24h
+  }
+}
+```
+
+---
+
+### Cenário 3: Webhook Timeout
+
+**Trigger:** Processamento de webhook demora mais de 15 segundos.
+
+```typescript
+sdk.on('message', async (data) => {
+  // ❌ Operação demorada (ex: consulta lenta no DB)
+  const result = await slowDatabaseQuery(); // 20 segundos
+  
+  // Meta já desistiu (timeout), mas SDK ainda processa
+  await data.whatsappResponse.send_text({
+    to: data.sender,
+    message: result
+  });
+});
+```
+
+**Solução:** Responder webhook imediatamente (200 OK) e processar assíncrono.
+
+```typescript
+sdk.on('message', async (data) => {
+  // Processar em background
+  processMessageAsync(data).catch(console.error);
+  
+  // Não aguardar processamento completo
+});
+
+async function processMessageAsync(data) {
+  const result = await slowDatabaseQuery();
+  await data.whatsappResponse.send_text({
+    to: data.sender,
+    message: result
+  });
+}
+```
+
+---
+
+### Cenário 4: Mensagem Fora da Janela de 24h
+
+**Trigger:** Enviar mensagem livre após 24h da última interação do cliente.
+
+```typescript
+// Cliente interagiu há 2 dias
+const result = await whatsapp.send_text({
+  to: '5511999999999',
+  message: 'Oi! Tudo bem?'  // ❌ Não é template aprovado
+});
+
+if (result.isLeft()) {
+  console.error(result.value);
+  // Error: [Meta API] Message failed to send because more than 24 hours have passed
+}
+```
+
+**Solução:** Usar template aprovado.
+
+```typescript
+const result = await whatsapp.send_text_template({
+  to: '5511999999999',
+  template: {
+    name: 'follow_up_aprovado',  // Template aprovado pela Meta
+    language: 'pt_BR',
+    components: []
+  }
+});
+```
+
+---
+
+## 🔗 Próximos Passos
+
+Com os fluxos compreendidos, explore:
+
+- **[Integrações](05-integracoes.md)** - Detalhes das APIs externas
+- **[Entidades](06-entidades.md)** - Estrutura de dados
+- **[Guia Prático](07-guia-pratico.md)** - Mais exemplos de código
+
+---
+
+[⬅️ Anterior: Arquitetura](03-arquitetura.md) | [⬆️ Voltar ao Índice](README.md) | [➡️ Próximo: Integrações](05-integracoes.md)