> ## Documentation Index
> Fetch the complete documentation index at: https://developer.zapsterapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Reconectando uma Instância WABA
> Reconecta uma instância WABA desconectada, preservando o ID, os webhooks e as configurações.
Use este endpoint para reconectar uma instância da API oficial (WABA) que foi desconectada, 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.
Apenas instâncias com status `disconnected` podem ser reconectadas. Se a instância ainda estiver conectada, desconecte-a primeiro ou continue usando-a normalmente.
### 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 continua desconectada e a resposta traz o motivo. Basta corrigir e chamar de novo.
### Exemplos
```bash cURL theme={null}
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"
}
}'
```
```javascript Node.js (fetch) theme={null}
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
```
```javascript Node.js (axios) theme={null}
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
```
```javascript JavaScript (navegador) theme={null}
// 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
```
```python Python theme={null}
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
```
```go Go theme={null}
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 PHP theme={null}
[
'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
```
```java Java theme={null}
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 response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
```
## OpenAPI
````yaml POST /wa/instances/{instance_id}/reconnect
openapi: 3.1.0
info:
title: Zapster API
description: ''
version: 1.0.0
servers:
- url: https://api.zapsterapi.com/v1
description: Produção
security: []
tags: []
paths:
/wa/instances/{instance_id}/reconnect:
post:
tags: []
summary: Reconexão de Instância WABA
description: >
Reconecta uma instância WABA desconectada, preservando o ID, os webhooks
e as configurações.
parameters:
- name: instance_id
in: path
description: ID da instância.
required: true
example: ozj35qv418rpmlrb
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- waba
properties:
waba:
type: object
description: >
Credenciais da Cloud API da Meta do número que será
reconectado.
properties:
access_token:
type: string
description: >
Token de acesso da Meta Cloud API. Pode ser um System
User Token
(gerado no Meta Business Manager) ou obtido via Embedded
Signup (OAuth).
example: EAAxxxxxxx...
phone_number_id:
type: string
description: >-
ID do número de telefone cadastrado na Meta Business
Platform
example: '1016102021584086'
waba_id:
type: string
description: ID da conta WhatsApp Business (WABA) na Meta
example: '419378847918255'
auth_method:
type: string
enum:
- system_user_token
default: system_user_token
description: >
Opcional. Como o `access_token` foi obtido. Aqui o único
valor aceito é `system_user_token` (token gerado no Meta
Business Manager), que também é o padrão quando omitido.
Este campo define qual segredo a Zapster usa para
validar
a assinatura dos webhooks que a Meta envia. Informe
`app_secret` junto se o token pertence ao seu próprio
app
Meta, para que a validação seja feita contra ele.
example: system_user_token
app_id:
type: string
description: >
Opcional. ID do app Meta do cliente (BYO-app), quando o
`access_token` é um System User Token gerado no app Meta
do
próprio cliente. Usado apenas para
identificação/auditoria —
não é segredo e não participa da validação de
assinatura.
example: '1234567890123456'
app_secret:
type: string
description: >
Opcional, recomendado para BYO-app. App Secret do app
Meta
do cliente, usado para validar a assinatura HMAC
(`X-Hub-Signature-256`) dos webhooks de entrada.
Armazenado
criptografado em repouso (AES-256).
example: a1b2c3d4e5f6...
webhook_verify_token:
type: string
description: |
Opcional. Token de verificação de webhook fornecido pelo
cliente. Se omitido, a Zapster gera um token aleatório.
Armazenado criptografado em repouso (AES-256).
example: meu-verify-token
required:
- access_token
- phone_number_id
- waba_id
example:
waba:
access_token: EAAxxxxxxx...
phone_number_id: '1016102021584086'
waba_id: '419378847918255'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Instance'
'400':
description: Erro de validação no corpo da requisição
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
description: Código do erro
example: invalid_type
message:
type: string
description: Mensagem de erro
example: WABA access token is required.
'401':
description: Token de acesso da Meta inválido ou expirado
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
example: waba_invalid_token
message:
type: string
example: >-
The provided WABA access token is invalid or has
expired. Please verify your credentials.
'404':
description: Instância não encontrada ou não pertence ao usuário
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
example: instance_not_found
message:
type: string
example: Instance not found.
'409':
description: A instância não está desconectada
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
example: instance_not_disconnected
message:
type: string
example: >-
The instance must be disconnected to perform this
action. Current status: "connected".
deprecated: false
security:
- bearer: []
components:
schemas:
Instance:
type: object
description: Estrutura de uma instância registrada na API.
properties:
created_at:
type: string
format: date-time
description: Data e hora de criação da instância no formato ISO 8601.
example: '2024-10-03T21:56:22.620Z'
id:
type: string
description: Identificador único da instância.
example: xy9rexnkwobmgg3tehgvs
metadata:
type: object
description: Metadados adicionais armazenados como chave e valor.
additionalProperties:
oneOf:
- type: string
- type: number
example:
customer_id: '123456'
customer_name: Joãozinho
phone_number: '+5587989075555'
connection_type:
type: string
enum:
- unofficial
- waba
description: |
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)
example: unofficial
name:
type: string
description: Nome da instância.
example: MyNewInstance2
owner:
type: object
description: Informações sobre o proprietário da instância.
properties:
display_name:
type: string
nullable: true
description: Nome de exibição do proprietário. Pode ser nulo.
example: null
id:
type: string
format: uuid
description: Identificador único do proprietário.
required:
- id
qrcode:
type: string
nullable: true
description: QR Code da instância, caso disponível.
example: null
settings:
$ref: '#/components/schemas/InstanceSettings'
status:
type: string
enum:
- connected
- disconnected
- offline
description: Status atual da instância
example: disconnected
webhooks:
type: array
description: Lista de webhooks configurados para esta instância.
items:
type: object
description: Configuração de um webhook associado à instância.
properties:
enabled:
type: boolean
description: Indica se o webhook está ativado.
example: true
events:
type: array
description: Lista de eventos que acionam este webhook.
items:
type: string
enum:
- group.created
- group.participants_added
- group.participants_demoted
- group.participants_promoted
- group.participants_removed
- group.updated
- instance.connected
- instance.disconnected
- instance.forbidden
- instance.mentioned
- instance.qrcode
- message.deleted
- message.delivered
- message.failed
- message.flow_reply
- message.pinned
- message.reaction
- message.read
- message.received
- message.sent
- message.unpinned
- poll.created
- poll.deleted
- poll.updated
- status.reply
example:
- message.received
id:
type: string
description: Identificador único do webhook.
example: 2nenz69l0xbf0m3uu9tfo
name:
type: string
description: Nome do webhook configurado.
example: Webhook Name
test_mode:
type: boolean
description: Indica se o webhook está em modo de teste.
example: false
test_url:
type: string
nullable: true
description: URL de teste do webhook, se disponível.
example: null
url:
type: string
format: uri
description: URL do webhook para onde os eventos serão enviados.
example: https://webhook.mydomain.com
required:
- enabled
- events
- id
- name
- test_mode
- url
lookup_key:
type: string
description: Identificador de pesquisa criado anteriormente.
example: ins_8j7wlxmpjlixx9mux5
required:
- created_at
- id
- metadata
- name
- owner
- settings
- status
- webhooks
InstanceSettings:
type: object
description: |
Objeto **opcional** de configurações da sua instância.
properties:
call_rejection:
type: string
description: |
Define o comportarmento de rejeição de ligações.
- `all` - Irá rejeitar todas ligações
- `none` - Não irá rejeitar ligações.
- `video_only` - Irá rejeitar apenas ligações de **vídeo**.
- `audio_only` - Irá rejeitar apenas ligações de **audio**.
enum:
- all
- none
- video_only
- audio_only
delay_per_word:
type: boolean
description: >
Define se o delay antes de enviar a mensagem deve ser baseado na
quantidade de palavras.
ℹ️ Limitado a no máximo **10 segundos** de espera.
delete_chat_after_sent:
type: boolean
description: >
⚠️ *Esta função não está funcionando adequadamente, estamos
trabalhando para regulariza-la.*
Define se o chat/conversa deve ser limpo depois do envio da
mensagem. Isso garante que o dispositivo fique acumulando mensagens
a ponto de muitas vezes travar o dispositivo que foi conectado.
message_delay:
type: object
description: >
Define a configuração de delay antes do envio da mensagem, se
configurado `delay_per_word` é ignorado. O tempo é gerado
randomicamente entre os limites configurado (`min` e `max`).
properties:
enabled:
type: boolean
default: true
max:
type: integer
description: >-
Máximo de tempo em segundos que deve ser esperado antes do envio
da mensagem.
default: 10
min:
type: integer
description: >-
Mínimo de tempo em segundos que deve ser esperado antes do envio
da mensagem.
default: 1
presence_behavior:
type: string
description: >
Define o comportamento da presença (Online, Digitando...,
Gravando...) da sua instância.
- `only_composing` - Aparecerá "Online" apenas durante o envio da
mensagem. (**recomendado**)
- `always_online` - Aparecerá sempre online
- `always_offline` - Nunca aparecerá "Online" exceto quando
necessário durante os envios (por boas práticas)
enum:
- only_composing
- always_online
- always_offline
read_confirmation:
description: >
Define o comportamento de "confirmação de leitura", ou seja, a
leitura automática das mensagens recebidas.
Aceita os valores clássicos em texto ou um objeto segmentado por
tipo de conversa:
- `never` - Nunca confirma a leitura (equivale a todos os segmentos
desligados)
- `always` - Sempre confirma a leitura (equivale a todos os
segmentos ligados)
- Objeto com os campos `chats`, `groups` e `status` - Controla cada
segmento de forma independente
No formato de objeto, cada campo é booleano e o padrão é `false`:
- `chats` - Conversas individuais
- `groups` - Grupos
- `status` - Status publicados pelos seus contatos (com este
segmento ligado, os status recebidos são marcados como vistos)
Mensagens enviadas pela própria instância, listas de transmissão e
publicações de canais nunca recebem confirmação de leitura
automática.
oneOf:
- type: string
enum:
- never
- always
- type: object
properties:
chats:
type: boolean
default: false
description: >-
Confirma a leitura de mensagens recebidas em conversas
individuais.
groups:
type: boolean
default: false
description: Confirma a leitura de mensagens recebidas em grupos.
status:
type: boolean
default: false
description: Marca como vistos os status publicados pelos seus contatos.
securitySchemes:
bearer:
type: http
scheme: bearer
````