Criar conta

Tenha certeza de queo número tem WhatsAppantes de enviar.

Você manda a lista como está no cadastro. O Preenvia pergunta ao próprio WhatsApp se existe conta em cada número e devolve o formato exato para enviar, com ou sem o nono dígito.

Criar contaLer a documentação
Lista de envio4 números
  1. (31) 98888-7777tem WhatsApp 553188887777 registrada sem o 9
  2. (11) 97777-0000sem WhatsAppnão enviar
  3. (21) 96666-5555tem WhatsApp 5521966665555 registrada com o 9
  4. (41) 1234-56número inválidocorrigir o cadastro
2 com WhatsApp · 1 sem WhatsApp · 1 inválidoExemplo com números fictícios

Dois jeitos de o envio falhar antes de começar.

Os dois aparecem só depois do disparo, quando a mensagem já foi perdida.

not_on_whatsapp

O número não tem WhatsApp

Cadastro desatualizado ou número digitado errado. A mensagem é disparada e não chega a ninguém. Conferindo antes, esse contato vai para outro canal.

valid · sem o 9

Tem WhatsApp, mas em outro formato

Contas criadas antes do nono dígito podem continuar registradas sem ele. O cadastro está com 9, a mensagem vai para o número com 9 e o envio falha. O Preenvia devolve o formato em que a conta existe.

Um número, do cadastro ao envio.

Uma chamada de API por lista. O mesmo caminho vale para cada número que você mandar.

  1. Chega do seu cadastro(31) 98888-7777Do jeito que estiver: máscara, espaço, parênteses, com ou sem DDI.
  2. Normalizado5531988887777Só dígitos, com o DDI do Brasil.
  3. Perguntas ao WhatsApp5531988887777 · 553188887777Celular brasileiro é consultado com o 9 e sem o 9.
  4. Resposta do WhatsAppexiste conta, sem o 9Quem responde é o próprio WhatsApp, não uma regra fixa por DDD.
  5. Você envia para553188887777O campo send_to traz o destino exato. É para ele que a mensagem vai.

Resultados recentes ficam em cache por um período configurado. Consultar de novo o mesmo número não gera nova consulta ao WhatsApp.

Cinco respostas possíveis.

Cada número volta com um status. Seu sistema de envio decide com base nele.

statusO que significaO que fazer
validExiste conta de WhatsApp no número.Enviar para send_to, nunca para o número digitado.
not_on_whatsappNão existe conta de WhatsApp, nem com 9 nem sem 9.Não enviar por WhatsApp. Usar outro canal.
ambiguousCom 9 e sem 9 são duas contas diferentes.Não enviar. Encaminhar para revisão humana.
invalid_numberO formato do número não é válido.Corrigir o cadastro na origem.
unknownNão foi possível consultar agora.Não enviar. Tentar de novo mais tarde.

Regra de integração: envie somente quando status for valid, e sempre para send_to.

Uma requisição, uma resposta.

API REST com chave por cliente. Listas pequenas respondem na hora; listas grandes vão em lote.

POST /v1/validaterequisição
curl -X POST https://<seu-host>/v1/validate \
  -H "X-API-Key: $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["(31) 98888-7777"]}'
200 OKresposta ilustrativa
{
  "request_id": "9f2c1a7b3e4d5f60",
  "results": [{
    "input":      "(31) 98888-7777",
    "normalized": "5531988887777",
    "status":     "valid",
    "has_whatsapp": true,
    "send_to":    "553188887777",
    "variant":    "without_9"
  }]
}
Lotes assíncronos
Mande milhares de números, acompanhe o progresso e busque os resultados paginados quando terminar.
Idempotência
O mesmo pedido com a mesma Idempotency-Key devolve o mesmo lote, sem gastar a quota de novo.
Quota por cliente
Limites diário e mensal. Consultas que não puderam ser feitas voltam para a quota.
Limite de requisições
Passou do ritmo permitido, a resposta é 429 com Retry-After dizendo quando tentar de novo.

Ver a referência completa da API

Não guarda o que não precisa.

O serviço confere os números sem montar uma base com os telefones dos seus destinatários.

Nenhum telefone no cache

A chave do cache é um HMAC do número. O uso por cliente é guardado só como contagem diária.

Lotes com prazo para sumir

Os números de um lote ficam guardados só enquanto ele existe e são apagados ao fim da retenção configurada.

Chave exibida uma única vez

A chave de API aparece só na criação. No banco ficam o hash e um prefixo para identificação.

Acesso cortado na hora

Revogar uma chave ou desativar um cliente interrompe o acesso imediatamente.

Hoje, WhatsApp. Depois, e-mail.

A mesma API e a mesma regra de envio vão valer para os próximos canais.

  • disponível

    WhatsApp

    Se existe conta no número e em qual formato ela está registrada, incluindo o caso do nono dígito.

  • planejado

    E-mail

    Validação de endereços antes do envio. Ainda sem data definida.

Confira a próxima lista antes de enviar.

Crie a conta, compre créditos e gere a chave de API. Cada número consultado usa 1 crédito. Volume maior ou contrato: fale com o time comercial.

Criar contaVer a documentação