Gerenciamento programático de nomes de usuário do WhatsApp Business

Um guia técnico para integrar verificações síncronas de registro, avatar e conta comercial do WhatsApp a fluxos de CRM usando o endpoint POST /api/v1/check.

O mapeamento programático de identidade no WhatsApp consiste em usar o endpoint documentado POST /api/v1/check para verificar o status de registro, a disponibilidade do avatar e o tipo de conta comercial. Ao enviar números no formato E.164 com o payload de service_type adequado, as equipes recebem dados JSON síncronos na mesma resposta HTTP. Esse sinal de presença de conta ajuda a enriquecer registros do CRM, apoia a limpeza de listas de leads e orienta fluxos de roteamento automatizados, dando às equipes de operações o contexto necessário para segmentar contatos sem depender de consultas periódicas assíncronas ou webhooks.

O papel das verificações programáticas do WhatsApp

Integrar sinais de presença de conta no WhatsApp às operações da empresa ajuda as equipes a manter bancos de dados mais limpos e favorece fluxos de comunicação mais eficientes. Quando as organizações coletam números de telefone por formulários de cadastro, campanhas de geração de leads ou portais de atendimento ao cliente, esses números muitas vezes não trazem contexto sobre a presença deles em plataformas de mensagens. Ao verificar esses números de forma programática antes de iniciar o contato, as equipes de operações podem segmentar suas listas de contatos com base no registro ativo na plataforma. Esse processo apoia a limpeza de listas de leads ao identificar quais registros estão associados a uma conta do WhatsApp e quais não estão. Além disso, orienta as decisões de roteamento automatizado. Essa abordagem programática ajuda a manter a precisão dos dados e dá às equipes o contexto necessário para estruturar seus canais de comunicação com eficácia.

Entendendo os sinais de identidade do WhatsApp

A plataforma oferece três tipos de serviço distintos em um único endpoint, permitindo que os desenvolvedores solicitem o nível de detalhe específico exigido pelo seu fluxo. Cada tipo de serviço controla quais campos são retornados na resposta JSON e qual custo de saldo se aplica.

• Verificação de registro (ws): é a verificação básica. Ela avalia o número E.164 enviado e retorna um campo registered, fornecendo um sinal direto de presença de conta na plataforma padrão do WhatsApp.
• Verificação de avatar (ws_avatar): essa verificação inclui o status básico de registro e acrescenta dados de enriquecimento de perfil. Ela retorna um booleano avatar que indica se há avatar disponível e uma string avatar_url que fica vazia quando não há URL disponível.
• Verificação de conta comercial (ws_business): projetada para a segmentação B2B, essa verificação retorna o status básico de registro junto com um booleano business. Esse sinal específico ajuda as equipes a identificar se o contato usa uma conta do WhatsApp Business.

Para uma verificação do WhatsApp concluída, o data retornado contém service_type, identifier e registered; ws_avatar também inclui avatar e avatar_url, enquanto ws_business inclui business. Campos internos de registro, transação, status e cobrança não são retornados.

Implementando fluxos de API síncronos

A integração técnica se baseia em um contrato de requisição simples e síncrono. Como os resultados são síncronos, eles são devolvidos na mesma resposta HTTP da requisição. Um CRM pode manter um registro em memória, fazer a chamada à API e aplicar imediatamente o sinal retornado ao fluxo. O contrato de requisição documentado exige o envio de uma requisição ao endpoint POST /api/v1/check. A requisição deve incluir dois cabeçalhos: X-API-Key, contendo sua chave de autenticação, e Content-Type: application/json. O corpo JSON deve conter dois campos:

• service_type: um valor de string ws, ws_avatar ou ws_business.
• identifier: o número de telefone formatado no padrão E.164.

Para apoiar essa integração, o painel da plataforma oferece ferramentas administrativas completas. As equipes de desenvolvimento e operações podem gerenciar chaves de API, monitorar o saldo, revisar o histórico de verificações e acessar relatórios por produto. O painel também exibe verificações recentes, métricas de consumo de saldo e a atividade da conta para ajudar a monitorar o uso da API e o volume dos fluxos.

Boas práticas para integridade dos dados e roteamento

Ao integrar verificações programáticas a um ambiente de produção, é fundamental definir expectativas precisas sobre o que os dados representam. Um resultado registrado informa os campos de status do WhatsApp disponíveis no momento exato da verificação. Ele funciona estritamente como um sinal de presença de conta. Não verifica status online, horário de visto por último, histórico de mensagens nem consentimento do contato. Verificações com falha, com timeout e indeterminadas não mantêm a cobrança. Consulte a página de preços para ver os detalhes de cobrança atuais.

Perguntas frequentes

Qual é a diferença entre uma verificação de registro e uma verificação de conta comercial?

Uma verificação de registro padrão (com o tipo de serviço ws) retorna um sinal de presença de conta que indica se o número E.164 enviado está registrado no WhatsApp. Uma verificação de conta comercial (com o tipo de serviço ws_business) retorna o mesmo status de registro, mas acrescenta um campo booleano business, que indica se a conta usa o WhatsApp Business.

Preciso configurar webhooks para as verificações do WhatsApp?

Não. Todas as verificações são síncronas. Os resultados são devolvidos na mesma resposta HTTP da requisição inicial, eliminando a necessidade de configurar webhooks ou implementar lógica de consulta periódica assíncrona na sua aplicação.

Em que formato os números de telefone devem estar para a API?

Todos os números de telefone enviados devem seguir o padrão do plano internacional de numeração telefônica E.164.

Um status registrado significa que posso enviar uma mensagem ao usuário?

Um resultado registrado é estritamente um sinal de presença de conta disponível no momento da verificação. Ele não informa presença ao vivo, histórico de mensagens, consentimento do contato nem se o número consegue receber uma mensagem com sucesso.

Como são cobradas as verificações com falha ou indeterminadas?

Verificações com falha, com timeout e indeterminadas não mantêm a cobrança. Consulte a página de preços para ver os detalhes de cobrança atuais.