Executando uma verificação em lote do WhatsApp a partir de um arquivo

Um guia passo a passo sobre tarefas assíncronas de verificação em lote do WhatsApp e como elas diferem das verificações em tempo real.

Uma verificação em lote do WhatsApp a partir de um arquivo é uma tarefa assíncrona: você faz o upload de uma lista em TXT ou CSV, recebe uma tarefa que pode ser monitorada, aguarda o processamento e baixa um arquivo de resultados quando a tarefa for concluída. Utilize este método quando a lista for muito maior do que o suportado por uma solicitação em tempo real. Para números individuais ou pequenos grupos que precisam de uma resposta imediata, utilize a verificação em tempo real.

Quando a verificação de arquivo em lote é a ferramenta certa

As verificações em tempo real respondem dentro da própria solicitação. Isso é ideal para formulários de cadastro, gatilhos de CRM ou pequenos grupos colados manualmente. A verificação de arquivo em lote atende à situação oposta: uma lista exportada, um banco de dados adquirido ou herdado, ou uma limpeza periódica de toda uma tabela de contatos.

A diferença prática está no fluxo de trabalho, não na pergunta feita. Com o tempo real, você obtém resultados imediatamente na resposta. Com o lote, você envia a solicitação uma vez, a tarefa é processada separadamente e você retorna para buscar a saída. Planeje as verificações em lote como um trabalho agendado, não como algo que alguém precise aguardar em uma tela.

Existem quatro produtos em lote, cada um focado em um sinal:

Cada produto possui seus próprios limites por arquivo, portanto, leia a documentação da API atual antes de dimensionar uma execução. Não presuma que os limites de um produto se aplicam a outro.

Prepare o arquivo antes de fazer o upload

A maioria das execuções em lote falhas ou ineficientes decorre do arquivo de entrada. Siga esta lista primeiro:

• Formato. Use um arquivo TXT ou CSV com um número por linha. Formatos de planilha como XLSX não são aceitos, portanto, exporte para CSV.
• Formato internacional. Forneça cada número com seu código de país, sem espaços, parênteses ou traços. Números em formato local sem o código do país não podem ser interpretados de forma confiável.
• Um país por arquivo. A lista deve ser essencialmente do país que você selecionar. Um arquivo com uma parcela significativa de números de outros países é rejeitado na pré-verificação, portanto, separe listas mistas por país primeiro.
• Remova duplicatas. Linhas repetidas são cobradas como qualquer outra, portanto, remova-as com antecedência.
• Verifique o suporte regional. Tarefas de arquivo em lote não cobrem números da China continental, Hong Kong ou Macau. Essas regiões possuem suporte limitado apenas para verificações individuais em tempo real.
• Consentimento. Confirme se você possui uma base legítima para entrar em contato com essas pessoas antes que o arquivo seja usado para qualquer tipo de abordagem.

Uma rejeição na pré-verificação é um aviso prévio útil. Ela custa apenas alguns minutos, em vez de uma execução finalizada em um arquivo ruim.

Envie a tarefa e acompanhe seu status

Você pode enviar uma tarefa em lote pelo painel ou através da API. O fluxo da API utiliza POST /api/v1/bulk-tasks para criar a tarefa e GET /api/v1/bulk-tasks/{id} para ler seu status. O painel também lista suas tarefas em lote e seus estados, o que é conveniente quando uma pessoa, e não um script, executa o trabalho.

Uma rotina sensata é:

1. Escolha o produto em lote que corresponde ao sinal de que você precisa.
2. Faça o upload do arquivo preparado e envie.
3. Guarde a referência da tarefa retornada no envio.
4. Monitore o status em um intervalo moderado ou verifique o painel, em vez de sobrecarregar o endpoint. A documentação da API descreve os controles de concorrência e tempo limite; consulte-a para as regras de uso atuais.
5. Baixe o arquivo de resultados quando a tarefa estiver concluída.

O saldo é reservado no momento do envio. Após o processamento, a parte não utilizada da reserva retorna ao saldo da sua conta, e uma tarefa com falha libera a reserva total. Isso é uma reconciliação de faturamento, não um programa de reembolso para verificações comuns. Resultados concluídos são cobrados independentemente de o número estar registrado ou não.

Leia o arquivo de resultados corretamente

O arquivo de resultados para download é um CSV com uma linha por número processado. Trate cada linha como um sinal no momento da execução:

• Um resultado Registrado significa que uma conta existia no momento da verificação.
• Um valor de foto de perfil ou comercial complementa o registro. Uma foto de perfil ausente não significa que o número não esteja registrado, e uma sinalização comercial identifica o tipo de conta, não uma empresa verificada.
• Números que não puderam ser decididos devem ser tentados novamente em uma execução posterior, em vez de tratados como Não registrado.

Carregue o arquivo de volta em seu CRM ou ferramenta de marketing, faça o cruzamento pelo número de telefone e armazene a data da verificação ao lado do resultado. Os segmentos tornam-se então filtros simples: números registrados para a fila do WhatsApp, outros para canais diferentes.

Misturando lote e tempo real em um fluxo de trabalho

A maioria das equipes acaba usando ambos. Execute uma tarefa em lote para limpar o banco de dados existente uma vez e, em seguida, use verificações em tempo real para cada novo contato que chegar posteriormente. Isso mantém a lista atualizada sem repetir grandes trabalhos. Ambos utilizam o mesmo saldo da conta, portanto, uma recarga cobre o painel, a API e as tarefas em lote. Consulte a página de preços para obter detalhes sobre o plano e o saldo atuais.

FAQ

Como as equipes podem enviar uma verificação em lote do WhatsApp?

Faça o upload de um arquivo TXT ou CSV preparado pelo painel ou crie uma tarefa através da API, acompanhe o status da tarefa e baixe o arquivo de resultados quando a tarefa estiver concluída.

Por que um arquivo em lote pode ser rejeitado na pré-verificação?

Um arquivo pode ser rejeitado quando uma grande parcela de seus números pertence a um país diferente do selecionado ou quando os números não possuem códigos de país. Separar a lista por país antes do upload evita isso.

O que acontece com o saldo reservado não utilizado após uma tarefa em lote?

O saldo é reservado no envio. Qualquer parte não utilizada retorna ao saldo da conta após o processamento, e uma tarefa com falha libera a reserva total.

Como uma verificação em lote é diferente de uma verificação em tempo real?

Uma verificação em tempo real retorna sua resposta na mesma solicitação. Uma verificação em lote retorna uma tarefa primeiro, processa o arquivo separadamente e entrega um arquivo de resultados para download posteriormente.

Saiba mais

Escolha as informações do produto que se ajustam à próxima etapa do seu fluxo de trabalho.

• Ver a documentação do produto →
• Falar com a equipe →