Skip to main content
POST
Reconexão de Instância WABA
Use este endpoint para reconectar uma instância da API oficial (WABA) sem precisar excluí-la e criar outra. O ID da instância, os webhooks cadastrados e as configurações permanecem exatamente como estavam: você só fornece novamente as credenciais do número. Diferente do que valia antes, a instância não precisa estar disconnected para chamar este endpoint. O comportamento muda conforme a situação: Rotacionar as credenciais do mesmo número é uma operação segura e idempotente, e é o caso mais comum: um token revogado no Meta Business Manager, por exemplo. Já apontar a instância para outro número é o único caso realmente arriscado, pois o ID, os webhooks e as configurações continuam os mesmos, mas a instância passa a atender por um número diferente. Por isso só esse caso pede confirmação: uma confirmação que aparecesse em toda chamada viraria um clique automático e deixaria de proteger qualquer coisa.

Credenciais

Envie o objeto waba 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.
Se o número foi conectado pelo login com o Facebook, em vez de um token gerado no Meta Business Manager, faça a reconexão pelo painel da Zapster. Esse login precisa acontecer em uma página hospedada por nós e não pode ser reproduzido por chamada de API.

O que acontece na reconexão

Você não precisa refazer nada do que já estava configurado. Ao receber as credenciais, a Zapster:
  1. Confere o token com a Meta, para garantir que ele é válido e tem acesso ao número informado.
  2. Guarda as credenciais com segurança, criptografadas.
  3. 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.
  4. Conclui o registro do número na Meta, quando ainda for necessário.
Terminado isso, a instância volta ao status 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 um phone_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:
  1. 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 em details.confirmation_token um token já pronto para a chamada que você acabou de tentar, junto com expires_at, from, to, status e resource. Basta repetir a chamada idêntica com esse valor no header.
  2. Peça o token antes de tentar reconectar, em POST /confirmations, informando action: "instance.reconnect", o resource (ID da instância) e params.phone_number_id com o número de destino.
Se o token estiver ausente, malformado, expirado ou não corresponder exatamente à chamada (outro 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 header X-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

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Cabeçalhos

X-Confirmation-Token
string

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

instance_id
string
obrigatório

ID da instância.

Corpo

application/json
waba
object
obrigatório

Credenciais da Cloud API da Meta do número que será reconectado.

Resposta

Success

Estrutura de uma instância registrada na API.

created_at
string<date-time>
obrigatório

Data e hora de criação da instância no formato ISO 8601.

Exemplo:

"2024-10-03T21:56:22.620Z"

id
string
obrigatório

Identificador único da instância.

Exemplo:

"xy9rexnkwobmgg3tehgvs"

metadata
object
obrigatório

Metadados adicionais armazenados como chave e valor.

Exemplo:
name
string
obrigatório

Nome da instância.

Exemplo:

"MyNewInstance2"

owner
object
obrigatório

Informações sobre o proprietário da instância.

settings
object
obrigatório

Objeto opcional de configurações da sua instância.

status
enum<string>
obrigatório

Status atual da instância

Opções disponíveis:
connected,
disconnected,
offline
Exemplo:

"disconnected"

webhooks
object[]
obrigatório

Lista de webhooks configurados para esta instância.

connection_type
enum<string>

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)
Opções disponíveis:
unofficial,
waba
Exemplo:

"unofficial"

qrcode
string | null

QR Code da instância, caso disponível.

Exemplo:

null

lookup_key
string

Identificador de pesquisa criado anteriormente.

Exemplo:

"ins_8j7wlxmpjlixx9mux5"