WhatsApp: conexão

Antes de conversar com clientes pelo WhatsApp, a loja precisa ter um número de WhatsApp Business ligado à plataforma. Esta seção cobre tudo da conexão: guardar as credenciais da Meta, cadastrar um número novo, editar o perfil público, configurar os atalhos de abertura e a aparência da mini-loja que abre dentro do WhatsApp. As demais seções (caixa de entrada, campanhas, fluxos, IA) pressupõem que a conexão funciona.

Como funciona

Conectar um número tem dois caminhos. Caminho A, o número já existe na Meta: grave o phone_number_id e o token com PUT /credentials e confira com POST /credentials/verify. Caminho B, o número é novo: use o assistente de cadastro.

1. Registrar

   POST /store-setup/register adiciona o telefone à conta WhatsApp Business (WABA) e devolve o phone_number_id. O número fica pendente.

2. Pedir o código

   POST /store-setup/request-code: a Meta manda um código de 6 dígitos por SMS ou ligação.

3. Confirmar

   POST /store-setup/verify com o código: o número entra no ar e a rota de mensagens recebidas é registrada.

4. Ajustar o perfil

   PUT /profile define nome, descrição e foto que o cliente verá.

O estado do número pode ser conferido a qualquer momento em GET /credentials (campos verified e last_verified_at).

Conceitos-chave

Meta, WABA e phone_number_id

O WhatsApp Business é operado pela Meta. Uma empresa tem uma WABA (conta WhatsApp Business) e, dentro dela, um ou mais números. Cada número tem um phone_number_id, uma string numérica da Meta (não é UUID e não é o telefone). É esse id que as rotas usam.

Número da loja versus número de um seller

Em uma loja com vários sellers (lojistas), há o número da própria loja (rotas credentials, profile, store-setup) e, opcionalmente, um número por seller (self-setup, que exige o vendor_id do seller). As mensagens recebidas num número são atendidas em nome de quem o possui.

Janela de 24 horas e templates

O WhatsApp só deixa a loja mandar texto livre até 24 horas depois da última mensagem do cliente. Depois disso, só templates (modelos de mensagem aprovados pela Meta). Isso afeta o envio do link da mini-loja.

Mini-loja e links personalizados

O link enviado ao cliente carrega um token com a loja e o cliente. Quem abre o link entra na loja já identificado, sem precisar fazer login.

Idioma das mensagens

Os textos de error, warning e meta_error vêm em português (ou no idioma da Meta). Para decidir o que mostrar, use kind e o status HTTP.

Endpoints

Erros comuns

• Achar que PUT /credentials testa o token: ele só grava. Chame POST /credentials/verify em seguida.
• Mandar só o campo alterado em PUT /profile ou em PUT /web-preview/settings: os demais campos de texto são apagados.
• Cadastrar um telefone que já tem WhatsApp comum: a Meta recusa (kind = whatsapp_exists). Exclua a conta do WhatsApp nesse número antes.
• Pedir códigos em excesso: a Meta limita e a resposta é 429 com retry_after_seconds. Troque para VOICE ou espere.
• Perder o two_step_pin devolvido em verify: a Meta o pede ao mover o número de aparelho.
• Esperar que DELETE /credentials apague conversas: ele só desativa o número.

Próximos passos