Como preparar uma lista CSV ou TXT para verificações de números do WhatsApp em tempo real

Um guia prático de fluxo de trabalho para preparar uma lista CSV ou TXT de números de telefone para verificações de WhatsApp em tempo real: formato E.164, escolha do tipo de serviço e obtenção de sinais de presença da conta pelos endpoints síncronos individual e múltiplo.

O WA Lookup verifica a presença de contas no WhatsApp em tempo real: envie um número ao endpoint de verificação síncrono, ou até 100 números ao endpoint múltiplo síncrono POST /api/v1/batch-check, e os resultados concluídos voltam na resposta HTTP da própria requisição, sem nenhum job para aguardar. Para processar uma lista CSV ou TXT dessa forma, formate cada identificador estritamente no padrão internacional de numeração E.164, remova caracteres não numéricos e prefixos locais e escolha o tipo de serviço de que seu fluxo precisa: ws para o status básico de registro, ws_avatar para incluir a disponibilidade de avatar ou ws_business para identificar contas do WhatsApp Business. Um arquivo inteiro, muito maior do que uma requisição em tempo real, também pode ser enviado como tarefa em massa assíncrona (enviar, aguardar, baixar).

Entendendo os sinais de verificação do WhatsApp

Ao preparar uma lista CSV ou TXT para verificações em tempo real, o primeiro passo é definir qual sinal de presença da conta atende ao seu fluxo de trabalho específico. O WA Lookup oferece três tipos de serviço distintos, todos acessados pelos mesmos endpoints síncronos. O parâmetro service_type controla quais campos são retornados na resposta.

Verificação básica de registro (ws)

O tipo de serviço ws confirma se o número de telefone enviado está registrado no WhatsApp no momento. Essa verificação retorna um campo registered, fornecendo um sinal direto de presença da conta. Ele orienta decisões internas sobre quais números do seu arquivo CSV ou TXT estão associados a uma conta do WhatsApp no momento da verificação.

Verificação com enriquecimento de avatar (ws_avatar)

O tipo de serviço ws_avatar inclui a verificação básica de registro e acrescenta recursos de enriquecimento de perfil. Além do status registered, essa verificação retorna um valor booleano avatar, que indica a disponibilidade de avatar, e uma string avatar_url. O campo de URL fica vazio quando não há URL disponível. Esse contexto adicional pode ser um dado a mais, junto com outras verificações, ao revisar perfis de usuários.

Verificação de conta Business (ws_business)

O tipo de serviço ws_business verifica o registro no WhatsApp e identifica se a conta usa o WhatsApp Business. Ele retorna um valor booleano business. Esse sinal ajuda as equipes a segmentar suas listas, distinguindo contas comuns de perfis comerciais, o que permite um roteamento mais personalizado no fluxo de trabalho.

Preparando seu arquivo de dados

O requisito mais importante para processar uma lista CSV ou TXT em verificações em tempo real é a formatação correta dos dados. O WA Lookup exige que todos os números sejam enviados no formato E.164. O E.164 é um plano internacional de numeração telefônica que atribui a cada dispositivo um identificador globalmente único. Para preparar seu arquivo CSV ou TXT:

1. Inclua o código do país: todo número deve começar com o código internacional do país correspondente.
2. Remova os caracteres de formatação: elimine espaços, hifens, parênteses e quaisquer outros caracteres não numéricos da sua lista.
3. Omita os zeros à esquerda: remova prefixos locais de discagem (muitas vezes um zero à esquerda) que não fazem parte do código de discagem internacional.

Por exemplo, um número dos EUA deve ser formatado como uma sequência contínua de dígitos que começa com o código do país (por exemplo, 1). Confirmar que toda a lista segue o padrão E.164 ajuda a evitar erros de formatação durante o processo de verificação síncrona. Um arquivo de entrada limpo e padronizado é essencial para obter sinais precisos de presença da conta para cada número enviado.

Enviando sua lista para verificação

Com a lista CSV ou TXT formatada corretamente, você pode enviar os identificadores à plataforma do WA Lookup. O caminho principal é síncrono: os resultados são retornados na mesma resposta HTTP da requisição, e não entregues posteriormente. Para equipes técnicas que integram o serviço, use POST /api/v1/check para um identificador ou o endpoint múltiplo síncrono POST /api/v1/batch-check para até 100 identificadores. As duas requisições exigem um cabeçalho X-API-Key e um cabeçalho Content-Type: application/json. O corpo da verificação individual contém service_type e identifier; o corpo da verificação múltipla contém service_type e identifiers. Siga as orientações de concorrência da documentação da API. Um arquivo CSV ou TXT inteiro, muito maior do que uma requisição em tempo real, também pode ser enviado como tarefa em massa assíncrona; você escolhe o país ao qual os números pertencem no momento do envio, e a lista deve ser essencialmente desse único país. Verificações com falha, que excederam o tempo limite ou sem resultado determinado não mantêm a cobrança. Consulte a página de preços para ver os detalhes de cobrança atuais.

Interpretando seus resultados

Em uma verificação de 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. O resultado registered informa os campos de status do WhatsApp disponíveis no momento exato da verificação. É importante entender os limites desse sinal de presença da conta. Além disso, o processo de verificação não informa presença em tempo real, histórico de mensagens nem consentimento para contato. Ele também não indica se o número pode ser contatado com sucesso ou se as mensagens serão entregues. O sinal apenas informa seu banco de dados interno sobre o registro na plataforma, o que pode ser um dado a mais, junto com outras verificações, ao organizar seu CRM ou rotear registros.

Perguntas frequentes

Qual é o formato exigido para os números de telefone?

Todos os números de telefone devem ser enviados estritamente no formato E.164. Esse plano internacional de numeração exige o código do país e a remoção de todos os caracteres não numéricos, espaços e zeros locais à esquerda.

Posso verificar o status de WhatsApp Business em uma lista?

Sim. Ao selecionar o tipo de serviço ws_business, você pode verificar tanto o status básico de registro quanto se a conta usa o WhatsApp Business. Isso retorna um valor booleano específico que indica a presença de conta Business, tanto em uma verificação individual quanto em uma requisição múltipla síncrona.

O que acontece se uma verificação falhar?

Verificações com falha, que excederam o tempo limite ou sem resultado determinado não mantêm a cobrança. Consulte a página de preços para ver os detalhes de cobrança atuais.

Os resultados da verificação são entregues de forma assíncrona?

Não no caminho principal. Os endpoints síncronos individual e múltiplo retornam o resultado concluído na mesma resposta HTTP da requisição. Uma tarefa em massa assíncrona (enviar, aguardar, baixar) também está disponível como complemento para uma lista grande inteira, mas, para as verificações do dia a dia, os endpoints síncronos são o caminho recomendado.