WPP Business

O WPP Business conecta o seu produto ao WhatsApp pelo caminho oficial da Meta — a WhatsApp Business Platform, também chamada de Cloud API. Ele guarda as credenciais de cada empresa cliente, envia mensagem e template, recebe o que o cliente responde, e transforma tudo isso em evento que os seus sistemas conseguem consumir.

Na prática: uma financeira precisa avisar 4 mil clientes de que o boleto vence amanhã. Ela cria um template, espera a Meta aprovar, dispara uma campanha filtrada por etiqueta e acompanha quantas mensagens saíram, chegaram e foram lidas — sem escrever uma linha de integração com a Graph API e sem contratar uma plataforma de WhatsApp em separado.

Está em produção desde março de 2026. O primeiro webhook real foi configurado e validado em produção em 1º de abril de 2026 (tutorial de setup). É o maior building block do catálogo: 151 endpoints, 27 modelos de dados e 86 arquivos de teste.

O caminho completo, do seu código ao celular do cliente e de volta:

flowchart LR
  App["Sua aplicação"] -->|"Bearer JWT do IAM"| BB["WPP Business"]
  BB -->|"Graph API v25.0"| Meta["Meta Cloud API"]
  Meta -->|"mensagem"| Cel["Celular do cliente"]
  Cel -->|"resposta"| Meta
  Meta -->|"webhook assinado com HMAC"| BB
  BB -->|"evento wpp-biz.*"| WE["Webhooks Engine"]
  WE -->|"entrega com retentativa"| App

O cenário. No Brasil, o WhatsApp é onde a conversa com o cliente acontece. E-mail marketing tem taxa de abertura baixa, SMS é caro e desconfiado, e ligação quase ninguém atende. Toda empresa que fala com pessoa física acaba no WhatsApp — e, se a empresa é regulada, precisa que isso aconteça no canal oficial, com registro e não com o celular do vendedor.

O que trava hoje.

• A Cloud API não é uma API simples. Para enviar a primeira mensagem você precisa de um Meta App, um App Secret, uma WABA verificada, um número registrado com PIN de dois fatores, um template aprovado e um webhook assinado com HMAC. Nada disso é opcional, e a documentação da Meta trata cada peça em uma página diferente.
• Multi-tenant não existe no modelo da Meta. Cada empresa cliente tem a própria WABA e o próprio token. Se você atende trinta clientes, são trinta conjuntos de credenciais para guardar, criptografar e rotacionar — e um único webhook da Meta chegando para todos, que você precisa rotear.
• A janela de 24 horas quebra a intuição do time. Fora dela, só template aprovado sai. O time de produto descobre isso em produção, quando a mensagem de resposta simplesmente não chega, e ninguém entende por quê.
• Você reimplementa a mesma infraestrutura de eventos. Verificação de assinatura, log do payload cru, retentativa com backoff, filtro por tipo de mensagem, encaminhamento para o sistema certo. Isso é um serviço inteiro, e não é o seu produto.
• A plataforma de WhatsApp vira mais um cadastro de cliente. Contratar um fornecedor separado significa manter a base de contatos em dois lugares e explicar, na auditoria, por que o dado do cliente também está lá.

As seis peças que a Meta exige antes da primeira mensagem

Nenhuma delas é opcional, e cada uma vive numa página diferente da documentação da Meta:

flowchart LR
  A["Meta App"] --> B["App Secret"]
  B --> C["WABA verificada"]
  C --> D["Número registrado<br/>com PIN de dois fatores"]
  D --> E["Template aprovado"]
  E --> F["Webhook assinado<br/>com HMAC"]
  F --> G["Primeira mensagem<br/>entregue"]

O custo de não resolver

Os números do canal no Brasil não deixam margem para dúvida.

E o atalho não oficial custa o canal inteiro

Ficar fora do canal, portanto, não é economia. E a alternativa não oficial — automatizar o WhatsApp Web com bibliotecas como Baileys ou whatsapp-web.js — viola os Termos de Serviço do WhatsApp Business, que proíbem literalmente "develop or use any applications that interact with our Business Services without our prior written consent" e reservam à Meta o direito de encerrar a conta, com a agravante de que, depois disso, "Company will not create another WhatsApp business account without our express written permission" (WhatsApp Business Terms of Service, consultado em 2026-08-16). Para uma operação de cobrança ou de atendimento, isso é perder o canal em um dia útil, sem recurso.

O onboarding cabe em duas chamadas. POST /apps registra o Meta App uma vez por organização. POST /devices/standalone recebe só o access token e o phoneNumberId e descobre sozinho a WABA, o negócio dono e o número — e ainda configura o webhook na Meta em seguida.

sequenceDiagram
  autonumber
  participant App as Sua aplicação
  participant BB as WPP Business
  participant Meta as Meta Graph API
  App->>BB: POST /apps (appId, appSecret)
  BB-->>App: 201 hasAppSecret true
  App->>BB: POST /devices/standalone (token, phoneNumberId, wabaId)
  BB->>Meta: debug_token — de qual app veio este token?
  BB->>Meta: consulta WABA, negócio dono e número
  BB->>Meta: assina o app e a WABA no webhook
  BB-->>App: 201 bbDeviceId, accountId, displayNumber

A janela de 24h deixa de ser folclore. O BB calcula a janela a partir da última mensagem recebida de verdade e devolve isOpen, expiresAt e remainingMinutes. O seu produto decide entre texto livre e template com dado, não com palpite.

O erro da Meta chega traduzido. META_TOKEN_EXPIRED, META_TOKEN_REVOKED, META_INSUFFICIENT_SCOPE e META_RATE_LIMIT vêm em details.code, junto do fbtrace_id. O painel decide o que mostrar ao usuário sem fazer parse de mensagem em inglês.

O evento sai pela mesma porta dos outros building blocks. Cada mensagem recebida vira um evento granular (wpp-biz.message.received.text, .image, .interactive...) que o Webhooks Engine entrega com retentativa. Quem já consome eventos do Commerce ou do Payments consome os do WhatsApp do mesmo jeito.

flowchart LR
  Meta["Meta Cloud API"] -->|"webhook único"| BB["WPP Business"]
  BB -->|"wpp-biz.message.received.text"| D1["Dispatcher"]
  BB -->|"wpp-biz.message.received.interactive"| D1
  D1 -->|"filtro, HMAC, backoff, log"| WE["Webhooks Engine"]
  WE --> S1["Sua esteira"]
  WE --> S2["Decision Platform"]
  WE --> S3["AI Engine"]

O atendimento humano tem lugar. Agentes, atribuição de conversa, transferência, notas internas e status de resolução são parte do BB — não um produto separado que você contrata por assento.

Panorama

Só existe um caminho oficial para o WhatsApp corporativo, e ele é da Meta. Desde 1º de julho de 2025 a Meta cobra por mensagem de template entregue, e não mais por conversa de 24 horas (WhatsApp Business Platform Pricing, consultado em 2026-08-16). A diferença entre os fornecedores está em quanto cobram por cima disso e em quanto de plataforma entregam junto.

De um lado ficam os provedores de acesso, com camada fina: a Cloud API direta e a 360dialog, que declara literalmente "no markups on Meta fees" e cobra €49 a €249 por mês por número (360dialog, consultado em 2026-08-16). No meio fica a Twilio, que publica tabela completa: US$ 0,005 por mensagem, na entrada e na saída, somados à tarifa da Meta (Twilio, consultado em 2026-08-16). Do outro lado ficam as plataformas completas — Take Blip, Zenvia, Infobip, Gupshup, Sinch — que somam construtor de fluxo, atendimento humano e campanha.

flowchart TD
  M["Tarifa da Meta<br/>por mensagem de template entregue"]
  M --> A["Provedores de acesso — camada fina<br/>Cloud API direta · 360dialog"]
  M --> B["Intermediário com tabela pública<br/>Twilio"]
  M --> C["Plataformas completas<br/>Take Blip · Zenvia · Infobip · Gupshup · Sinch"]
  M --> D["Catalisa WPP Business<br/>peça de WhatsApp de uma plataforma já contratada"]
  A --> A1["Sem margem por mensagem<br/>você constrói tenancy, webhook e relay"]
  B --> B1["US$ 0,005 por mensagem<br/>na entrada e na saída"]
  C --> C1["Construtor de fluxo, atendimento e campanha<br/>cobrança por conversa e por assento"]
  D --> D1["Sem segundo cadastro do seu cliente<br/>mesmo token, mesmo tenant"]

Duas observações que mudam a leitura do mercado, e que raramente aparecem em comparativo:

• Metade dos grandes não publica preço de WhatsApp. Infobip, Sinch e Gupshup remetem a contato comercial; a página de preços da Gupshup responde 404 (verificado em 2026-08-16). Não é falha de busca, é o modelo comercial: você paga conforme o seu poder de barganha.
• Os fornecedores brasileiros ainda cobram por conversa, não por mensagem. A Zenvia publica R$ 0,47 a R$ 0,55 por mensagem de empresa, com pacote mínimo de R$ 100 por mês e setup de R$ 649 (Zenvia); a Take Blip publica R$ 1,25 a R$ 1,40 por conversa adicional e R$ 100 a R$ 150 por agente por mês, sem publicar a mensalidade base (Blip) — ambos consultados em 2026-08-16. Como a Meta migrou para cobrança por mensagem, esses modelos não são diretamente comparáveis com a tarifa de origem.

