curl --request POST \
--url https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"waba": {
"access_token": "EAAxxxxxxx...",
"phone_number_id": "1016102021584086",
"waba_id": "419378847918255"
}
}
'import requests
url = "https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect"
payload = { "waba": {
"access_token": "EAAxxxxxxx...",
"phone_number_id": "1016102021584086",
"waba_id": "419378847918255"
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
waba: {
access_token: 'EAAxxxxxxx...',
phone_number_id: '1016102021584086',
waba_id: '419378847918255'
}
})
};
fetch('https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'waba' => [
'access_token' => 'EAAxxxxxxx...',
'phone_number_id' => '1016102021584086',
'waba_id' => '419378847918255'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect"
payload := strings.NewReader("{\n \"waba\": {\n \"access_token\": \"EAAxxxxxxx...\",\n \"phone_number_id\": \"1016102021584086\",\n \"waba_id\": \"419378847918255\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"waba\": {\n \"access_token\": \"EAAxxxxxxx...\",\n \"phone_number_id\": \"1016102021584086\",\n \"waba_id\": \"419378847918255\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"waba\": {\n \"access_token\": \"EAAxxxxxxx...\",\n \"phone_number_id\": \"1016102021584086\",\n \"waba_id\": \"419378847918255\"\n }\n}"
response = http.request(request)
puts response.read_body{
"created_at": "2024-10-03T21:56:22.620Z",
"id": "xy9rexnkwobmgg3tehgvs",
"metadata": {
"customer_id": "123456",
"customer_name": "Joãozinho",
"phone_number": "+5587989075555"
},
"name": "MyNewInstance2",
"owner": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"display_name": null
},
"settings": {
"call_rejection": "all",
"delay_per_word": true,
"delete_chat_after_sent": true,
"message_delay": {
"enabled": true,
"max": 10,
"min": 1
},
"presence_behavior": "only_composing",
"read_confirmation": "never"
},
"status": "disconnected",
"webhooks": [
{
"enabled": true,
"events": [
"message.received"
],
"id": "2nenz69l0xbf0m3uu9tfo",
"name": "Webhook Name",
"test_mode": false,
"url": "https://webhook.mydomain.com",
"test_url": null
}
],
"connection_type": "unofficial",
"qrcode": null,
"lookup_key": "ins_8j7wlxmpjlixx9mux5"
}{
"errors": [
{
"code": "invalid_type",
"message": "WABA access token is required."
}
]
}{
"errors": [
{
"code": "waba_invalid_token",
"message": "The provided WABA access token is invalid or has expired. Please verify your credentials."
}
]
}{
"errors": [
{
"code": "instance_not_found",
"message": "Instance not found."
}
]
}{
"errors": [
{
"code": "confirmation_required",
"message": "This action interrupts the service of an instance that is currently \"connected\". Resend the request with the confirmation token to proceed.",
"details": {
"action": "instance.reconnect",
"confirmation_token": "eyJ2IjoxLCJhY3QiOiJpbnN0YW5jZS5yZWNvbm5lY3QifQ.q1w2e3r4t5y6",
"expires_at": "2026-08-08T18:35:00.000Z",
"resource": "ozj35qv418rpmlrb",
"from": "5511999999999",
"to": "5511888888888",
"status": "connected",
"reason": "malformed"
}
}
]
}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.
curl --request POST \
--url https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"waba": {
"access_token": "EAAxxxxxxx...",
"phone_number_id": "1016102021584086",
"waba_id": "419378847918255"
}
}
'import requests
url = "https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect"
payload = { "waba": {
"access_token": "EAAxxxxxxx...",
"phone_number_id": "1016102021584086",
"waba_id": "419378847918255"
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
waba: {
access_token: 'EAAxxxxxxx...',
phone_number_id: '1016102021584086',
waba_id: '419378847918255'
}
})
};
fetch('https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'waba' => [
'access_token' => 'EAAxxxxxxx...',
'phone_number_id' => '1016102021584086',
'waba_id' => '419378847918255'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect"
payload := strings.NewReader("{\n \"waba\": {\n \"access_token\": \"EAAxxxxxxx...\",\n \"phone_number_id\": \"1016102021584086\",\n \"waba_id\": \"419378847918255\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"waba\": {\n \"access_token\": \"EAAxxxxxxx...\",\n \"phone_number_id\": \"1016102021584086\",\n \"waba_id\": \"419378847918255\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"waba\": {\n \"access_token\": \"EAAxxxxxxx...\",\n \"phone_number_id\": \"1016102021584086\",\n \"waba_id\": \"419378847918255\"\n }\n}"
response = http.request(request)
puts response.read_body{
"created_at": "2024-10-03T21:56:22.620Z",
"id": "xy9rexnkwobmgg3tehgvs",
"metadata": {
"customer_id": "123456",
"customer_name": "Joãozinho",
"phone_number": "+5587989075555"
},
"name": "MyNewInstance2",
"owner": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"display_name": null
},
"settings": {
"call_rejection": "all",
"delay_per_word": true,
"delete_chat_after_sent": true,
"message_delay": {
"enabled": true,
"max": 10,
"min": 1
},
"presence_behavior": "only_composing",
"read_confirmation": "never"
},
"status": "disconnected",
"webhooks": [
{
"enabled": true,
"events": [
"message.received"
],
"id": "2nenz69l0xbf0m3uu9tfo",
"name": "Webhook Name",
"test_mode": false,
"url": "https://webhook.mydomain.com",
"test_url": null
}
],
"connection_type": "unofficial",
"qrcode": null,
"lookup_key": "ins_8j7wlxmpjlixx9mux5"
}{
"errors": [
{
"code": "invalid_type",
"message": "WABA access token is required."
}
]
}{
"errors": [
{
"code": "waba_invalid_token",
"message": "The provided WABA access token is invalid or has expired. Please verify your credentials."
}
]
}{
"errors": [
{
"code": "instance_not_found",
"message": "Instance not found."
}
]
}{
"errors": [
{
"code": "confirmation_required",
"message": "This action interrupts the service of an instance that is currently \"connected\". Resend the request with the confirmation token to proceed.",
"details": {
"action": "instance.reconnect",
"confirmation_token": "eyJ2IjoxLCJhY3QiOiJpbnN0YW5jZS5yZWNvbm5lY3QifQ.q1w2e3r4t5y6",
"expires_at": "2026-08-08T18:35:00.000Z",
"resource": "ozj35qv418rpmlrb",
"from": "5511999999999",
"to": "5511888888888",
"status": "connected",
"reason": "malformed"
}
}
]
}disconnected para chamar este endpoint. O comportamento muda conforme a situação:
| Situação | O que acontece |
|---|---|
Instância disconnected | Reconecta normalmente, sem exigir confirmação |
Instância em uso, mesmo phone_number_id | Rotaciona as credenciais (ex.: token revogado no Meta Business Manager), sem exigir confirmação |
Instância em uso, phone_number_id diferente | Aponta a instância para outro número, exige o header X-Confirmation-Token |
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.
curl -X POST https://api.zapsterapi.com/v1/wa/instances/ozj35qv418rpmlrb/reconnect \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"waba": {
"access_token": "EAAxxxxxxx...",
"phone_number_id": "1016102021584086",
"waba_id": "419378847918255"
}
}'
# Trocando o número da instância, com o token de confirmação:
curl -X POST https://api.zapsterapi.com/v1/wa/instances/ozj35qv418rpmlrb/reconnect \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Confirmation-Token: eyJ2IjoxLCJhY3QiOiJpbnN0YW5jZS5yZWNvbm5lY3QifQ.q1w2e3r4t5y6" \
-d '{
"waba": {
"access_token": "EAAxxxxxxx...",
"phone_number_id": "1016102099998765",
"waba_id": "419378847918255"
}
}'
const instanceId = 'ozj35qv418rpmlrb'
const response = await fetch(
`https://api.zapsterapi.com/v1/wa/instances/${instanceId}/reconnect`,
{
method: 'POST',
headers: {
Authorization: 'Bearer SEU_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({
waba: {
access_token: 'EAAxxxxxxx...',
phone_number_id: '1016102021584086',
waba_id: '419378847918255',
},
}),
},
)
const instance = await response.json()
console.log(instance.status) // connected
import axios from 'axios'
const instanceId = 'ozj35qv418rpmlrb'
const { data: instance } = await axios.post(
`https://api.zapsterapi.com/v1/wa/instances/${instanceId}/reconnect`,
{
waba: {
access_token: 'EAAxxxxxxx...',
phone_number_id: '1016102021584086',
waba_id: '419378847918255',
},
},
{ headers: { Authorization: 'Bearer SEU_TOKEN' } },
)
console.log(instance.status) // connected
// Nunca chame a Zapster direto do navegador: o seu token daria acesso total
// à conta a quem abrisse o DevTools. Chame o seu próprio backend, e é ele
// quem fala com a Zapster usando o token guardado no servidor.
const response = await fetch('/api/instancias/ozj35qv418rpmlrb/reconectar', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
access_token: 'EAAxxxxxxx...',
phone_number_id: '1016102021584086',
waba_id: '419378847918255',
}),
})
const instance = await response.json()
console.log(instance.status) // connected
import requests
instance_id = "ozj35qv418rpmlrb"
response = requests.post(
f"https://api.zapsterapi.com/v1/wa/instances/{instance_id}/reconnect",
headers={"Authorization": "Bearer SEU_TOKEN"},
json={
"waba": {
"access_token": "EAAxxxxxxx...",
"phone_number_id": "1016102021584086",
"waba_id": "419378847918255",
}
},
timeout=30,
)
instance = response.json()
print(instance["status"]) # connected
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
instanceID := "ozj35qv418rpmlrb"
body, _ := json.Marshal(map[string]any{
"waba": map[string]string{
"access_token": "EAAxxxxxxx...",
"phone_number_id": "1016102021584086",
"waba_id": "419378847918255",
},
})
url := fmt.Sprintf(
"https://api.zapsterapi.com/v1/wa/instances/%s/reconnect",
instanceID,
)
req, _ := http.NewRequest(http.MethodPost, url, bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer SEU_TOKEN")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var instance map[string]any
json.NewDecoder(res.Body).Decode(&instance)
fmt.Println(instance["status"]) // connected
}
<?php
$instanceId = 'ozj35qv418rpmlrb';
$payload = json_encode([
'waba' => [
'access_token' => 'EAAxxxxxxx...',
'phone_number_id' => '1016102021584086',
'waba_id' => '419378847918255',
],
]);
$ch = curl_init("https://api.zapsterapi.com/v1/wa/instances/{$instanceId}/reconnect");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer SEU_TOKEN',
'Content-Type: application/json',
],
]);
$instance = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $instance['status']; // connected
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class ReconnectInstance {
public static void main(String[] args) throws Exception {
String instanceId = "ozj35qv418rpmlrb";
String payload = """
{
"waba": {
"access_token": "EAAxxxxxxx...",
"phone_number_id": "1016102021584086",
"waba_id": "419378847918255"
}
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(
"https://api.zapsterapi.com/v1/wa/instances/"
+ instanceId + "/reconnect"))
.header("Authorization", "Bearer SEU_TOKEN")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
{
"customer_id": "123456",
"customer_name": "Joãozinho",
"phone_number": "+5587989075555"
}
Nome da instância.
"MyNewInstance2"
Informações sobre o proprietário da instância.
Show child attributes
Show child attributes
Objeto opcional de configurações da sua instância.
Show child attributes
Show child attributes
Status atual da instância
connected, disconnected, offline "disconnected"
Lista de webhooks configurados para esta instância.
Show child attributes
Show child attributes
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"