antigravity-skills-reference/skills/whatsapp-cloud-api/references/advanced-features.md

Features Avancados - WhatsApp Cloud API

Guia dos recursos avancados da WhatsApp Business Platform: Flows, Commerce, Channels, Click-to-WhatsApp Ads e Status Tracking.

---

Indice

1. WhatsApp Flows
2. Commerce e Catalogo
3. WhatsApp Channels
4. Click-to-WhatsApp Ads
5. Status Tracking
6. Analytics e Reporting

---

WhatsApp Flows

WhatsApp Flows permite criar formularios interativos multi-tela dentro do WhatsApp. O cliente preenche campos, seleciona opcoes e envia dados sem sair do app.

Quando Usar

• Cadastros e registros
• Agendamentos e reservas
• Pesquisas NPS e feedback
• Selecao de produtos com opcoes
• Formularios de suporte com campos estruturados
• Questionarios de qualificacao de leads

Estrutura JSON de um Flow

Um Flow e composto por screens (telas) com components (campos):

{
  "version": "3.0",
  "screens": [
    {
      "id": "SCREEN_1",
      "title": "Agendamento",
      "data": {},
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextHeading",
            "text": "Agende sua consulta"
          },
          {
            "type": "TextInput",
            "name": "customer_name",
            "label": "Seu nome completo",
            "required": true,
            "input-type": "text"
          },
          {
            "type": "DatePicker",
            "name": "appointment_date",
            "label": "Data desejada",
            "required": true,
            "min-date": "1709251200000",
            "max-date": "1711929600000"
          },
          {
            "type": "Dropdown",
            "name": "service_type",
            "label": "Tipo de servico",
            "required": true,
            "data-source": [
              { "id": "consulta", "title": "Consulta" },
              { "id": "retorno", "title": "Retorno" },
              { "id": "exame", "title": "Exame" }
            ]
          },
          {
            "type": "Footer",
            "label": "Confirmar",
            "on-click-action": {
              "name": "navigate",
              "next": { "type": "screen", "name": "SCREEN_2" },
              "payload": {
                "customer_name": "${form.customer_name}",
                "appointment_date": "${form.appointment_date}",
                "service_type": "${form.service_type}"
              }
            }
          }
        ]
      }
    },
    {
      "id": "SCREEN_2",
      "title": "Confirmacao",
      "terminal": true,
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextHeading",
            "text": "Confirme seus dados"
          },
          {
            "type": "TextBody",
            "text": "Nome: ${data.customer_name}\nData: ${data.appointment_date}\nServico: ${data.service_type}"
          },
          {
            "type": "Footer",
            "label": "Confirmar Agendamento",
            "on-click-action": {
              "name": "complete",
              "payload": {
                "customer_name": "${data.customer_name}",
                "appointment_date": "${data.appointment_date}",
                "service_type": "${data.service_type}"
              }
            }
          }
        ]
      }
    }
  ]
}

Componentes Disponiveis

Componente	Descricao	Campos principais
TextHeading	Titulo de secao	text
TextBody	Texto descritivo	text
TextInput	Campo de texto	name, label, input-type
TextArea	Area de texto multi-linha	name, label
DatePicker	Seletor de data	name, label, min-date, max-date
Dropdown	Lista suspensa	name, label, data-source
RadioButtonsGroup	Botoes de opcao	name, label, data-source
CheckboxGroup	Caixas de selecao	name, label, data-source
OptIn	Checkbox de aceite	name, label
Footer	Botao de acao/navegacao	label, on-click-action

Enviar Flow via API

async function sendFlow(to: string, flowId: string, screenId: string): Promise<void> {
  await sendMessage({
    messaging_product: 'whatsapp',
    to,
    type: 'interactive',
    interactive: {
      type: 'flow',
      header: { type: 'text', text: 'Agendar Consulta' },
      body: { text: 'Preencha o formulário abaixo para agendar.' },
      footer: { text: 'Seus dados são protegidos' },
      action: {
        name: 'flow',
        parameters: {
          flow_message_version: '3',
          flow_id: flowId,
          flow_cta: 'Agendar',
          flow_action: 'navigate',
          flow_action_payload: {
            screen: screenId,
            data: {}
          }
        }
      }
    }
  });
}

Receber Resposta do Flow

function handleFlowResponse(message: IncomingMessage): Record<string, any> | null {
  if (message.interactive?.type === 'nfm_reply') {
    return JSON.parse(message.interactive.nfm_reply.response_json);
    // Ex: { customer_name: "João", appointment_date: "2026-03-01", service_type: "consulta" }
  }
  return null;
}

Criar Flows

Flows podem ser criados de duas formas:

1. Visual Builder - No WhatsApp Manager, arrastar e soltar componentes
2. JSON Editor - Editar diretamente o JSON para controle total

---

