6.O Canal Oficial (WhatsApp Cloud API)#
O Catcher é um Meta Tech Provider: além do WhatsApp não-oficial (QR Code), você pode criar conexões no canal oficial — a WhatsApp Cloud API da Meta. O mesmo contrato de API (envio, eventos, webhooks, templates) vale para os dois canais; o que muda é o tipo de conexão, exposto no campo channel e na matriz capabilities de cada instância.
channel |
Como conecta | QR? | Templates | Janela 24h |
|---|---|---|---|---|
whatsapp |
QR Code | sim | não | não |
whatsapp_official |
Credenciais WABA / Embedded Signup | não | sim | sim |
Ramifique por
capabilities, nunca pelo nome do canal. Ex.:capabilities.supports_qr,capabilities.requires_service_window,capabilities.supports_templates.
Criar uma conexão oficial#
POST /v1/instances com {"name": "...", "channel": "whatsapp_official"}. A conexão nasce CREATED (sem QR) e conecta ao credenciar.
Credenciar (BYO token)#
POST /v1/instances/{id}/official/credentials com {"waba_id", "phone_number_id", "access_token"}. O token é validado contra a Graph API da Meta, armazenado cifrado (nunca é retornado — só o hint dos últimos 4), e a conexão vira CONNECTED. GET .../official/credentials retorna o estado mascarado (incluindo reauth_required quando o token expira/é revogado).
Embedded Signup (onboarding sem token)#
Pelo Console, o cliente conecta a própria WABA em minutos via o diálogo Embedded Signup da Meta — o token é trocado no servidor, nunca no browser. Config pública em GET /v1/meta/embedded-signup/config; finalização em POST /v1/instances/{id}/official/embedded-signup.
Templates + janela de 24h#
Conexões oficiais gerenciam message templates aprovados: GET/POST/DELETE /v1/instances/{id}/templates. Fora da janela de 24h (nenhuma mensagem recebida do contato nas últimas 24h), envios free-form retornam 409 OUTSIDE_SERVICE_WINDOW — só templates aprovados passam (POST /v1/messages/template).
Commerce — vender pelo catálogo dentro da conversa#
Três endpoints tipados montam a mensagem de commerce da Cloud API para você (a Catcher valida os limites da Meta localmente, então um envio malformado falha com 400 legível em vez de erro cru da Graph API):
| Rota | O que envia |
|---|---|
POST /v1/instances/{id}/official/send-product |
Um produto (catalog_id + product_retailer_id, com body/footer opcionais) |
POST /v1/instances/{id}/official/send-product-list |
Até 30 produtos em até 10 seções (header e body são obrigatórios; o header é sempre texto) |
POST /v1/instances/{id}/official/send-catalog |
O catálogo inteiro como um card (thumbnail_product_retailer_id opcional) |
O catálogo é criado no Commerce Manager do cliente e conectado à WABA dele — a Catcher não hospeda nem cura catálogo. Todos exigem Idempotency-Key, retornam 202 e respeitam a janela de 24h (fora dela, use o template MPM).
Os limites da Meta são validados localmente (você recebe 400 legível antes da chamada sair): header ≤60 caracteres, body ≤1024, footer ≤60, título de seção ≤24, ≤10 seções e ≤30 produtos por lista. A contagem é em caracteres, não bytes.
Quando o contato monta o carrinho e envia, chega um message.order_received com quais produtos foram pedidos: items[] (product_retailer_id, quantity, item_price_1000, currency), catalog_id, text (recado do comprador) e o rollup item_count/total_amount_1000.
Webhooks + eventos#
Inbound, statuses (sent/delivered/read) e reações do canal oficial chegam pelos mesmos eventos do canal não-oficial (message.received, message.delivered, message.read, message.reaction_received) — com contrato UUID e mídia re-hospedada (nunca URL de CDN da Meta). Eventos operacionais exclusivos: official.template_status, official.quality_update, official.reauth_required e official.automatic_event.
official.automatic_event — atribuição de anúncio. Quando uma conversa nasce de um anúncio Click-to-WhatsApp, a Meta avisa quando ela vira lead (LeadSubmitted) ou compra (Purchase, com currency + value_1000). O ctwa_clid é o mesmo que chega no ad_context do message.received — junte os dois e você fecha o loop anúncio → conversa → resultado. Requer o field automatic_events subscrito na sua App da Meta; indisponível na UE, Reino Unido e Japão.
Métricas de uso#
GET /v1/instances/{id}/official/usage retorna mensagens enviadas/recebidas, templates e conversas (proxy de 24h) por conexão — base para acompanhamento de consumo.