Saltar al contenido principal
GET
/
api
/
instance
/
connect
/
:instance
Conectar instancia
curl --request GET \
  --url https://api.example.com/api/instance/connect/:instance \
  --header 'token: <token>'
Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: parcial

​
Descripción

Inicia la conexión vía whatsmeow. Sin parámetros, genera un QR code. Con ?number=..., genera un pairing code (8 caracteres). Bloquea hasta recibir un código o error (timeout interno ~60s).

​
Ejemplos

​
QR code (uso por defecto)

Sin query params, el servidor genera el QR code para escanear en el teléfono. Devuelve la cadena ASCII y el PNG en base64 listo para renderizar. 
curl -X GET "https://ryzeapi.cloud/api/instance/connect/my-instance" \
  -H "token: $Token_Instance"

​
Pairing code

Pasando ?number=5511999999999, el servidor fuerza el login vía un pairing code de 8 caracteres en lugar de QR, útil cuando el usuario no tiene acceso a una cámara para escanear. 
curl -X GET "https://ryzeapi.cloud/api/instance/connect/my-instance?number=5511999999999" \
  -H "token: $Token_Instance"

​
Con 7 días de historial

Solicita los últimos 7 días de mensajes en el primer pairing vía ?history=7. La presencia del parámetro fuerza la sincronización aunque disableHistorySync=true esté en los settings de la instancia. 
curl -X GET "https://ryzeapi.cloud/api/instance/connect/my-instance?history=7" \
  -H "token: $Token_Instance"
Pairing code: no se necesita cámara. El usuario teclea los 8 caracteres en WhatsApp en Dispositivos vinculados > Vincular un dispositivo > Vincular con número de teléfono.

​
Respuesta exitosa

200 OK
{
  "success": true,
  "message": "QR code generated",
  "qrCode": "1@abc...,xyz==,base64string",
  "qrCodeBase64": "data:image/png;base64,iVBORw0K...",
  "status": "qr"
}
  • qrCode, cadena ASCII del QR (lo que WhatsApp espera). Puede renderizarse con cualquier librería QR.
  • qrCodeBase64, PNG renderizado por el servidor (base64). Listo para usar como <img src="data:image/png;base64,...">.

​
Parámetros de ruta

​
instance
string
requerido
Nombre de la instancia a conectar.

​
Cabeceras

​
token
string
requerido
TokenAccount o TokenInstance de la instancia en el path.

​
Parámetros de consulta

​
number
string
Teléfono en formato internacional (p. ej., 5511999999999). Si está rellenado, fuerza login vía pairing code en lugar de QR.
​
history
integer
Solicita los últimos N días de historial en el primer pairing (p. ej., ?history=5). Requiere soporte del servidor de WhatsApp, no garantizado. La presencia del parámetro fuerza la sincronización aunque disableHistorySync=true esté en los settings.

​
Notas

El QR expira, WhatsApp emite un nuevo QR después de ~20s. Si el usuario tarda demasiado y necesitas otro intento, repite la llamada.
Pairing code no es reutilizable. Si el usuario lo escribe mal, repite la solicitud para generar uno nuevo.
Después de llamar a connect, haz polling a GET /api/instance/list?instanceName=<name> para detectar cuando el estado pase a connected. Webhook/WebSocket notifican en tiempo real vía el evento instance.state.

​
Errores

HTTPerror.messageCuándo
400Instance name is requiredPath vacío.
401Invalid tokenToken faltante o inválido.
404Instance not foundNombre no existe.
429Rate limit exceeded. Try again later.Más de 100 req/min.
500Failed to generate QR codeFalla al generar QR/pairing (red, proxy, store corrupto).
{
  "success": false,
  "error": {
    "message": "Instance not found"
  }
}

​
Siguiente

Reconectar sin QR

POST /api/instance/reconnect/:instance, reutiliza la sesión guardada.

Verificar estado

GET /api/instance/list?instanceName=<name> muestra el estado actual.