Reconectando uma Instância WABA
Reconecta uma instância WABA, rotacionando as credenciais ou apontando o mesmo ID para outro número, preservando os webhooks e as configurações.
disconnected para chamar este endpoint. O comportamento muda conforme a situação:
Credenciais
Envie o objetowaba com access_token, phone_number_id e waba_id — os mesmos campos aceitos na criação de instância. Campos opcionais como app_id, app_secret, webhook_verify_token e auth_method também são aceitos.
O que acontece na reconexão
Você não precisa refazer nada do que já estava configurado. Ao receber as credenciais, a Zapster:- Confere o token com a Meta, para garantir que ele é válido e tem acesso ao número informado.
- Guarda as credenciais com segurança, criptografadas.
- Aponta as mensagens do número de volta para a sua instância, para que os webhooks voltem a chegar no endereço que você já tinha cadastrado.
- Conclui o registro do número na Meta, quando ainda for necessário.
connected e volta a enviar e receber normalmente. Como o ID não muda, nada precisa ser alterado no seu código.
Se alguma etapa falhar (token inválido, por exemplo), a instância permanece no estado anterior e a resposta traz o motivo. Basta corrigir e chamar de novo.
Confirmação para trocar o número da instância
Apontar uma instância em uso para umphone_number_id diferente do atual exige o header X-Confirmation-Token.
Esse token não é um valor arbitrário: é assinado pela própria API e vinculado ao usuário autenticado, à ação (instance.reconnect), à instância e ao phone_number_id de destino. Um token obtido para um número não confirma a troca para outro. Ele expira em cerca de 5 minutos.
Existem duas formas de obter o token, e ambas produzem o mesmo resultado:
- Chame o endpoint sem o header. Se as credenciais enviadas apontam para um número diferente do atual, a resposta é
409(confirmation_required), e o corpo traz emdetails.confirmation_tokenum token já pronto para a chamada que você acabou de tentar, junto comexpires_at,from,to,statuseresource. Basta repetir a chamada idêntica com esse valor no header. - Peça o token antes de tentar reconectar, em
POST /confirmations, informandoaction: "instance.reconnect", oresource(ID da instância) eparams.phone_number_idcom o número de destino.
phone_number_id, por exemplo), a API responde com o mesmo 409 e um token novo pronto para uso. O campo details.reason existe só para depuração: o fluxo do cliente é sempre “recebi 409, pego o token, tento de novo”, nunca uma decisão baseada no motivo.
Essa confirmação não é uma camada de segurança. Quem tem o token de acesso da conta sempre consegue emitir uma confirmação; ela existe para tornar deliberada uma troca de número que aconteceria por engano, não para impedir chamadas mal-intencionadas.
Exemplos
Os exemplos abaixo cobrem o caso mais comum: rotacionar as credenciais do mesmo número, que não exige o headerX-Confirmation-Token. Para apontar a instância a outro número, adicione o header com o token obtido conforme a seção anterior.
Autorizações
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Cabeçalhos
Token de confirmação, obrigatório apenas quando a instância está em
uso E as credenciais enviadas apontam para um phone_number_id
diferente do que ela serve atualmente. Rotacionar as credenciais do
mesmo número, ou reconectar uma instância disconnected, nunca exige
este header. É um token opaco assinado pela própria API, vinculado
ao usuário autenticado, à ação e ao número de destino, com validade
de cerca de 5 minutos. Obtenha-o em details.confirmation_token, na
resposta 409 desta mesma chamada sem o header, ou antecipadamente
em POST /confirmations. Sem o header nessa situação, a API
responde 409 (confirmation_required).
Parâmetros de caminho
ID da instância.
Corpo
Credenciais da Cloud API da Meta do número que será reconectado.
Resposta
Success
Estrutura de uma instância registrada na API.
Data e hora de criação da instância no formato ISO 8601.
"2024-10-03T21:56:22.620Z"
Identificador único da instância.
"xy9rexnkwobmgg3tehgvs"
Metadados adicionais armazenados como chave e valor.
Nome da instância.
"MyNewInstance2"
Informações sobre o proprietário da instância.
Objeto opcional de configurações da sua instância.
Status atual da instância
connected, disconnected, offline "disconnected"
Lista de webhooks configurados para esta instância.
Tipo de conexão da instância:
unofficial: conexão via QR code (padrão)waba: conexão via API oficial do WhatsApp (Cloud API da Meta)
unofficial, waba "unofficial"
QR Code da instância, caso disponível.
null
Identificador de pesquisa criado anteriormente.
"ins_8j7wlxmpjlixx9mux5"