Instâncias e sessões na UAZAPI
Uma automação que envia para um número desconectado falha sem explicar o motivo. Na UAZAPI, a instância guarda e controla a sessão do WhatsApp no servidor da API. Com o token dessa instância, você consulta o estado da conexão, como connected ou disconnected, antes de enviar mensagens pelo número pareado.
Ficha e sumário da página
- Referência técnica
- UAZAPI 2.6.9
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
Servidor, instância e número são objetos diferentes
O servidor é o ambiente acessado pela Server URL. Dentro dele, a UAZAPI mantém instâncias com configurações próprias. O número de WhatsApp entra nessa relação quando uma instância conclui o pareamento. Você pode encontrar uma instância criada que ainda não tem uma conexão ativa, pois criar o recurso e conectar o aplicativo são ações distintas. O nome usado no painel identifica visualmente a sessão, mas não substitui sua credencial de acesso.
Essa separação aparece no seu app quando você atende mais de uma empresa. Cada empresa precisa acessar somente as instâncias autorizadas pelo seu backend. Uma lista visual que esconde outros números não faz essa conferência nas requisições. Se o navegador envia um identificador de instância, o backend verifica o vínculo antes de recuperar o token correspondente. Assim, a autorização acompanha a chamada ao servidor, além da apresentação do painel que você entrega ao cliente.
O pareamento estabelece a sessão
A documentação descreve conexão por QR Code ou código de pareamento. Esses recursos ligam a instância ao WhatsApp. Até a conclusão desse processo, o cadastro da instância não significa que as mensagens já podem sair. O seu sistema consulta o estado para distinguir uma sessão ainda em conexão de uma sessão disponível. O pareamento também exige cuidado com as telas exibidas: compartilhar uma captura desse processo pode permitir acesso indevido ao número que você está conectando.
Servidor
A Server URL identifica o ambiente da API.
Instância
O recurso possui token e configuração próprios.
Pareamento
QR Code ou código associa a sessão ao número.
Conexão
connectedA sessão autenticada recebe chamadas para mensagens.
O fornecedor recomenda o aplicativo WhatsApp Business no contrato da API 2.6.9. Essa recomendação trata da compatibilidade descrita pela UAZAPI. Ela não transforma a sessão pareada na plataforma oficial da Meta nem garante aceitação de toda mensagem. A uazapi mantém um serviço proprietário, sem licença aberta do servidor publicada nas fontes consultadas. As condições do WhatsApp continuam relevantes mesmo quando o painel informa uma conexão ativa e o token passa na autenticação.
O que os estados informam
O estado disconnected indica ausência de conexão ativa. Em connecting,
a sessão está conectando ou aguardando pareamento. O estado connected
informa uma sessão conectada. Já hibernated representa uma sessão pausada
com credenciais preservadas. Essas diferenças permitem que o seu app
apresente a situação real do número e evite mostrar um envio como concluído
apenas porque o cadastro da instância existe no servidor.
Você consulta a sessão em /instance/status. O retorno descreve a conexão
naquele momento, mas a chamada seguinte ainda tem resposta própria.
Uma mudança de rede ou uma recusa da plataforma pode ocorrer entre as duas
requisições. Por isso, o fluxo também interpreta o resultado do envio.
O evento connection complementa a consulta quando você precisa receber
mudanças de estado no seu sistema sem consultar a API continuamente.
O token escolhe o alcance da chamada
O header token autoriza ações da instância, como trabalhar com mensagens,
chats e webhooks associados à sessão. O header admintoken permite ações
administrativas sobre o servidor. Ao usar a credencial administrativa num
componente que só precisa enviar mensagens, você entrega acesso maior que
o necessário para aquela função. No fluxo de um cliente, o token da
instância mantém o alcance da requisição limitado à sessão correspondente.
Uma credencial enviada ao navegador pode ser lida por ferramentas de desenvolvimento, extensões e scripts da página. A documentação admite cenários de painel pessoal com acesso direto, mas recomenda o backend para um SaaS que atende clientes diferentes. Você guarda a credencial nesse backend e faz a autorização antes de chamar a UAZAPI. Colocar um token numa variável pública do frontend apenas muda a forma de distribuí-lo.
A troca de credencial afeta os consumidores
A rotação do token substitui a credencial usada pelas chamadas. As automações que ainda enviam o valor anterior deixam de autenticar como antes. O n8n, o backend do app e outros consumidores precisam acompanhar essa troca. A documentação também orienta retirar tokens dos logs e dos registros de análise. Uma falha de autenticação pode ser investigada pela operação, pelo status HTTP e pelo identificador interno da instância, sem guardar a credencial junto ao erro.
O endereço do servidor continua fazendo parte da conferência. Um token correto enviado ao ambiente errado não encontra automaticamente a sessão original. A Server URL também é diferente da URL do webhook, que pertence ao seu sistema. Quando você separa esses dois sentidos de comunicação, consegue distinguir um erro ao chamar a API de uma falha na entrega dos eventos de conexão para o seu receptor.
A sessão participa da continuidade das conversas
Uma automação precisa tratar o período sem conexão como uma situação visível. Respostas pendentes e mensagens recebidas não devem ser confundidas com uma conversa encerrada. O histórico do seu app registra os estados confirmados, enquanto a consulta à API informa a situação da sessão. Com esses registros, você localiza a parte interrompida antes de repetir chamadas que podem gerar novas mensagens.
O significado dos retornos de envio está em mensagens e mídias. A forma como o receptor distingue cada ocorrência da conexão e das conversas está em webhooks e eventos. A sessão fornece o acesso ao número, enquanto o seu sistema mantém o vínculo entre esse número e os atendentes autorizados a atender suas conversas.