O WPP Business não tenta ser a melhor plataforma de WhatsApp do mercado. Ele é a peça de WhatsApp de uma plataforma que o cliente já contratou por outro motivo — e que por isso não cobra o cadastro do cliente duas vezes.

Tabela comparativa

Valores públicos consultados em 2026-08-16 nas páginas de preço dos próprios fornecedores. Preço muda com frequência e varia por país, volume e negociação — confira na data da sua análise. A tarifa da Meta está em WhatsApp Business Platform Pricing.

Nossos diferenciais

1. A organização do IAM é a unidade de isolamento, não a instalação. Cada empresa cliente tem WppBizApp e WppBizAccount próprios, com token e App Secret cifrados, e o webhook único da Meta é roteado pelo wabaId do payload até a conta certa. Um concorrente só chega nisso se você construir a camada de tenancy por cima dele — que é exatamente o trabalho que ele te vendeu para não fazer.
2. O WhatsApp entra na mesma malha de eventos do resto do catálogo. Um dispatcher do WPP Business vira uma inscrição no Webhooks Engine, com filtro JSONPath, HMAC, backoff e log de entrega reaproveitáveis. Quem já integrou o Commerce integra o WhatsApp com o mesmo código de recepção.
3. O erro da Meta chega classificado. Token expirado, token revogado, escopo insuficiente e limite de taxa vêm em details.code com o fbtrace_id junto. Isso parece detalhe até a primeira madrugada em que um token de system user expira e o time precisa descobrir se é permissão, credencial ou throttle.
4. Não há um segundo cadastro do seu cliente em um fornecedor de mensageria. Contato, mensagem e conversa ficam no mesmo banco, no mesmo tenant, sob a mesma política de retenção do resto da plataforma.

Quando escolher o concorrente

O atalho, antes da prosa — se o seu requisito principal está nesta tabela, o fornecedor da direita entrega melhor que nós hoje:

Se o seu problema é construir jornada conversacional complexa com pessoa não técnica desenhando o fluxo, a Take Blip e a Twilio Studio entregam isso hoje e o WPP Business não entrega — nosso construtor de fluxo é o WhatsApp Flows da própria Meta, editado por JSON, e não temos editor visual. Se você precisa de bot com IA respondendo em linguagem natural de caixa, aqui a automação casa palavra-chave e ponto; a Gupshup e a Blip têm produto pronto, e a própria Meta agora vende os Business Agents com cobrança por token. Se você precisa de SMS, voz e WhatsApp no mesmo contrato e no mesmo SLA, a Twilio, a Infobip e a Sinch são a escolha óbvia, e nós só temos e-mail em building block separado.

Se o seu volume é altíssimo e você já tem engenharia para operar a integração, a Cloud API direta ou a 360dialog vão custar menos — não existe intermediário mais barato que a ausência de intermediário, e o modelo de €49 por número da 360dialog tem margem marginal que tende a zero conforme o volume cresce. Se você precisa de entrada self-serve barata para uma operação pequena no Brasil, o Blip Go a R$ 299 por mês e o plano de entrada da Zenvia a R$ 100 por mês resolvem sem ciclo de vendas.

E se a sua operação depende de catálogo de produtos sincronizado com o Commerce Manager ou de pagamento processado dentro do WhatsApp, leia a §15 antes de decidir: essas duas frentes existem no modelo de dados mas não estão completas aqui.

Uma nota de diligência sobre a saúde do fornecedor

Uma nota de diligência que vale para os dois lados: ao escolher fornecedor de canal, olhe a saúde dele. A Zenvia saiu do Nasdaq em março de 2026, em deslistagem voluntária que ela mesma justificou pela ausência de mercado ativo de negociação das ações (PR Newswire, consultado em 2026-08-16), e com isso deixou de publicar demonstrações financeiras. A Bird cortou cerca de 20% do quadro global em maio de 2026 e declarou foco no mercado americano. Isso não os desqualifica — mas se o WhatsApp é canal crítico da sua operação, a continuidade do fornecedor entra na conta junto com o preço.

Unidade de cobrança

A precificação Catalisa do WPP Business está em definição. O que já é certo é a estrutura: a tarifa da Meta é repassada, porque quem cobra por mensagem é a Meta e não a Catalisa.

Como a Meta cobra hoje. Desde 1º de julho de 2025, o modelo é por mensagem de template entregue — a documentação é literal: "You are only charged when a template message is delivered". Conversas de serviço iniciadas pelo cliente são gratuitas desde 1º de novembro de 2024, e mensagens que não são template são gratuitas desde que enviadas dentro de uma janela de atendimento aberta (WhatsApp Business Platform Pricing, consultado em 2026-08-16). O preço varia por categoria e por país do destinatário.

Estimativa, não tabela oficial. A Meta publica a tabela do Brasil em arquivo dentro do WhatsApp Manager, não em página aberta. Triangulando fornecedores públicos em 2026-08-16, o MARKETING no Brasil fica na ordem de US$ 0,0625 por mensagem e o UTILITY, na ordem de US$ 0,0068 — uma diferença de cerca de nove vezes. Trate como ordem de grandeza para orientar conversa e baixe a tabela oficial da sua conta antes de fechar qualquer número em proposta. O valor de AUTHENTICATION diverge entre as fontes e não está incluído aqui de propósito.

Duas mudanças da Meta com data marcada

A régua de datas da cobrança da Meta, do que já valeu ao que ainda vai valer:

timeline
  title Linha do tempo da cobrança da Meta
  2024-11-01 : Conversas de serviço iniciadas pelo cliente ficam gratuitas
  2025-07-01 : Cobrança passa a ser por mensagem de template entregue, e não mais por conversa de 24 horas
  2026-07-01 : Começa a localização do faturamento em reais
  2026-10-01 : Meta passa a cobrar também as respostas enviadas dentro da janela de 24 horas
  2027-06-30 : Prazo final para migrar a WABA para faturamento em reais

As duas mudanças com data marcada que precisam entrar no seu planejamento, em detalhe:

A primeira delas reprecifica o custo de operação de atendimento, que hoje é praticamente zero — reportagem sobre o mercado brasileiro cita um cliente cuja conta passaria de perto de zero para a ordem de US$ 100 mil por mês (Mobile Time, consultado em 2026-08-16). A segunda favorece quem já fatura em reais: contratos em euro ou dólar com provedor estrangeiro entram em conflito com esse relógio.

O que dispara custo

O detalhe que mais destrói orçamento

A categoria do template não é escolha sua. Desde 9 de abril de 2025, quando você marca UTILITY e a Meta discorda, ela aprova o template como MARKETING em vez de rejeitar (Template Categorization, consultado em 2026-08-16). Com a diferença de cerca de nove vezes entre as duas categorias no Brasil, um template mal escrito multiplica o custo da régua inteira sem gerar um único erro na sua aplicação. Por isso GET /wpp-business/api/v1/analytics/conversations/stats agrupa por category e por originType: sem esse recorte, a fatura da Meta é um número só.

flowchart TD
  A["Você cria o template marcando UTILITY"] --> B{"A Meta revisa a categoria"}
  B -->|"concorda"| C["Aprovado como UTILITY<br/>ordem de US$ 0,0068 por mensagem no Brasil"]
  B -->|"discorda"| D["Aprovado como MARKETING<br/>ordem de US$ 0,0625 por mensagem no Brasil"]
  D --> E["Nenhum erro aparece na sua aplicação"]
  E --> F["A régua inteira custa cerca de nove vezes mais, em silêncio"]
  C --> G["GET /analytics/conversations/stats<br/>agrupa por category e originType"]
  F --> G
  G --> H["A recategorização vira problema detectável"]

Comparação de custo

Cenário nomeado: operação brasileira com 200 mil mensagens de template por mês (150 mil UTILITY, 50 mil MARKETING), 6 números conectados e 12 atendentes.

As ordens de grandeza acima são cálculo nosso sobre os preços públicos consultados em 2026-08-16, não proposta de nenhum fornecedor. As semanas de engenharia são estimativa interna da Catalisa, não medição. Infobip, Sinch e Gupshup ficaram fora da tabela porque não publicam preço de WhatsApp.

ROI

O retorno não está na linha de licença — a Cloud API direta será sempre a opção de menor tarifa, e a 360dialog fica muito perto disso. Está em duas coisas.

A primeira é a engenharia que não é gasta: uma integração própria que atenda mais de um cliente precisa, no mínimo, dos itens abaixo — cada um é código que alguém escreve, testa e mantém por anos.

A segunda é o custo evitado que ninguém orça: com o MARKETING custando cerca de nove vezes o UTILITY no Brasil, e com a Meta recategorizando template sem rejeitá-lo, uma régua de 150 mil mensagens transacionais mal categorizada custa ordens de grandeza a mais em silêncio. Ver a categoria efetiva por conversa é o que transforma isso em problema detectável.