Commerce e Catalogo

Configurar Catalogo

O catalogo WhatsApp suporta ate 500 produtos vinculados ao seu perfil de negocio.

Configuracao:

1. Abra o WhatsApp Manager
2. Va para Account Tools → Catalog
3. Adicione produtos com: nome, descricao, preco, imagem, URL

Enviar Mensagem de Produto Unico

async function sendSingleProduct(to: string, catalogId: string, productId: string): Promise<void> {
  await sendMessage({
    messaging_product: 'whatsapp',
    to,
    type: 'interactive',
    interactive: {
      type: 'product',
      body: { text: 'Confira este produto!' },
      footer: { text: 'Responda para comprar' },
      action: {
        catalog_id: catalogId,
        product_retailer_id: productId
      }
    }
  });
}

Enviar Mensagem Multi-Produto

async function sendMultiProduct(
  to: string,
  catalogId: string,
  sections: Array<{ title: string; product_items: Array<{ product_retailer_id: string }> }>
): Promise<void> {
  await sendMessage({
    messaging_product: 'whatsapp',
    to,
    type: 'interactive',
    interactive: {
      type: 'product_list',
      header: { type: 'text', text: 'Nossos Produtos' },
      body: { text: 'Selecione os produtos que deseja:' },
      footer: { text: 'Adicione ao carrinho' },
      action: {
        catalog_id: catalogId,
        sections
      }
    }
  });
}

// Uso:
await sendMultiProduct('5511999999999', 'CATALOG_ID', [
  {
    title: 'Eletronicos',
    product_items: [
      { product_retailer_id: 'SKU_001' },
      { product_retailer_id: 'SKU_002' }
    ]
  },
  {
    title: 'Acessorios',
    product_items: [
      { product_retailer_id: 'SKU_003' },
      { product_retailer_id: 'SKU_004' }
    ]
  }
]);

Checkout In-App

Quando o cliente seleciona produtos e faz checkout, voce recebe via webhook:

{
  "type": "order",
  "order": {
    "catalog_id": "CATALOG_ID",
    "product_items": [
      {
        "product_retailer_id": "SKU_001",
        "quantity": 2,
        "item_price": 99.90,
        "currency": "BRL"
      }
    ],
    "text": "Quero esses produtos"
  }
}

Sync com Inventario

Para manter o catalogo atualizado:

async def sync_inventory(catalog_id: str, products: list[dict]) -> None:
    """Sincroniza inventario com o catalogo WhatsApp via Commerce Manager API."""
    for product in products:
        await update_product(
            catalog_id=catalog_id,
            product_id=product["sku"],
            data={
                "availability": "in stock" if product["stock"] > 0 else "out of stock",
                "price": product["price"] * 100,  # Em centavos
                "currency": "BRL"
            }
        )

---

WhatsApp Channels

WhatsApp Channels e um recurso de broadcasting unidirecional. Voce envia atualizacoes para subscribers ilimitados na aba "Atualizacoes" do WhatsApp.

Caracteristicas

• Unidirecional: Apenas o admin envia, subscribers recebem
• Privacidade do admin: Followers nao veem seu numero pessoal
• Privacidade do subscriber: Admin nao ve numeros dos followers (a menos que salvos como contatos)
• Conteudo: Texto, imagens, videos, stickers, polls

Analytics Disponiveis (30 dias)

Metrica	Descricao
Crescimento	Novos followers vs unfollows
Alcance	Quantos viram suas mensagens
Engajamento	Reacoes com emoji
Resultados de polls	Votos em enquetes

Melhores Praticas

• Publique conteudo relevante e nao promocional em excesso
• Use polls para engajamento
• Frequencia ideal: 2-5 postagens por semana
• Conteudo exclusivo incentiva follows

---

Click-to-WhatsApp Ads

Anuncios no Facebook e Instagram com botao que abre conversa no WhatsApp.

Setup no Meta Ads Manager

1. Criar campanha com objetivo "Messaging", "Leads" ou "Sales"
2. Selecionar "Click to WhatsApp" como destino
3. Vincular conta WhatsApp Business
4. Configurar mensagem pre-preenchida (greeting + pre-filled message)

Pre-filled Messages

Configure a mensagem que o cliente ve quando abre o chat:

Greeting: "Olá! Obrigado por clicar no nosso anúncio."
Pre-filled: "Oi, vi o anúncio sobre [produto] e gostaria de saber mais!"

Integracao no Webhook

Quando um cliente vem de um anuncio, o webhook inclui dados de referral:

{
  "messages": [{
    "from": "5511999999999",
    "type": "text",
    "text": { "body": "Oi, vi o anúncio..." },
    "referral": {
      "source_url": "https://fb.me/...",
      "source_type": "ad",
      "source_id": "AD_ID",
      "headline": "Titulo do Anuncio",
      "body": "Texto do anuncio",
      "ctwa_clid": "click_id_para_tracking"
    }
  }]
}

