Skip to main content
POST
Migração do Tipo de Conexão
Use este endpoint para trocar o tipo de conexão de uma instância existente sem perder nada da sua integração: o ID da instância, os webhooks cadastrados e as configurações permanecem exatamente como estavam. A migração funciona nos dois sentidos.

Não oficial para API oficial (WABA)

Envie connection_type: "waba" junto com o objeto waba, contendo access_token, phone_number_id e waba_id.
O Embedded Signup (login com o Facebook) só está disponível pelo painel da Zapster: ele depende de uma página hospedada por nós e não pode ser reproduzido por chamada de API. Para migrar por aqui, gere um System User Token no Meta Business Manager e informe-o no objeto waba.
O ambiente de execução da conexão não oficial é desativado e o número passa a operar pela Cloud API da Meta. Ao final, a instância fica connected.

API oficial (WABA) para não oficial

Envie connection_type: "unofficial", sem credenciais. A configuração WABA é removida com segurança na Meta e um novo ambiente de conexão é preparado. A instância fica disconnected, aguardando a leitura do QR Code (ou código de pareamento) para conectar o número.

Webhooks são revalidados

Os tipos de conexão suportam conjuntos diferentes de eventos de webhook, e a API oficial suporta um conjunto menor. Antes de migrar, os webhooks já cadastrados na instância são validados contra o tipo de destino: se algum estiver inscrito em um evento que o destino não emite, a migração é rejeitada com 400 (unsupported_webhook_event), listando todos os eventos incompatíveis e os eventos válidos. Ajuste as inscrições e repita a chamada.

Confirmação para instâncias em uso

Migrar uma instância que não está disconnected interrompe o serviço dela durante a troca, mesmo quando ela está apenas offline: só a instância já disconnected dispensa a confirmação. Nesse caso, a chamada exige o header X-Confirmation-Token, com um valor que identifique a confirmação (evite reenviar sempre o mesmo texto fixo). Sem ele, a API responde 409 (confirmation_required) e nada é alterado; o corpo da resposta traz em details o contexto da ação (action, resource, from, to e status). Essa confirmação não é uma camada de segurança. Ela existe para evitar que uma migração disruptiva aconteça por engano, não para impedir chamadas mal-intencionadas.

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 quando a instância NÃO está desconectada, inclusive quando está offline: a migração interrompe o serviço dela durante a troca. Qualquer valor não vazio confirma a chamada hoje; envie um valor que identifique a confirmação, sem fixar sempre o mesmo texto. 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
connection_type
enum<string>
obrigatório

Tipo de conexão de destino:

  • unofficial: o metadata WABA é limpo e um pod é provisionado para a conexão por QR Code
  • waba: o pod é derrubado e o número é conectado pela Cloud API da Meta (exige credenciais)
Opções disponíveis:
unofficial,
waba
Exemplo:

"waba"

waba
object

Credenciais manuais da Cloud API da Meta, aceitas apenas quando connection_type é waba.

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"