Conectar WhatsApp não oficial (uazapi)

Este é o caminho rápido: o número é ligado lendo um QR code com o celular, como no WhatsApp Web. Não precisa de aprovação da Meta. Se o cliente exige a API oficial, use o caminho Datafy.

Antes de tudo: o servidor uazapi

A plataforma não vem com um servidor uazapi embutido. Os servidores são cadastrados dentro da própria plataforma, no menu UAZAPI servers.

Essa tela é só para administradores. Quem não é admin não vê o link no menu e, se tentar abrir o endereço direto, recebe um aviso amigável de “Acesso restrito”.

Cadastrar um servidor

Abra UAZAPI servers

No menu do topo do painel, clique em UAZAPI servers.

Cadastre

Informe:

Nome — um apelido único (ex.: sao-paulo).
URL — o endereço do servidor, começando por https://. Uma barra no final é removida automaticamente.
Admin token — o token administrativo do servidor. Ele é gravado e nunca mais exibido, nem logo depois de salvar.

Marque o padrão

O primeiro servidor cadastrado já vira o Padrão. Só pode existir um padrão por vez: ao promover outro, o anterior perde a marcação automaticamente.

Na tela você também pode ativar/desativar, substituir o token e remover um servidor.

Desativar não desliga quem já está conectado. Cada agent fica “grudado” no servidor onde a instância dele nasceu, porque o token da instância só vale naquele servidor. Desativar apenas impede que novos agents nasçam ali. Por isso também não dá para remover um servidor que ainda tenha agent vinculado — a plataforma recusa com a mensagem “Este item ainda está vinculado a outro recurso. Desvincule antes de remover.”

Servidor gratuito não serve para cliente real. Servidores uazapi gratuitos expiram as instâncias, e quando isso acontece o número simplesmente para de responder até alguém reconectar. Para cliente pagante, use servidor pago. Esta é uma recomendação de operação do time, não uma trava do sistema — a plataforma aceita qualquer servidor que você cadastrar.

Conectar o número

Abra o card do WhatsApp não oficial

No agent, vá em Integrations → card WhatsApp (Não oficial).

Clique em Connect

A plataforma cria a instância no servidor e devolve um QR code na tela.

Leia o QR code com o celular

No celular do número que vai atender: WhatsApp → Aparelhos conectados → Conectar um aparelho e aponte para o QR da tela.

Confirme o status

Clique em Refresh status. O card deve mostrar a conexão ativa, com o telefone e o identificador da instância parcialmente escondidos (só os últimos dígitos aparecem).

O QR code é temporário e não é guardado pelo painel. Se ele expirar antes de você ler, clique em Refresh status e depois em Connect de novo.

Para desligar o número, use Disconnect no mesmo card.

Trocar o número (ou reconectar depois de uma queda)

Este é o cenário mais comum na prática: o cliente trocou de número, ou a instância foi apagada/expirou no servidor. Antes isso deixava o agent travado, mostrando “O serviço está temporariamente instável” para sempre.

Hoje a plataforma se recupera sozinha. Ao clicar em Connect, se ela perceber que a instância guardada não existe mais no servidor, ela:

apaga as credenciais velhas;
cria uma instância nova;
devolve um QR code novo para você ler;
religa o webhook sozinha.

Você não precisa fazer nada além de clicar em Connect e ler o QR code.

A recuperação automática só acontece quando o servidor responde “essa instância não existe / esse token não vale”. Se o servidor estiver fora do ar ou dando erro temporário, a plataforma não apaga nada — de propósito: apagar credenciais de uma instância saudável só porque o servidor piscou seria muito pior. Nesse caso, espere e tente de novo.

Depois de conectar: o canal de entrada

Diferente do caminho oficial, aqui o registro do webhook é feito pela própria plataforma no momento do Connect — você não precisa colar URL em painel nenhum.

Se você usa a seção Inbound channels para organizar os vínculos, escolha o provedor uazapi no mesmo fluxo descrito em Conectar WhatsApp oficial.

Protegendo o número

