Antes de mandar a primeira mensagem, vale entender quatro ideias que aparecem em toda a API: o modelo multi-tenant, a WABA, o Embedded Signup sob a aprovação de Tech Provider e a identidade do contato.
Modelo multi-tenant
A BotoZap é feita para quem atende vários clientes de uma vez. A hierarquia é:
account (você, o dev / workspace)
└─ customer (cada cliente seu)
└─ waba_connection (a WABA do cliente)
└─ phone_number (número de WhatsApp)
└─ conversation / messageA sua account é o topo: é a conta da BotoZap que você administra. Abaixo dela ficam os seus customers, e cada um conecta a própria conta de WhatsApp. Tudo isola por account_id no servidor, então você envia e recebe mensagens em nome de todos os clientes por um endpoint só, sem nunca passar um id de conta na requisição: ele é derivado da sua chave de API.
WABA
WABA é a WhatsApp Business Account, a conta de WhatsApp Business do seu cliente na Meta. Cada WABA tem um ou mais números de telefone e um token de acesso próprio, usado para falar com a Graph API.
Esse token nunca é exposto: fica guardado com segurança no servidor e é resolvido só na hora de chamar a Meta. Você trabalha com a WABA através da API da BotoZap e das suas chaves; o token da conta do cliente não aparece nas respostas nem nos logs.
Embedded Signup e Tech Provider
Para conectar a WABA, o cliente passa pelo Embedded Signup: um fluxo hospedado pela Meta em que ele autoriza (ou cria) a conta de WhatsApp Business dele por um link. No fim, a WABA e o número ficam vinculados à sua plataforma.
Isso funciona porque a BotoZap opera como Tech Provider aprovada pela Meta. A aprovação é nossa, então você não precisa do seu próprio Advanced Access nem de passar pelo App Review da Meta para colocar clientes em produção. Você gera o link, o cliente conecta, e pronto.
A conexão self-service de clientes novos depende de uma aprovação da Meta que está fora do nosso controle direto. Em algum momento ela pode ficar temporariamente indisponível para novas contas, mesmo com o restante da API funcionando normalmente. Se isso acontecer com você, fale com o suporte da BotoZap.
Os detalhes do fluxo estão no artigo Embedded Signup explicado.
Identidade e BSUID
A chave que identifica um contato é opaca. Trate-a sempre como um identificador, nunca como um número de telefone.
Com o rollout de WhatsApp Usernames, a Meta desacoplou a identidade do usuário do número. A Cloud API passou a enviar um BSUID (Business-Scoped User ID): um id escopado por empresa, então o mesmo usuário tem BSUIDs diferentes em WABAs diferentes. O formato é o código de país ISO-2, um ponto e até 128 caracteres alfanuméricos, por exemplo BR.1029411383003659.
Na BotoZap, a chave canônica do contato (wa_id) é o BSUID quando ele é conhecido, e os dígitos E.164 quando não é. Ou seja: às vezes o wa_id parece um telefone, às vezes não. Não faça parsing dele como número, não deduza DDI ou DDD a partir dele; use os campos dedicados (telefone, username) quando precisar exibir ou validar.
O contexto completo, incluindo os usernames do WhatsApp, está no artigo WhatsApp Usernames e BSUID.