As cinco camadas

Duas portas de entrada, uma pilha só. O cliente HTTP chega autenticado; a Meta chega sem token e se autentica por assinatura.

flowchart TD
  App["Hono app — basePath /wpp-business<br/>20 routers mais /health"]
  Cli["Cliente HTTP<br/>Bearer JWT ou X-API-Key"] --> App
  MetaIn["Meta — webhook sem auth"] -->|"x-hub-signature-256"| App
  App -->|"Zod parse, depois ResultAsync de T ou AppError"| Svc["services/ — 18 serviços<br/>AccountService · MessageService · WebhookService · TemplateService …"]
  Svc --> Repo["repositories/ — 24 repositórios<br/>acesso por Prisma"]
  Svc --> Prov["providers/cloud-api<br/>CloudApiClient"]
  Repo --> PG["PostgreSQL — schema wpp_business<br/>27 modelos<br/>accessToken e appSecret cifrados em AES-256-GCM"]
  Prov --> Graph["graph.facebook.com/v25.0<br/>retry ×3, HMAC timing-safe<br/>erro da Meta vira details.code"]

Os 20 grupos de rota montados no app

O caminho de uma mensagem recebida — o fluxo mais importante do BB

Primeiro a autenticação, que é onde a configuração costuma falhar:

sequenceDiagram
  autonumber
  participant Meta as Meta
  participant WR as webhook.router
  participant AR as AccountRepository
  participant WS as WebhookService
  Meta->>WR: POST /wpp-business/api/v1/webhook
  WR->>WR: lê entry[0].id e obtém o wabaId
  WR->>AR: findByWabaIdGlobal(wabaId)
  AR-->>WR: conta da organização dona daquela WABA
  WR->>WR: decifra o appSecret da conta (WppBizApp ou campo legado)
  WR->>WR: HMAC-SHA256 do corpo cru contra x-hub-signature-256
  alt assinatura inválida
    WR-->>Meta: 401 — é o único 401 que a Meta recebe
  else assinatura válida
    WR->>WS: processWebhook
    WS-->>Meta: 200, mesmo quando o processamento falha
  end

Depois o processamento, que se abre em três frentes a partir do mesmo payload:

flowchart TD
  WS["WebhookService.processWebhook"] --> L["Grava WppBizWebhookLog<br/>payload, headers, IP, tamanho, tempo"]
  WS --> M["Campo messages"]
  WS --> O["Outros 9 campos<br/>status de template, qualidade,<br/>flows, alertas, segurança"]
  M --> M1["get-or-create WppBizContact"]
  M1 --> M2["Grava WppBizMessage"]
  M2 --> M3["Publica wpp-biz.message.received<br/>mais o evento granular por tipo"]
  M3 --> M4["DispatcherService.evaluateDispatchers"]
  M3 --> M5["AutomationService.processMessage"]
  M --> M6["Campo statuses — atualiza o status da mensagem<br/>e a WppBizConversation"]
  O --> O1["Publica o evento e pronto<br/>não persiste — ver §15"]

Decisões não óbvias

