Conectar Instância

GET

api

instance

connect

:instance

Conectar Instância

curl --request GET \
  --url https://api.example.com/api/instance/connect/:instance \
  --header 'token: <token>'

const options = {method: 'GET', headers: {token: '<token>'}};

fetch('https://api.example.com/api/instance/connect/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: parcial

Descrição

Inicia a conexão via whatsmeow. Sem parâmetros, gera QR code. Com ?number=..., gera pairing code (8 caracteres). Bloqueia até obter código ou erro (timeout interno ~60s).

Exemplos

QR code (uso padrão)

Sem nenhum query param, o servidor gera o QR code para escanear no celular. Retorna a string ASCII e o PNG em base64 prontos para renderizar.

curl -X GET "https://ryzeapi.cloud/api/instance/connect/minha-instancia" \
  -H "token: $Token_Instance"

await fetch("https://ryzeapi.cloud/api/instance/connect/minha-instancia", {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/connect/minha-instancia",
    headers={
        "token": os.environ["Token_Instance"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/connect/minha-instancia", nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

Pairing code

Passando ?number=5511999999999, o servidor força login via pairing code de 8 caracteres em vez de QR, útil quando o usuário não tem acesso à câmera para escanear.

curl -X GET "https://ryzeapi.cloud/api/instance/connect/minha-instancia?number=5511999999999" \
  -H "token: $Token_Instance"

await fetch("https://ryzeapi.cloud/api/instance/connect/minha-instancia?number=5511999999999", {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/connect/minha-instancia?number=5511999999999",
    headers={
        "token": os.environ["Token_Instance"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/connect/minha-instancia?number=5511999999999", nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

Com 7 dias de histórico

Solicita os últimos 7 dias de mensagens no primeiro pareamento via ?history=7. A presença do parâmetro força a sincronização mesmo se disableHistorySync=true estiver nos settings da instância.

curl -X GET "https://ryzeapi.cloud/api/instance/connect/minha-instancia?history=7" \
  -H "token: $Token_Instance"

await fetch("https://ryzeapi.cloud/api/instance/connect/minha-instancia?history=7", {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/connect/minha-instancia?history=7",
    headers={
        "token": os.environ["Token_Instance"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/connect/minha-instancia?history=7", nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

Pairing code: sem câmera. O usuário digita os 8 caracteres no WhatsApp em Dispositivos Vinculados > Vincular Outro Dispositivo > Vincular com número.

Resposta de sucesso

QR code gerado
Pairing code gerado

200 OK

{
  "success": true,
  "message": "QR code generated",
  "qrCode": "1@abc...,xyz==,base64string",
  "qrCodeBase64": "data:image/png;base64,iVBORw0K...",
  "status": "qr"
}

qrCode, string ASCII do QR (o que o WhatsApp espera). Pode ser renderizado em qualquer biblioteca de QR.
qrCodeBase64, PNG renderizado pelo servidor (base64). Pronto para usar como <img src="data:image/png;base64,...">.

200 OK

{
  "success": true,
  "message": "Pairing code generated",
  "pairingCode": "ABCD-EFGH",
  "status": "qr"
}

pairingCode é o que o usuário digita no celular.

Path parameters

string

obrigatório

Nome da instância a conectar.

Headers

string

obrigatório

TokenAccount ou TokenInstance da instância do path.

Query parameters

string

Telefone em formato internacional (ex.: 5511999999999). Se preenchido, força login via pairing code em vez de QR.

integer

Solicita os últimos N dias de histórico no primeiro pareamento (ex.: ?history=5). Requer suporte do servidor WhatsApp, não é garantido. A presença do parâmetro força a sincronização mesmo se disableHistorySync=true nos settings.

Notas

O QR expira, o WhatsApp emite um novo QR após ~20s. Se o usuário demorar e você precisar de uma nova tentativa, refaça a chamada.

Pairing code não é reutilizável. Se o usuário errar, refaça o request para gerar um novo.

Após chamar connect, faça poll de GET /api/instance/list?instanceName=<nome> para detectar quando o estado virar connected. Webhook/WebSocket avisam em tempo real via evento instance.state.

Erros

HTTP	`error.message`	Quando
400	`Instance name is required`	Path vazio.
401	`Invalid token`	Token ausente ou inválido.
404	`Instance not found`	Nome não existe.
429	`Rate limit exceeded. Try again later.`	Mais de 100 req/min.
500	`Failed to generate QR code`	Falha ao gerar QR/pairing (rede, proxy, store corrompido).

{
  "success": false,
  "error": {
    "message": "Instance not found"
  }
}

Reconectar sem QR

POST /api/instance/reconnect/:instance, reaproveita a sessão salva.

Verificar estado

GET /api/instance/list?instanceName=<nome> mostra o estado atual.

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Conectar Instância

Descrição

Exemplos

QR code (uso padrão)

Pairing code

Com 7 dias de histórico

Resposta de sucesso

Path parameters

Headers

Query parameters

Notas

Erros

Próximo

Reconectar sem QR

Verificar estado

​Descrição

​Exemplos

​QR code (uso padrão)

​Pairing code

​Com 7 dias de histórico

​Resposta de sucesso

​Path parameters

​Headers

​Query parameters

​Notas

​Erros

​Próximo

Reconectar sem QR

Verificar estado

Descrição

Exemplos

QR code (uso padrão)

Pairing code

Com 7 dias de histórico

Resposta de sucesso

Path parameters

Headers

Query parameters

Notas

Erros

Próximo