O WhatsApp não pune quem responde: pune quem inicia conversa demais, rápido demais, com quem nunca escreveu. Num número não oficial (uazapi) a punição é a pior de todas — a instância simplesmente morre, e o número volta banido.

Por isso a plataforma trata os dois casos como coisas diferentes:

O que é	Exemplo	Tem limite?
Resposta — o cliente falou com você nas últimas 24 horas	O agent responde uma dúvida; o atendente humano manda um recado no meio do atendimento	Nunca. Cliente sendo atendido é sempre respondido
Envio iniciado — ninguém falou com você, ou faz mais de 24 horas	Uma rotina de follow-up; um lembrete de orçamento; a primeira mensagem para um número novo	Sim, pelos limites abaixo

Os limites que já vêm ligados

Todo agent nasce com estes valores, sem você precisar fazer nada:

Limite	Valor	Para quê
Envios iniciados por dia	200	O volume que um número saudável sustenta
Envios iniciados por hora	40	Segura a rajada — é o disparo em bloco que acende o alarme
Espaço entre mensagens	3 a 8 segundos	Ninguém digita 25 mensagens no mesmo segundo
Pausa automática por falhas	10 falhas numa hora ⇒ 1 hora parado	Falha em série costuma ser número já em apuros

Quando um envio iniciado esbarra num limite, ele não some: uma rotina é remarcada para a próxima hora (ou para o dia seguinte) e volta a tentar sozinha. As conversas em andamento continuam sendo respondidas o tempo todo, inclusive durante a pausa automática.

Se o seu agent hoje dispara mais de 200 mensagens iniciadas por dia, ele passa a parar em 200 e remarcar o excedente. Isso é proposital. Se o seu caso realmente precisa de mais, peça para a gente subir o limite desse agent — mas suba junto com o aquecimento abaixo.

Só quem já falou com você

Existe um interruptor (“só contatos conhecidos”) que recusa qualquer envio iniciado para quem nunca escreveu para o agent. Ele nasce desligado, porque hoje o envio manual pelo painel legitimamente escreve para número novo.

Recomendamos ligá-lo em qualquer agent que dispare rotina em lista — é a única regra que protege de verdade contra “mandar para quem não pediu”, que é o que gera denúncia.

Aquecimento de número novo

Número recém-criado que começa mandando 200 mensagens no primeiro dia é o caso clássico de banimento em 48 horas. A plataforma sabe fazer aquecimento: um teto diário que cresce por semana.

A tabela que sugerimos:

Semana	Envios iniciados por dia
1ª	20
2ª	50
3ª	100
4ª em diante	200 (o limite normal)

O aquecimento vem desligado e precisa ser ligado à mão, informando a data de início — peça para a gente configurar quando você conectar um número novo.

Como saber que um envio foi contido

Cada bloqueio vira uma linha no registro de auditoria (agent.outbound_blocked), com o motivo — limite diário, limite por hora, pausa por falhas, contato desconhecido. A linha guarda um código da conversa, nunca o telefone e nunca o texto.

Quando a pausa automática abre, você recebe um aviso no seu canal de avisos dizendo quantas mensagens falharam e até quando os disparos ficam parados.

Problemas comuns

Sintoma	Causa provável	O que fazer
“O serviço está temporariamente instável” ao conectar	Servidor uazapi fora do ar ou instável	Espere alguns instantes e clique em Connect de novo
Não consigo cadastrar servidor	Você não é administrador	Peça a um admin — a tela é admin-only
“Já existe um registro com esses dados” ao cadastrar servidor	Nome duplicado	Escolha outro apelido
Não consigo remover um servidor	Ainda existe agent vinculado a ele	Reconecte esses agents em outro servidor antes de remover
O número parou de responder do nada	Instância expirou no servidor (típico de servidor gratuito)	Clique em Connect e leia o QR novamente; para cliente real, migre para servidor pago
O QR não aparece / não pôde ser exibido	O código veio em formato inesperado	Clique em Refresh status e tente conectar de novo