Ciclo de vida da instância
Criação, pareamento, estados, reinício e desvinculação.
Uma instância representa a sessão de WhatsApp de uma empresa em um servidor. Criação, conexão, reinício e exclusão têm efeitos diferentes.
Fluxo de integração
| Etapa | Operação | Resultado esperado |
|---|---|---|
| Criar | POST /instance/init | ID e token; estado disconnected |
| Preparar eventos | POST /v1/webhook | Destino global herdado pela instância |
| Conectar | POST /instance/connect | Início de conexão, QR ou código de pareamento |
| Acompanhar | GET /instance/status | Estado, connected, loggedIn e resumo de webhook |
| Reiniciar sessão | POST /instance/restart | Retoma a sessão com credenciais guardadas |
| Desvincular | POST /instance/disconnect | Remove a credencial local e tenta desvincular remotamente |
| Excluir | DELETE /instance | Remove a instância e seus dados associados |
Criação e vínculo
O cadastro usa admintoken. name é obrigatório; systemName e companyId ajudam a identificar a integração. Guarde o vínculo servidor → empresa → ID de instância no backend do Atendro.
kind é fixado na criação: whatsapp (padrão) para mensagens e calls para voz. A instância de ligação tem pareamento próprio e pode usar um número dedicado ou outro dispositivo vinculado do mesmo número.
O campo companyId não concede autorização automaticamente. A aplicação deve validar o vínculo em cada ação e em cada evento recebido.
Estados da sessão
| Estado | Significado |
|---|---|
disconnected | Não há sessão autenticada disponível para as operações |
connecting | Pareamento ou conexão em andamento |
connected | Sessão conectada; considere também connected e loggedIn na resposta |
O QR é temporário. Mostre-o apenas ao usuário autorizado e consulte o status para obter uma versão vigente. Não registre QR, código de pareamento ou chaves de sessão.
Webhook de conexão
O evento connection informa mudanças de estado. Configure a inscrição antes de iniciar o pareamento, porque uma URL nova começa a receber eventos após seu cadastro.
qrcode é aceito por compatibilidade, mas não é entregue. Obtenha o QR pelo fluxo privado de connect/status. Veja payloads dos eventos.
Reinício e desconexão
restart preserva a credencial de sessão. disconnect limpa a credencial local mesmo quando unlinked é false; nesse caso, a confirmação remota da desvinculação não ocorreu.
O reinício administrativo do worker em POST /admin/restart devolve 202 e agenda o trabalho em background. Ele não retorna uma contagem de sessões já reiniciadas.
Sessões distribuídas
Cada sessão tem um worker dono e um lease. 409 session_owned_elsewhere indica que a sessão está sob responsabilidade de outro worker; não crie outra instância para contornar o erro.
Uma instância conectada permite apenas os recursos anunciados por GET /v1/capabilities. Conexão não implica suporte a chamadas de voz.