Pular para o conteúdo principal
GET
/
api
/
instance
/
connect
/
:instance
Conectar Instância
curl --request GET \
  --url https://api.example.com/api/instance/connect/:instance \
  --header 'token: <token>'
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"

​
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"

​
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"
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

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,...">.

​
Path parameters

​
instance
string
obrigatório
Nome da instância a conectar.

​
Headers

​
token
string
obrigatório
TokenAccount ou TokenInstance da instância do path.

​
Query parameters

​
number
string
Telefone em formato internacional (ex.: 5511999999999). Se preenchido, força login via pairing code em vez de QR.
​
history
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

HTTPerror.messageQuando
400Instance name is requiredPath vazio.
401Invalid tokenToken ausente ou inválido.
404Instance not foundNome não existe.
429Rate limit exceeded. Try again later.Mais de 100 req/min.
500Failed to generate QR codeFalha ao gerar QR/pairing (rede, proxy, store corrompido).
{
  "success": false,
  "error": {
    "message": "Instance not found"
  }
}

​
Próximo

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.