Conceitos

O modelo app → SDK → broker, números oficiais × não-oficiais, tenant e API key.

O modelo: app → SDK → broker

Você integra o WhatsApp em três camadas, sempre na mesma direção. Seu app chama o @wabroker/sdk; o SDK fala HTTP com o broker; e o broker — e só ele — conhece os provedores. Seu código nunca toca a camada de nenhum provedor: o contrato do SDK é o mesmo, seja o número oficial ou não-oficial.

Os exemplos deste portal existem em TypeScript (@wabroker/sdk) e C# (Wabroker.Sdk) — use o seletor no topo de cada bloco; ambos falam com o mesmo broker pela mesma API /v1.

Por que isso importa para você

Trocar o provider por trás de um número não muda uma linha do seu código. Identificadores são sempre msg_…/chan_…, telefones são E.164 sem +, e falhas são códigos de uma união fechada — nunca um wamid ou um erro cru do provedor vazando para você.

Números oficiais × não-oficiais

Um número é um número de WhatsApp que o broker opera em seu nome. Todo número declara sua kind, e ela muda o que você pode fazer:

official: número na plataforma oficial. Habilita templates, exige registro do número e respeita a janela de 24h para texto livre. Conectado por credenciais (Embedded Signup ou credenciais próprias).
unofficial: número conectado por QR code, como o WhatsApp Web. Não envia templates. Você não fornece credencial de provider — o broker resolve a instância de plataforma.

A kind é sempre visível

O broker devolve kind em todo número justamente porque ela muda o que é possível e o risco envolvido. Trate um número não-oficial pelo que ele é — sem as garantias e os recursos (templates) de um oficial.

Tenant e API key

Cada conta é um tenant isolado. Você autentica com uma API key de tenant, enviada no header Authorization: Bearer …. Todo recurso que o SDK acessa — números, mensagens, templates, entregas — é automaticamente escopado ao tenant daquela key. Um recurso de outro tenant é indistinguível de inexistente (o broker responde 404, nunca 403).

O que o broker faz por você

Normaliza envio e recebimento num contrato único, agnóstico ao provider.
Guarda e cifra credenciais (write-only — nunca as devolve).
Gera e renova QR de números não-oficiais; supervisiona a sessão.
Submete e reconcilia templates com a plataforma oficial.
Entrega eventos ao seu webhook, assinados por HMAC, com retries.

Referência da plataforma oficial: plataforma oficial do WhatsApp. Você não precisa dela para integrar — o broker abstrai tudo — mas ela explica conceitos como janela de 24h e templates.