• O webhook responde 200 mesmo quando o processamento falha. A Meta reenvia payload em caso de erro, e reenvio em massa durante uma falha de banco transforma incidente em avalanche. Só assinatura inválida devolve 401. O erro real fica no WppBizWebhookLog, com o payload cru guardado para reprocessar em POST /webhook/logs/:id/replay.
• O appSecret é resolvido por conta, não por variável de ambiente. Cada tenant tem o próprio Meta App. Um segredo global tornaria impossível hospedar duas empresas com apps diferentes — e é justamente esse o caso de uso.
• A criptografia é aplicada na borda do repositório, não no serviço. AccountRepository cifra na escrita e decifra na leitura, então mais de trinta pontos de consumo continuam vendo o token em texto puro sem saber que ele está cifrado no banco. decryptSecretIfEncrypted deixa linhas legadas em texto puro passarem, o que permitiu ligar a criptografia antes de rodar a migração dos dados.
• A verificação HMAC usa timingSafeEqual. Comparar assinatura com === vaza informação por tempo de resposta. É uma linha de código e elimina a classe inteira do problema.
• 429 da Meta não é retentado. O cliente tenta de novo até três vezes com backoff exponencial em erro transitório, mas limite de taxa é explicitamente excluído: insistir estende a janela de throttle em vez de encurtá-la. O erro sobe como META_RATE_LIMIT para o chamador decidir.
• Templates têm duas portas propositalmente. /api/v1/templates/* opera o cache local (WppBizTemplate), útil para listar rápido e para amarrar campanha. /api/v1/accounts/:id/templates/* fala direto com a Meta, que é a fonte de verdade sobre aprovação. Misturar as duas produziria um cache que mente sobre o status de aprovação.
• A versão da Graph API é fixa no código (v25.0), não configurável por ambiente. Subir de versão é mudança de código com teste, não flag — a Meta muda contrato entre versões, e a v21.0 chegou a parar de entregar texto livre.

Monolito vs. standalone

Em monolito, o app é montado com os demais e resolvido pelo container TypeDI. Em standalone — o modo usado em produção — sobe na porta 3025 com prefixo /wpp-business. A diferença que importa: em standalone o WPP_BUSINESS_WEBHOOK_BASE_URL precisa apontar para a URL pública do serviço, porque é ela que o BB registra na Meta como callback.

Glossário

Modelo de dados

Schema wpp_business no PostgreSQL, 27 modelos. Antes da tabela, os três blocos de relacionamento — credencial, conversa e atendimento.

Bloco 1 — credencial e canal. É por aqui que o tenant entra: a organização do IAM é dona do Meta App, o app é dono das WABAs, e a WABA é dona dos números.

erDiagram
  Organization ||--o{ WppBizApp : "registra"
  Organization ||--o{ WppBizAccount : "possui"
  WppBizApp ||--o{ WppBizAccount : "assina o webhook de"
  WppBizAccount ||--o{ WppBizPhoneNumber : "conecta"
  WppBizAccount ||--o{ WppBizWebhookLog : "recebe eventos em"
  WppBizAccount ||--o{ WppBizFlow : "publica"
  WppBizAccount ||--o{ WppBizPaymentConfig : "configura"
  WppBizPhoneNumber ||--o{ WppBizDispatcher : "filtra eventos de"
  WppBizPhoneNumber ||--o{ WppBizAutomation : "responde por"
  WppBizPhoneNumber ||--o{ WppBizShortLink : "aponta para"

Bloco 2 — conversa. O número e o contato se encontram na mensagem; template e campanha alimentam o envio em massa.

erDiagram
  WppBizPhoneNumber ||--o{ WppBizMessage : "envia e recebe"
  WppBizContact ||--o{ WppBizMessage : "conversa em"
  WppBizPhoneNumber ||--o{ WppBizConversation : "fatura em"
  WppBizContact ||--o{ WppBizContactTagAssignment : "recebe"
  WppBizContactTag ||--o{ WppBizContactTagAssignment : "etiqueta"
  WppBizAccount ||--o{ WppBizTemplate : "aprova na Meta"
  WppBizTemplate ||--o{ WppBizCampaign : "instancia"
  WppBizPhoneNumber ||--o{ WppBizCampaign : "dispara por"
  WppBizCampaign ||--o{ WppBizCampaignRecipient : "resolve"
  WppBizContact ||--o{ WppBizCampaignRecipient : "é alvo em"
  WppBizCampaignRecipient ||--o{ WppBizMessage : "gera"

Bloco 3 — atendimento e comércio. Agente, atribuição e o par pedido-cobrança, que hoje ainda depende do que está na §15.

erDiagram
  WppBizAgent ||--o{ WppBizConversationAssignment : "atende"
  WppBizContact ||--o{ WppBizConversationAssignment : "é atendido em"
  WppBizPhoneNumber ||--o{ WppBizConversationAssignment : "recebe em"
  WppBizConversationAssignment ||--o{ WppBizAgentNote : "acumula"
  WppBizConversationAssignment ||--o{ WppBizConversationTransfer : "registra"
  WppBizCatalog ||--o{ WppBizProduct : "lista"
  WppBizProduct ||--o{ WppBizOrderItem : "aparece em"
  WppBizOrder ||--o{ WppBizOrderItem : "contém"
  WppBizContact ||--o{ WppBizOrder : "faz"
  WppBizPhoneNumber ||--o{ WppBizOrder : "recebe"
  WppBizOrder ||--o{ WppBizPayment : "cobra por"
  WppBizPhoneNumber ||--o{ WppBizPayment : "envia"

Enumerações

Máquinas de estado

Seis estados que mudam sozinhos e um que o seu código muda. Cada diagrama abaixo foi conferido contra o serviço que executa a transição — o que não está desenhado, o código não faz.

A janela de 24 horas — a máquina de estado que mais gera bug de integração

stateDiagram-v2
  direction LR
  state "Janela fechada" as Fechada
  state "Janela aberta" as Aberta
  [*] --> Fechada: contato nunca escreveu
  Fechada --> Aberta: contato responde (mensagem INBOUND)
  Aberta --> Fechada: 24h sem nenhuma mensagem INBOUND
  note right of Fechada
    Só sai POST /messages/send-template
    e POST /messages/send-otp
  end note
  note right of Aberta
    Sai POST /messages/send,
    /send-interactive e /send-template
  end note

Consulte antes de decidir entre texto livre e template:

GET /wpp-business/api/v1/contacts/:id/conversation-window?phoneNumberId=<uuid>
→ { isOpen, expiresAt, remainingMinutes, lastInboundAt }

GET /wpp-business/api/v1/contacts/:id/conversation-window?phoneNumberId=<uuid>
→ { isOpen, expiresAt, remainingMinutes, lastInboundAt }

A janela é calculada a partir da última mensagem INBOUND daquele contato naquele número. Enviar texto livre com a janela fechada devolve erro da Meta.

Ciclo de vida do template

stateDiagram-v2
  direction LR
  [*] --> DRAFT: POST /templates (grava no cache local)
  DRAFT --> PENDING: POST /templates/:id/submit (envia para a Meta)
  PENDING --> APPROVED: POST /templates/:id/sync, quando a Meta aprovou
  PENDING --> REJECTED: POST /templates/:id/sync, quando a Meta recusou
  APPROVED --> DRAFT: PATCH /templates/:id (edição volta para rascunho)
  REJECTED --> DRAFT: PATCH /templates/:id (edição volta para rascunho)
  note right of PENDING
    PATCH é bloqueado enquanto o
    template está em PENDING
  end note
  note right of REJECTED
    rejectionReason é preenchido
    pelo sync, não pelo webhook
  end note

Ciclo de vida da campanha

stateDiagram-v2
  direction LR
  [*] --> DRAFT: POST /campaigns (sempre nasce em DRAFT)
  DRAFT --> EXECUTING: POST /:id/execute
  EXECUTING --> COMPLETED: o último lote terminou
  EXECUTING --> PAUSED: POST /:id/pause
  EXECUTING --> FAILED: erro no processamento do lote
  COMPLETED --> [*]
  FAILED --> [*]
  PAUSED --> [*]

O envio roda em lotes de 50 com 1 segundo entre lotes, dentro do processo. O pause só é verificado entre lotes.

Ciclo de vida da mensagem

stateDiagram-v2
  direction LR
  [*] --> PENDING: linha criada antes de chamar a Meta
  PENDING --> SENT: a Meta aceitou o envio
  PENDING --> FAILED: a Meta recusou — errorCode e errorMessage gravados
  SENT --> DELIVERED: status update delivered, grava deliveredAt
  DELIVERED --> READ: status update read, grava readAt
  SENT --> FAILED: status update failed
  DELIVERED --> FAILED: status update failed
  READ --> [*]
  FAILED --> [*]

Só POST /messages/* cria essa linha. Envio por automação, campanha ou flow não entra no histórico — é a limitação da §15 que mais confunde quem monta relatório.

Ciclo de vida da atribuição de conversa

stateDiagram-v2
  direction LR
  [*] --> OPEN: POST /inbox/assign sem agentId e sem agente disponível
  [*] --> ASSIGNED: POST /inbox/assign com agentId, ou com roteamento automático
  OPEN --> ASSIGNED: POST /inbox/assign informando o agentId
  ASSIGNED --> ASSIGNED: POST /inbox/:id/transfer (troca de agente, com motivo)
  ASSIGNED --> RESOLVED: POST /inbox/:id/resolve
  OPEN --> RESOLVED: POST /inbox/:id/resolve
  RESOLVED --> CLOSED: POST /inbox/:id/close
  ASSIGNED --> CLOSED: POST /inbox/:id/close
  CLOSED --> [*]

Ciclo de vida do flow

stateDiagram-v2
  direction LR
  [*] --> DRAFT: POST /flows
  DRAFT --> DRAFT: PUT /flows/:id/json (só fora de PUBLISHED)
  DRAFT --> PUBLISHED: POST /flows/:id/publish
  PUBLISHED --> DEPRECATED: POST /flows/:id/deprecate
  DEPRECATED --> [*]

BLOCKED e THROTTLED existem no enum porque espelham estados que a Meta aplica ao flow — o BB não os grava por conta própria.

Ciclo de vida do dispatcher

stateDiagram-v2
  direction LR
  [*] --> ACTIVE: POST /dispatchers
  ACTIVE --> PAUSED: POST /dispatchers/:id/toggle (pausa a inscrição no Webhooks Engine)
  PAUSED --> ACTIVE: POST /dispatchers/:id/toggle (retoma a inscrição)
  ACTIVE --> [*]: DELETE /dispatchers/:id remove também a inscrição
  PAUSED --> [*]: DELETE /dispatchers/:id remove também a inscrição

DISABLED existe no enum, mas o toggle alterna só entre ACTIVE e PAUSED.

Status de pedido e de cobrança

Os dois são movidos por PATCH, sem guarda de transição: qualquer valor do enum é aceito a partir de qualquer outro. WppBizOrderStatus vai de PENDING a REFUNDED e WppBizPaymentStatus de PENDING a EXPIRED — mas o order_status_update da Meta é quem move a cobrança na prática, mapeando pending, processing, captured, failed, canceled/cancelled, refunded e expired para o enum interno. Como não há rota para criar pedido pela API (§15), essas duas máquinas ainda não fecham ponta a ponta.

Prefixo: /wpp-business. Em staging, a base é https://wpp-business.bb.stg.catalisa.app/wpp-business.

Salvo indicação em contrário, toda rota exige authMiddleware (Bearer JWT do IAM ou X-API-Key), a permissão indicada e requireOrganization — token sem organizationId recebe 403. A única exceção é /api/v1/webhook, que é chamado pela Meta e se autentica por assinatura HMAC.

São 151 endpoints em 20 recursos, mais GET /wpp-business/health. A ordem em que um integrador os encontra é sempre a mesma:

flowchart LR
  A["/apps<br/>5 endpoints"] --> B["/devices ou /accounts<br/>1 e 27 endpoints"]
  B --> C["/accounts/:id/webhooks<br/>configura a Meta"]
  C --> D["/templates<br/>9 endpoints"]
  D --> E["/messages<br/>7 endpoints"]
  E --> F["/contacts<br/>12 endpoints"]
  F --> G["/campaigns<br/>8 endpoints"]
  E --> H["/webhook e /webhook/logs<br/>2 mais 4 endpoints"]
  H --> I["/dispatchers<br/>8 endpoints"]
  I --> J["/agents e /inbox<br/>11 mais 8 endpoints"]

Meta Apps — /wpp-business/api/v1/apps (5)

Contas WABA — /wpp-business/api/v1/accounts (27)

Conta

Números da conta

Webhook na Meta

Informação da WABA

Templates direto na Meta — a Meta é a fonte de verdade nestas rotas

Operações de número — :phoneNumberId aqui é o ID da Meta, não o UUID interno

Onboarding simplificado — /wpp-business/api/v1/devices (1)

Mensagens — /wpp-business/api/v1/messages (7)

Contatos — /wpp-business/api/v1/contacts (12)

Templates (cache local) — /wpp-business/api/v1/templates (9)

Campanhas — /wpp-business/api/v1/campaigns (8)

Automações — /wpp-business/api/v1/automations (6)

Dispatchers — /wpp-business/api/v1/dispatchers (8)

WhatsApp Flows — /wpp-business/api/v1/flows (9)

Catálogo e produtos — /wpp-business/api/v1/catalogs (11)

Os dois send-* exigem que o catálogo tenha metaCatalogId, e nenhum endpoint preenche esse campo hoje. Leia a §15 antes de planejar com base neles.

Pedidos — /wpp-business/api/v1/orders (3)

Pagamentos — /wpp-business/api/v1/payments (9)

Analytics — /wpp-business/api/v1/analytics (2)

Mídia — /wpp-business/api/v1/media (4)

Links curtos — /wpp-business/api/v1/short-links (5)

Agentes e regras de distribuição — /wpp-business/api/v1/agents (11)

Caixa de entrada — /wpp-business/api/v1/inbox (8)

Webhook da Meta e log — /wpp-business/api/v1/webhook (2 + 4)

Saúde

Abaixo, os endpoints que um integrador usa primeiro, em detalhe.

POST /wpp-business/api/v1/apps

Registra o Meta App da organização. É o primeiro passo — sem ele, criar conta falha com APP_NOT_REGISTERED.

Request

{
  "name": "App WhatsApp da Financeira Exemplo",
  "appId": "1234567890123456",
  "appSecret": "o-app-secret-do-meta-for-developers"
}

{
  "name": "App WhatsApp da Financeira Exemplo",
  "appId": "1234567890123456",
  "appSecret": "o-app-secret-do-meta-for-developers"
}

Resposta 201 — o App Secret vem como booleano, não como valor.

{
  "data": {
    "id": "a1000000-0000-4000-8000-000000000001",
    "name": "App WhatsApp da Financeira Exemplo",
    "appId": "1234567890123456",
    "hasAppSecret": true,
    "createdAt": "2026-08-16T12:00:00.000Z"
  }
}

{
  "data": {
    "id": "a1000000-0000-4000-8000-000000000001",
    "name": "App WhatsApp da Financeira Exemplo",
    "appId": "1234567890123456",
    "hasAppSecret": true,
    "createdAt": "2026-08-16T12:00:00.000Z"
  }
}

Erros

POST /wpp-business/api/v1/devices/standalone

Onboarding modo B: você manda o access token, o phoneNumberId e o wabaId, e o BB descobre a WABA, o negócio dono e o número na Graph API, cria ou reaproveita a conta e ainda configura o webhook na Meta em seguida.

Request

{
  "accessToken": "EAAxxxxx...",
  "phoneNumberId": "9876543210987654",
  "wabaId": "1122334455667788",
  "name": "Número principal de atendimento"
}

{
  "accessToken": "EAAxxxxx...",
  "phoneNumberId": "9876543210987654",
  "wabaId": "1122334455667788",
  "name": "Número principal de atendimento"
}

Resposta 201

{
  "data": {
    "bbDeviceId": "a3000000-0000-4000-8000-000000000003",
    "accountId": "a2000000-0000-4000-8000-000000000002",
    "wppBizAppId": "a1000000-0000-4000-8000-000000000001",
    "displayNumber": "+55 11 90000-0000"
  }
}

{
  "data": {
    "bbDeviceId": "a3000000-0000-4000-8000-000000000003",
    "accountId": "a2000000-0000-4000-8000-000000000002",
    "wppBizAppId": "a1000000-0000-4000-8000-000000000001",
    "displayNumber": "+55 11 90000-0000"
  }
}

O bbDeviceId é o UUID interno do número — é ele que vai em phoneNumberId nas rotas de envio, não o ID da Meta.

Erros

POST /wpp-business/api/v1/accounts/:id/webhooks

Configura o webhook na Meta. Faz duas chamadas: assina o Meta App na callback URL e inscreve a WABA no app.

Pré-requisitos. A conta precisa ter um WppBizApp vinculado (ou os campos legados appId/appSecret) e um webhookVerifyToken — gere com POST /accounts/:id/regenerate-verify-token. O serviço também precisa de WPP_BUSINESS_WEBHOOK_BASE_URL configurada.

Request

{ "fields": ["messages", "message_template_status_update", "phone_number_quality_update"] }

{ "fields": ["messages", "message_template_status_update", "phone_number_quality_update"] }

overrideCallbackUri não é mais aceito — o schema rejeita explicitamente. A URL de callback é derivada de WPP_BUSINESS_WEBHOOK_BASE_URL e é sempre <base>/wpp-business/api/v1/webhook.

Resposta 201

{
  "data": {
    "id": "a2000000-0000-4000-8000-000000000002",
    "subscribedFields": ["messages", "message_template_status_update", "phone_number_quality_update"],
    "webhookConfiguredAt": "2026-08-16T12:05:00.000Z",
    "webhookCallbackUrl": "https://wpp-business.bb.stg.catalisa.app/wpp-business/api/v1/webhook",
    "hasAccessToken": true,
    "hasAppSecret": true
  }
}

{
  "data": {
    "id": "a2000000-0000-4000-8000-000000000002",
    "subscribedFields": ["messages", "message_template_status_update", "phone_number_quality_update"],
    "webhookConfiguredAt": "2026-08-16T12:05:00.000Z",
    "webhookCallbackUrl": "https://wpp-business.bb.stg.catalisa.app/wpp-business/api/v1/webhook",
    "hasAccessToken": true,
    "hasAppSecret": true
  }
}

Erros

POST /wpp-business/api/v1/messages/send-template

Envia um template aprovado. É o único jeito de iniciar conversa com a janela de 24h fechada.

Request

{
  "phoneNumberId": "a3000000-0000-4000-8000-000000000003",
  "to": "5511999998888",
  "templateName": "aviso_vencimento",
  "languageCode": "pt_BR",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Maria" },
        { "type": "text", "text": "R$ 412,90" },
        { "type": "text", "text": "20/08" }
      ]
    }
  ]
}

{
  "phoneNumberId": "a3000000-0000-4000-8000-000000000003",
  "to": "5511999998888",
  "templateName": "aviso_vencimento",
  "languageCode": "pt_BR",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Maria" },
        { "type": "text", "text": "R$ 412,90" },
        { "type": "text", "text": "20/08" }
      ]
    }
  ]
}

Resposta 201 — o registro em wpp_biz_messages, já com o ID da Meta.

{
  "data": {
    "id": "0c8f3f7a-4d2b-4b71-9d1e-3a6c5e2f8b40",
    "waMessageId": "wamid.HBgNNTUxMTk5OTk5ODg4OBUCABEYEjc...",
    "direction": "OUTBOUND",
    "status": "SENT",
    "type": "TEMPLATE",
    "to": "5511999998888",
    "sentAt": "2026-08-16T12:10:00.000Z"
  }
}

{
  "data": {
    "id": "0c8f3f7a-4d2b-4b71-9d1e-3a6c5e2f8b40",
    "waMessageId": "wamid.HBgNNTUxMTk5OTk5ODg4OBUCABEYEjc...",
    "direction": "OUTBOUND",
    "status": "SENT",
    "type": "TEMPLATE",
    "to": "5511999998888",
    "sentAt": "2026-08-16T12:10:00.000Z"
  }
}

O status evolui para DELIVERED e READ conforme a Meta manda os status updates pelo webhook. Se o envio falhar, a linha é gravada com status: "FAILED" e errorMessage, e a resposta HTTP carrega o erro.

Erros

POST /wpp-business/api/v1/messages/send

Texto livre, mídia, localização e interativo. Só funciona com a janela de 24h aberta.

Request

{
  "phoneNumberId": "a3000000-0000-4000-8000-000000000003",
  "to": "5511999998888",
  "type": "TEXT",
  "content": { "body": "Recebi seu comprovante, já estou verificando." }
}

{
  "phoneNumberId": "a3000000-0000-4000-8000-000000000003",
  "to": "5511999998888",
  "type": "TEXT",
  "content": { "body": "Recebi seu comprovante, já estou verificando." }
}

Exemplos de content por tipo:

// TEXT
{ "body": "texto da mensagem" }
// IMAGE — por link público ou por id vindo de POST /media/upload
{ "link": "https://exemplo.com/foto.jpg", "caption": "legenda" }
{ "id": "1234567890", "caption": "legenda" }
// DOCUMENT
{ "id": "1234567890", "filename": "boleto.pdf" }
// LOCATION
{ "latitude": -23.5613, "longitude": -46.6565, "name": "Loja Paulista" }

// TEXT
{ "body": "texto da mensagem" }
// IMAGE — por link público ou por id vindo de POST /media/upload
{ "link": "https://exemplo.com/foto.jpg", "caption": "legenda" }
{ "id": "1234567890", "caption": "legenda" }
// DOCUMENT
{ "id": "1234567890", "filename": "boleto.pdf" }
// LOCATION
{ "latitude": -23.5613, "longitude": -46.6565, "name": "Loja Paulista" }

Erros — os mesmos de send-template, mais o mais comum de todos: a Meta recusa com 400 quando a janela está fechada. Consulte GET /contacts/:id/conversation-window antes.

GET /wpp-business/api/v1/contacts/:id/conversation-window

Diz se dá para mandar texto livre.

Query string

Resposta 200

{
  "data": {
    "isOpen": true,
    "expiresAt": "2026-08-17T09:32:11.000Z",
    "remainingMinutes": 1289,
    "lastInboundAt": "2026-08-16T09:32:11.000Z"
  }
}

{
  "data": {
    "isOpen": true,
    "expiresAt": "2026-08-17T09:32:11.000Z",
    "remainingMinutes": 1289,
    "lastInboundAt": "2026-08-16T09:32:11.000Z"
  }
}

Com isOpen: false, remainingMinutes é 0 e expiresAt pode ser null quando o contato nunca escreveu. Nesse caso, a única saída é POST /messages/send-template.

POST /wpp-business/api/v1/webhook — chamado pela Meta

Você não chama este endpoint; a Meta chama. Documentado porque é o ponto que mais gera dúvida na configuração.

Autenticação. Sem JWT. O BB extrai entry[0].id (o wabaId), encontra a conta correspondente, decifra o App Secret dela e valida o x-hub-signature-256 com HMAC-SHA256 sobre o corpo cru, em comparação de tempo constante.

Respostas

Verificação inicial — GET /wpp-business/api/v1/webhook?hub.mode=subscribe&hub.verify_token=<token>&hub.challenge=<n> devolve o challenge em texto puro quando o verify_token casa com o webhookVerifyToken de alguma conta ativa, e 403 caso contrário.

Do zero à primeira mensagem entregue no WhatsApp de alguém.

Os comandos abaixo não foram executados na redação deste documento. Eles reproduzem o fluxo validado em produção em 1º de abril de 2026, registrado no tutorial de webhook. Credenciais de staging vêm de AMBIENTES.md — nunca use credencial de produção em script de exemplo.

Pré-requisitos do lado da Meta, que nenhuma API resolve por você: uma WABA verificada, um número registrado com PIN de dois fatores, um Meta App com o App Secret em mãos, e um template aprovado (o hello_world que a Meta cria por padrão serve para o teste).

Os sete passos, antes dos comandos:

sequenceDiagram
  autonumber
  participant Voce as Você
  participant IAM as IAM
  participant BB as WPP Business
  participant Meta as Meta Cloud API
  participant Cel as Seu celular
  Voce->>IAM: 1. login, recebe o token com organizationId
  Voce->>BB: 2. POST /apps — registra o Meta App
  Voce->>BB: 3. POST /devices/standalone — conecta o número
  BB->>Meta: descobre WABA, negócio e número
  Voce->>BB: 4. GET e POST /accounts/:id/webhooks — confirma o callback
  BB->>Meta: assina o app e a WABA
  Voce->>BB: 5. POST /messages/send-template
  BB->>Meta: hello_world
  Meta->>Cel: a mensagem chega
  Cel->>Meta: 6. você responde no celular
  Meta->>BB: webhook messages
  Voce->>BB: 6. GET /messages — vê a resposta INBOUND
  Voce->>BB: 7. GET /contacts/:id/conversation-window — a janela abriu

1. Autenticar no IAM

BASE="https://wpp-business.bb.stg.catalisa.app/wpp-business/api/v1"

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

echo "${TOKEN:0:32}..."

BASE="https://wpp-business.bb.stg.catalisa.app/wpp-business/api/v1"

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

echo "${TOKEN:0:32}..."

2. Registrar o Meta App

APP_ID=$(curl -s -X POST "$BASE/apps" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "App de teste",
    "appId": "SEU_META_APP_ID",
    "appSecret": "SEU_META_APP_SECRET"
  }' | jq -r '.data.id')

APP_ID=$(curl -s -X POST "$BASE/apps" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "App de teste",
    "appId": "SEU_META_APP_ID",
    "appSecret": "SEU_META_APP_SECRET"
  }' | jq -r '.data.id')

{ "data": { "id": "a1000000-...", "appId": "SEU_META_APP_ID", "hasAppSecret": true } }

{ "data": { "id": "a1000000-...", "appId": "SEU_META_APP_ID", "hasAppSecret": true } }

3. Conectar o número (modo B)

curl -s -X POST "$BASE/devices/standalone" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "accessToken": "SEU_TOKEN_DE_SYSTEM_USER",
    "phoneNumberId": "ID_DO_NUMERO_NA_META",
    "wabaId": "ID_DA_SUA_WABA"
  }' | jq

curl -s -X POST "$BASE/devices/standalone" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "accessToken": "SEU_TOKEN_DE_SYSTEM_USER",
    "phoneNumberId": "ID_DO_NUMERO_NA_META",
    "wabaId": "ID_DA_SUA_WABA"
  }' | jq

{
  "data": {
    "bbDeviceId": "a3000000-...",
    "accountId": "a2000000-...",
    "wppBizAppId": "a1000000-...",
    "displayNumber": "+55 11 90000-0000"
  }
}

{
  "data": {
    "bbDeviceId": "a3000000-...",
    "accountId": "a2000000-...",
    "wppBizAppId": "a1000000-...",
    "displayNumber": "+55 11 90000-0000"
  }
}

Guarde os dois: PHONE=a3000000-... e ACCOUNT=a2000000-....

4. Configurar o webhook na Meta

O modo B já tenta configurar o webhook sozinho. Confirme primeiro:

curl -s "$BASE/accounts/$ACCOUNT/webhooks" -H "Authorization: Bearer $TOKEN" | jq

curl -s "$BASE/accounts/$ACCOUNT/webhooks" -H "Authorization: Bearer $TOKEN" | jq

Se a resposta já traz os campos assinados e a webhookCallbackUrl, pule para o passo 5. Se não, gere o verify token:

curl -s -X POST "$BASE/accounts/$ACCOUNT/regenerate-verify-token" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.webhookVerifyToken'

curl -s -X POST "$BASE/accounts/$ACCOUNT/regenerate-verify-token" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.webhookVerifyToken'

{ "data": { "webhookVerifyToken": "um-token-aleatório-gerado-pelo-BB" } }

{ "data": { "webhookVerifyToken": "um-token-aleatório-gerado-pelo-BB" } }

E então assine o webhook na Meta:

curl -s -X POST "$BASE/accounts/$ACCOUNT/webhooks" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"fields":["messages"]}' | jq '.data | {subscribedFields, webhookCallbackUrl}'

curl -s -X POST "$BASE/accounts/$ACCOUNT/webhooks" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"fields":["messages"]}' | jq '.data | {subscribedFields, webhookCallbackUrl}'

{
  "subscribedFields": ["messages"],
  "webhookCallbackUrl": "https://wpp-business.bb.stg.catalisa.app/wpp-business/api/v1/webhook"
}

{
  "subscribedFields": ["messages"],
  "webhookCallbackUrl": "https://wpp-business.bb.stg.catalisa.app/wpp-business/api/v1/webhook"
}

5. Enviar o primeiro template

curl -s -X POST "$BASE/messages/send-template" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"phoneNumberId\": \"$PHONE\",
    \"to\": \"5511999999999\",
    \"templateName\": \"hello_world\",
    \"languageCode\": \"en_US\"
  }" | jq '.data | {id, waMessageId, status}'

curl -s -X POST "$BASE/messages/send-template" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"phoneNumberId\": \"$PHONE\",
    \"to\": \"5511999999999\",
    \"templateName\": \"hello_world\",
    \"languageCode\": \"en_US\"
  }" | jq '.data | {id, waMessageId, status}'

{ "id": "0c8f3f7a-...", "waMessageId": "wamid.HBgNNTUxMTk5...", "status": "SENT" }

{ "id": "0c8f3f7a-...", "waMessageId": "wamid.HBgNNTUxMTk5...", "status": "SENT" }

A mensagem chega no celular. É aqui que você vê acontecer.

6. Responder no celular e conferir que a resposta chegou

curl -s "$BASE/messages?phoneNumberId=$PHONE&limit=5" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {direction, type, status, from, createdAt}'

curl -s "$BASE/messages?phoneNumberId=$PHONE&limit=5" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {direction, type, status, from, createdAt}'

A resposta aparece com direction: "INBOUND". Se não aparecer, o webhook não está entregando — confira o log:

curl -s "$BASE/webhook/logs?limit=5" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {status, errorMessage, sourceIp, createdAt}'

curl -s "$BASE/webhook/logs?limit=5" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {status, errorMessage, sourceIp, createdAt}'

7. Confirmar que a janela abriu

CONTACT=$(curl -s "$BASE/contacts?limit=1" -H "Authorization: Bearer $TOKEN" | jq -r '.data[0].id')

curl -s "$BASE/contacts/$CONTACT/conversation-window?phoneNumberId=$PHONE" \
  -H "Authorization: Bearer $TOKEN" | jq

CONTACT=$(curl -s "$BASE/contacts?limit=1" -H "Authorization: Bearer $TOKEN" | jq -r '.data[0].id')

curl -s "$BASE/contacts/$CONTACT/conversation-window?phoneNumberId=$PHONE" \
  -H "Authorization: Bearer $TOKEN" | jq

{ "data": { "isOpen": true, "remainingMinutes": 1439, "expiresAt": "..." } }

{ "data": { "isOpen": true, "remainingMinutes": 1439, "expiresAt": "..." } }

Com a janela aberta, POST /messages/send com texto livre passa a funcionar.

Publicar um template e usá-lo em campanha

Objetivo: sair do zero até uma campanha disparada para os contatos de uma etiqueta.

flowchart LR
  T1["POST /templates<br/>DRAFT"] --> T2["POST /templates/:id/submit<br/>PENDING"]
  T2 --> T3["Meta revisa"]
  T3 --> T4["POST /templates/:id/sync<br/>APPROVED ou REJECTED"]
  T4 --> C1["POST /contacts/tags<br/>etiqueta o público"]
  C1 --> C2["POST /campaigns<br/>filters.tagIds"]
  C2 --> C3["POST /campaigns/:id/execute<br/>EXECUTING"]
  C3 --> C4["GET /campaigns/:id<br/>totalRecipients, sentCount, failedCount"]

1. Criar o template no cache local, como DRAFT

TPL=$(curl -s -X POST "$BASE/templates" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"accountId\": \"$ACCOUNT\",
    \"name\": \"aviso_vencimento\",
    \"language\": \"pt_BR\",
    \"category\": \"UTILITY\",
    \"components\": [
      {\"type\":\"BODY\",\"text\":\"Olá {{1}}, sua parcela de {{2}} vence em {{3}}.\"}
    ]
  }" | jq -r '.data.id')

TPL=$(curl -s -X POST "$BASE/templates" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"accountId\": \"$ACCOUNT\",
    \"name\": \"aviso_vencimento\",
    \"language\": \"pt_BR\",
    \"category\": \"UTILITY\",
    \"components\": [
      {\"type\":\"BODY\",\"text\":\"Olá {{1}}, sua parcela de {{2}} vence em {{3}}.\"}
    ]
  }" | jq -r '.data.id')

2. Submeter à Meta — o status vai para PENDING

curl -s -X POST "$BASE/templates/$TPL/submit" -H "Authorization: Bearer $TOKEN" | jq '.data.status'

curl -s -X POST "$BASE/templates/$TPL/submit" -H "Authorization: Bearer $TOKEN" | jq '.data.status'

"PENDING"

"PENDING"

3. Aguardar a aprovação e sincronizar o status local

curl -s -X POST "$BASE/templates/$TPL/sync" -H "Authorization: Bearer $TOKEN" \
  | jq '.data | {status, rejectionReason}'

curl -s -X POST "$BASE/templates/$TPL/sync" -H "Authorization: Bearer $TOKEN" \
  | jq '.data | {status, rejectionReason}'

{ "status": "APPROVED", "rejectionReason": null }

{ "status": "APPROVED", "rejectionReason": null }

4. Etiquetar os contatos-alvo

TAG=$(curl -s -X POST "$BASE/contacts/tags" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"vence-20-08","color":"#F97316"}' | jq -r '.data.id')

TAG=$(curl -s -X POST "$BASE/contacts/tags" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"vence-20-08","color":"#F97316"}' | jq -r '.data.id')

5. Criar a campanha e disparar

CAMP=$(curl -s -X POST "$BASE/campaigns" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Aviso de vencimento 20/08\",
    \"templateId\": \"$TPL\",
    \"phoneNumberId\": \"$PHONE\",
    \"filters\": {\"tagIds\": [\"$TAG\"]}
  }" | jq -r '.data.id')

curl -s -X POST "$BASE/campaigns/$CAMP/execute" -H "Authorization: Bearer $TOKEN" | jq '.data.status'

CAMP=$(curl -s -X POST "$BASE/campaigns" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Aviso de vencimento 20/08\",
    \"templateId\": \"$TPL\",
    \"phoneNumberId\": \"$PHONE\",
    \"filters\": {\"tagIds\": [\"$TAG\"]}
  }" | jq -r '.data.id')

curl -s -X POST "$BASE/campaigns/$CAMP/execute" -H "Authorization: Bearer $TOKEN" | jq '.data.status'

"EXECUTING"

"EXECUTING"

6. Acompanhar

curl -s "$BASE/campaigns/$CAMP" -H "Authorization: Bearer $TOKEN" \
  | jq '.data | {status, totalRecipients, sentCount, failedCount}'

curl -s "$BASE/campaigns/$CAMP" -H "Authorization: Bearer $TOKEN" \
  | jq '.data | {status, totalRecipients, sentCount, failedCount}'

{ "status": "EXECUTING", "totalRecipients": 4000, "sentCount": 350, "failedCount": 2 }

{ "status": "EXECUTING", "totalRecipients": 4000, "sentCount": 350, "failedCount": 2 }

Armadilhas.

• filters vazio significa a base inteira. O único filtro implementado é tagIds. Qualquer outra chave é ignorada e a campanha vai para todos os contatos da organização. Confira o totalRecipients logo depois do execute, antes de tomar café.
• A campanha só sai com o template APPROVED. O BB recusa com 400 se o status local não estiver aprovado — e o status local só muda com POST /templates/:id/sync, porque o webhook de aprovação da Meta não escreve no banco (§15).
• A Meta recategoriza template, e isso custa caro. Desde abril de 2025, quando você pede UTILITY e a Meta discorda, ela aprova como MARKETING em vez de rejeitar — a sua aplicação não vê erro nenhum, e a fatura pode multiplicar por cerca de nove (§6). As causas mais comuns são conteúdo misturado (uma atualização de pedido com uma promoção junto) e conteúdo vago (um corpo que é só {{1}}, ou só "Parabéns!"). Sempre confira a categoria efetiva em GET /accounts/:id/templates depois da aprovação. Há 60 dias para recorrer da categorização (Template Categorization).
• Reincidência tem escada de punição. A Meta aplica, em ordem: aviso — e a partir daí recategorização passa a ser instantânea, sem as 24 horas de aviso prévio; limitação de volume de UTILITY por pelo menos 7 dias; e, no limite, recategorização de todos os templates de utilidade da WABA para marketing, com criação de novos utility desabilitada por 7 dias, ou 30 em reincidência.
• pause demora até um lote. O envio roda em lotes de 50 e o pause só é verificado entre lotes.
• Não reinicie o serviço com campanha em andamento. O envio roda dentro do processo; um deploy no meio deixa os destinatários restantes em PENDING para sempre (§15).
• deliveredCount e readCount não sobem. Os envios de campanha não criam registro em wpp_biz_messages, então o status update da Meta não encontra o destinatário para atualizar. Use sentCount e failedCount, que são confiáveis (§15).

Reprocessar um webhook que falhou

Objetivo: descobrir por que um evento da Meta não virou mensagem e tentar de novo.

flowchart LR
  L1["GET /webhook/logs?status=FAILED"] --> L2["GET /webhook/logs/:id<br/>payload cru"]
  L2 --> L3["POST /webhook/logs/:id/replay"]
  L3 --> L4["GET /webhook/logs/stats<br/>isolado ou sistêmico?"]

1. Achar o log com falha

curl -s "$BASE/webhook/logs?status=FAILED&limit=10" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {id, errorMessage, phoneNumberId, createdAt}'

curl -s "$BASE/webhook/logs?status=FAILED&limit=10" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {id, errorMessage, phoneNumberId, createdAt}'

{ "id": "…", "errorMessage": "Unknown phone number", "phoneNumberId": null, "createdAt": "…" }

{ "id": "…", "errorMessage": "Unknown phone number", "phoneNumberId": null, "createdAt": "…" }

2. Ver o payload cru

curl -s "$BASE/webhook/logs/$LOG_ID" -H "Authorization: Bearer $TOKEN" | jq '.data.payload'

curl -s "$BASE/webhook/logs/$LOG_ID" -H "Authorization: Bearer $TOKEN" | jq '.data.payload'

3. Reprocessar

curl -s -X POST "$BASE/webhook/logs/$LOG_ID/replay" -H "Authorization: Bearer $TOKEN" | jq

curl -s -X POST "$BASE/webhook/logs/$LOG_ID/replay" -H "Authorization: Bearer $TOKEN" | jq

4. Estatísticas gerais, para saber se é caso isolado ou sistêmico

curl -s "$BASE/webhook/logs/stats" -H "Authorization: Bearer $TOKEN" | jq

curl -s "$BASE/webhook/logs/stats" -H "Authorization: Bearer $TOKEN" | jq

Armadilhas.

• IGNORED quase sempre é número desconhecido. O log fica IGNORED quando o phone_number_id do payload não bate com nenhum WppBizPhoneNumber. Confira se o número foi vinculado à conta.
• O replay não valida assinatura, por desenho. Só quem tem WPP_BIZ_WEBHOOKS_WRITE deve receber essa permissão.
• O replay de eventos de mensagem hoje não reprocessa. O log guarda o value do evento, não o envelope completo que o reprocessador espera — a chamada devolve sucesso sem fazer nada. Ver §15. Para reconstituir uma mensagem perdida, o caminho é o payload cru do passo 2.

Encaminhar mensagens recebidas para o seu sistema

Objetivo: fazer o WhatsApp alimentar a sua aplicação sem escrever um relay.

sequenceDiagram
  autonumber
  participant Meta as Meta
  participant BB as WPP Business
  participant Disp as Dispatcher
  participant WE as Webhooks Engine
  participant Voce as Seu sistema
  Meta->>BB: webhook messages
  BB->>Disp: evento wpp-biz.message.received.*
  Disp->>Disp: filtra por messageTypes, events e conditions JSONPath
  Disp->>WE: cria ou reusa a inscrição (subscriptionId)
  WE->>Voce: POST assinado com o signingSecret
  Voce-->>WE: 2xx encerra, 5xx entra em backoff
  WE->>WE: registra em delivery-logs

Modo BASIC — todos os textos e imagens recebidos de um número específico:

curl -s -X POST "$BASE/dispatchers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Esteira de atendimento\",
    \"mode\": \"BASIC\",
    \"messageTypes\": [\"TEXT\", \"IMAGE\"],
    \"phoneNumberId\": \"$PHONE\",
    \"endpointUrl\": \"https://seu-sistema.com.br/hooks/whatsapp\",
    \"signingSecret\": \"um-segredo-com-pelo-menos-16-caracteres\",
    \"timeoutMs\": 15000,
    \"retryConfig\": {\"maxRetries\": 5, \"retryBackoffMs\": 1000, \"retryBackoffMultiplier\": 2}
  }" | jq '.data | {id, subscriptionId, status}'

curl -s -X POST "$BASE/dispatchers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Esteira de atendimento\",
    \"mode\": \"BASIC\",
    \"messageTypes\": [\"TEXT\", \"IMAGE\"],
    \"phoneNumberId\": \"$PHONE\",
    \"endpointUrl\": \"https://seu-sistema.com.br/hooks/whatsapp\",
    \"signingSecret\": \"um-segredo-com-pelo-menos-16-caracteres\",
    \"timeoutMs\": 15000,
    \"retryConfig\": {\"maxRetries\": 5, \"retryBackoffMs\": 1000, \"retryBackoffMultiplier\": 2}
  }" | jq '.data | {id, subscriptionId, status}'

{ "id": "…", "subscriptionId": "…", "status": "ACTIVE" }

{ "id": "…", "subscriptionId": "…", "status": "ACTIVE" }

Modo ADVANCED — só interativos cujo payload de botão comece com PROPOSTA_:

curl -s -X POST "$BASE/dispatchers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "Respostas de proposta",
    "mode": "ADVANCED",
    "events": ["wpp-biz.message.received.interactive"],
    "endpointUrl": "https://seu-sistema.com.br/hooks/proposta",
    "conditions": {
      "match": "all",
      "filters": [
        { "path": "$.text", "operator": "starts_with", "value": "PROPOSTA_" }
      ]
    }
  }' | jq '.data.id'

curl -s -X POST "$BASE/dispatchers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "Respostas de proposta",
    "mode": "ADVANCED",
    "events": ["wpp-biz.message.received.interactive"],
    "endpointUrl": "https://seu-sistema.com.br/hooks/proposta",
    "conditions": {
      "match": "all",
      "filters": [
        { "path": "$.text", "operator": "starts_with", "value": "PROPOSTA_" }
      ]
    }
  }' | jq '.data.id'

Acompanhar a entrega e reprocessar o que falhou:

curl -s "$BASE/dispatchers/$DISP/delivery-logs?status=failed" -H "Authorization: Bearer $TOKEN" | jq
curl -s -X POST "$BASE/dispatchers/$DISP/delivery-logs/$LOG/retry" -H "Authorization: Bearer $TOKEN" | jq

curl -s "$BASE/dispatchers/$DISP/delivery-logs?status=failed" -H "Authorization: Bearer $TOKEN" | jq
curl -s -X POST "$BASE/dispatchers/$DISP/delivery-logs/$LOG/retry" -H "Authorization: Bearer $TOKEN" | jq

Armadilhas.

• messageTypes e events se combinam, não se substituem. Passar os dois gera a união dos filtros. Se nenhum for informado em modo BASIC, o padrão é wpp-biz.message.received.*.
• Guarde o signingSecret. Ele é cifrado no banco e não volta em nenhuma leitura. Perdeu, atualize o dispatcher com um novo e ajuste o seu verificador.
• Excluir o dispatcher exclui a inscrição no Webhooks Engine. Não há órfão para limpar, mas também não há como recuperar o histórico depois.

Descobrir por que a mensagem não chegou

Objetivo: o roteiro de diagnóstico, na ordem que resolve mais rápido.

flowchart TD
  M["GET /messages/:id<br/>o que o BB registrou"] --> Q1{"status FAILED?"}
  Q1 -->|"sim"| E["Leia errorCode e errorMessage"]
  Q1 -->|"não"| W["GET /contacts/:id/conversation-window"]
  W --> Q2{"isOpen false e você usou POST /send?"}
  Q2 -->|"sim"| F["Causa encontrada — use send-template"]
  Q2 -->|"não"| N["GET /accounts/phone-numbers/:id/status<br/>qualidade e limite do número"]
  N --> WB["GET /accounts/:id/waba-info<br/>a WABA está aprovada?"]
  WB --> T["GET /accounts/:id/templates?status=APPROVED<br/>aprovado na Meta, não só no cache"]

1. O que o BB registrou sobre a mensagem

curl -s "$BASE/messages/$MSG_ID" -H "Authorization: Bearer $TOKEN" \
  | jq '{status, errorCode, errorMessage, sentAt, deliveredAt, readAt}'

curl -s "$BASE/messages/$MSG_ID" -H "Authorization: Bearer $TOKEN" \
  | jq '{status, errorCode, errorMessage, sentAt, deliveredAt, readAt}'

2. A janela estava aberta? Só importa para POST /send.

curl -s "$BASE/contacts/$CONTACT/conversation-window?phoneNumberId=$PHONE" \
  -H "Authorization: Bearer $TOKEN" | jq

curl -s "$BASE/contacts/$CONTACT/conversation-window?phoneNumberId=$PHONE" \
  -H "Authorization: Bearer $TOKEN" | jq

3. O número está saudável na Meta?

curl -s "$BASE/accounts/phone-numbers/$META_PHONE_ID/status" -H "Authorization: Bearer $TOKEN" | jq

curl -s "$BASE/accounts/phone-numbers/$META_PHONE_ID/status" -H "Authorization: Bearer $TOKEN" | jq

4. A WABA está aprovada?

curl -s "$BASE/accounts/$ACCOUNT/waba-info" -H "Authorization: Bearer $TOKEN" | jq

curl -s "$BASE/accounts/$ACCOUNT/waba-info" -H "Authorization: Bearer $TOKEN" | jq

5. O template está mesmo aprovado na Meta, e não só no cache local?

curl -s "$BASE/accounts/$ACCOUNT/templates?status=APPROVED" -H "Authorization: Bearer $TOKEN" | jq

curl -s "$BASE/accounts/$ACCOUNT/templates?status=APPROVED" -H "Authorization: Bearer $TOKEN" | jq

Ordem de causa mais comum, da que mais aparece para a que menos aparece:

Rotacionar o token da Meta sem derrubar o envio

Objetivo: trocar o access token de uma conta com o mínimo de janela de erro.

1. Trocar o token

curl -s -X PATCH "$BASE/accounts/$ACCOUNT" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"accessToken":"EAA_NOVO_TOKEN"}' \
  | jq '.data | {id, hasAccessToken}'

curl -s -X PATCH "$BASE/accounts/$ACCOUNT" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"accessToken":"EAA_NOVO_TOKEN"}' \
  | jq '.data | {id, hasAccessToken}'

{ "id": "a2000000-…", "hasAccessToken": true }

{ "id": "a2000000-…", "hasAccessToken": true }

2. Validar imediatamente com uma leitura que toca a Meta

curl -s "$BASE/accounts/$ACCOUNT/waba-info" -H "Authorization: Bearer $TOKEN" | jq '.data'

curl -s "$BASE/accounts/$ACCOUNT/waba-info" -H "Authorization: Bearer $TOKEN" | jq '.data'

Armadilhas.

• O token novo tem que vir do mesmo Meta App. O BB valida com debug_token e recusa se o app do token não bater com o WppBizApp vinculado.
• Token de system user permanente ainda pode ser revogado. Monitore META_TOKEN_REVOKED nos logs, não só a expiração.
• A troca não reconfigura o webhook. A assinatura na Meta é do app, não do token — mas vale conferir com GET /accounts/:id/webhooks depois de qualquer mexida.

Colocar um atendente humano na conversa

Objetivo: sair da automação e entregar a conversa a uma pessoa.

sequenceDiagram
  autonumber
  participant App as Sua aplicação
  participant BB as WPP Business
  participant IAM as IAM
  App->>BB: POST /agents (userId do IAM, maxConcurrent, skills)
  BB->>IAM: valida o usuário
  App->>BB: PATCH /agents/:id/status — AVAILABLE
  App->>BB: POST /inbox/assign (sem agentId, escolhe o de menor carga)
  BB-->>App: atribuição com agentId, status e slaDeadlineAt
  App->>BB: POST /inbox/:id/transfer (outro agente, com motivo)
  App->>BB: POST /inbox/:id/resolve

1. Registrar o agente a partir de um usuário do IAM

AGENT=$(curl -s -X POST "$BASE/agents" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"userId":"UUID_DO_USUARIO_NO_IAM","name":"Ana Souza","maxConcurrent":8,"skills":["cobranca"]}' \
  | jq -r '.data.id')

curl -s -X PATCH "$BASE/agents/$AGENT/status" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"AVAILABLE"}' | jq '.data.status'

AGENT=$(curl -s -X POST "$BASE/agents" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"userId":"UUID_DO_USUARIO_NO_IAM","name":"Ana Souza","maxConcurrent":8,"skills":["cobranca"]}' \
  | jq -r '.data.id')

curl -s -X PATCH "$BASE/agents/$AGENT/status" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"AVAILABLE"}' | jq '.data.status'

"AVAILABLE"

"AVAILABLE"

2. Atribuir a conversa. Sem agentId, o BB escolhe o agente disponível de menor carga.

curl -s -X POST "$BASE/inbox/assign" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"contactPhone\": \"5511999998888\",
    \"phoneNumberId\": \"$PHONE\",
    \"priority\": \"HIGH\",
    \"subject\": \"Negociação de parcela\",
    \"slaMinutes\": 30
  }" | jq '.data | {id, agentId, status, slaDeadlineAt}'

curl -s -X POST "$BASE/inbox/assign" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"contactPhone\": \"5511999998888\",
    \"phoneNumberId\": \"$PHONE\",
    \"priority\": \"HIGH\",
    \"subject\": \"Negociação de parcela\",
    \"slaMinutes\": 30
  }" | jq '.data | {id, agentId, status, slaDeadlineAt}'