Tracking de Conversao

function handleAdReferral(message: IncomingMessage): void {
  if (message.referral) {
    const adData = {
      adId: message.referral.source_id,
      clickId: message.referral.ctwa_clid,
      headline: message.referral.headline,
      customerPhone: message.from,
      timestamp: new Date()
    };

    // Registrar lead vindo do anuncio
    trackConversion(adData);

    // Personalizar atendimento com contexto do anuncio
    customizeGreeting(message.from, adData.headline);
  }
}

Metricas

• Taxa de abertura: ~99% (mensagens WhatsApp)
• Reducao de custo: Ate 32% menor custo por lead vs formularios
• Aumento: Ate 46% mais mensagens de clientes

---

Status Tracking

Ciclo de Vida da Mensagem

Enviada (sent) → Entregue ao servidor (delivered) → Entregue ao dispositivo (delivered) → Lida (read)

Status via Webhook

{
  "statuses": [
    {
      "id": "wamid.HBgNNTUxMTk5...",
      "status": "delivered",
      "timestamp": "1709251200",
      "recipient_id": "5511999999999",
      "conversation": {
        "id": "CONVERSATION_ID",
        "origin": { "type": "business_initiated" },
        "expiration_timestamp": "1709337600"
      },
      "pricing": {
        "billable": true,
        "pricing_model": "CBP",
        "category": "utility"
      }
    }
  ]
}

Status Possiveis

Status	Descricao	Confiabilidade
sent	Mensagem enviada para servidores Meta	Alta
delivered	Entregue ao dispositivo do cliente	Alta
read	Cliente leu a mensagem (blue check)	Media (pode ser off)
failed	Falha na entrega	Alta

Limitacao Importante

O status read depende de o usuario ter read receipts ativados nas configuracoes do WhatsApp. Muitos usuarios desativam. Use delivered como confirmacao confiavel de entrega.

Implementacao de Tracking

interface MessageStatus {
  messageId: string;
  to: string;
  sentAt: Date;
  deliveredAt?: Date;
  readAt?: Date;
  failedAt?: Date;
  failureReason?: string;
}

async function processStatusUpdate(status: WebhookStatus): Promise<void> {
  const update: Partial<MessageStatus> = {};

  switch (status.status) {
    case 'sent':
      update.sentAt = new Date(parseInt(status.timestamp) * 1000);
      break;
    case 'delivered':
      update.deliveredAt = new Date(parseInt(status.timestamp) * 1000);
      break;
    case 'read':
      update.readAt = new Date(parseInt(status.timestamp) * 1000);
      break;
    case 'failed':
      update.failedAt = new Date(parseInt(status.timestamp) * 1000);
      update.failureReason = status.errors?.[0]?.message;
      break;
  }

  await db.messageStatuses.updateOne(
    { messageId: status.id },
    { $set: update }
  );
}

---

Analytics e Reporting

Metricas Essenciais para Atendimento

Metrica	Como Calcular	Meta Ideal
Tempo Primeira Resposta (FRT)	Timestamp resposta - timestamp mensagem	< 5 minutos
Tempo Medio de Resolucao	Timestamp fechamento - timestamp inicio	< 30 minutos
Taxa de Resolucao no Bot	Resolvidos pelo bot / total	> 60%
Taxa de Escalacao	Escalados para humano / total	< 40%
CSAT (Satisfacao)	Pesquisa NPS pos-atendimento	> 4.0 / 5.0
Taxa de Entrega	Delivered / sent	> 95%
Taxa de Leitura	Read / delivered	> 70%
Taxa de Opt-out	Optouts / total da base	< 2% por campanha

Pesquisa NPS via WhatsApp

async function sendNPSSurvey(to: string): Promise<void> {
  await sendMessage({
    messaging_product: 'whatsapp',
    to,
    type: 'interactive',
    interactive: {
      type: 'button',
      body: {
        text: 'De 1 a 5, como voce avalia nosso atendimento?\n\n' +
              '1 = Muito ruim\n5 = Excelente'
      },
      action: {
        buttons: [
          { type: 'reply', reply: { id: 'nps_1_2', title: '1-2 Ruim' } },
          { type: 'reply', reply: { id: 'nps_3', title: '3 Regular' } },
          { type: 'reply', reply: { id: 'nps_4_5', title: '4-5 Bom' } }
        ]
      }
    }
  });
}

Dashboard de Analytics

Para analytics avancados, considere integrar com:

• Infobip - Dashboard completo com APIs de reporting
• Trengo - CSAT tracking, response times, trending topics
• Wassenger - Comparacao de agentes, exportacao CSV/JSON/PDF
• Solucao propria - MongoDB/PostgreSQL + Grafana/Metabase