Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

El módulo Instance es el punto de partida de cualquier integración con RyzeAPI. Cada instancia representa una conexión activa a un número de WhatsApp, puedes tener varias por cuenta (una para ventas, otra para soporte, otra para marketing, por ejemplo). Aquí encontrarás todo lo que necesitas para:
  • Aprovisionar nuevas instancias en tu cuenta, opcionalmente ya configuradas con webhook, WebSocket y Chatwoot en la misma solicitud
  • Conectar cada una a un número vía QR code o pairing code
  • Inspeccionar el estado actual y los datos de perfil
  • Configurar proxy, ajustes de comportamiento y almacenamiento S3
  • Desconectar (logout) manteniendo la instancia, o eliminar completamente
El estado actual de una instancia se consulta vía GET /api/instance/list?instanceName=<name>. La respuesta incluye el estado de conexión, el perfil y un resumen de las integraciones (webhook, websocket, chatwoot).

​
Ciclo de vida típico

1

Crear

POST /api/instance/new aprovisiona la instancia y devuelve el TokenInstance. La instancia nace en el estado disconnected.
2

Conectar

GET /api/instance/connect/:instance genera el QR code (o pairing code) para escanear en el teléfono.
3

Verificar

GET /api/instance/list?instanceName=<name> confirma que el estado pasó a connected y expone los datos completos (perfil, integraciones, settings).
4

Operar

La instancia está lista para enviar/recibir mensajes, gestionar grupos, etc. Webhooks y WebSocket notifican cambios de estado en tiempo real.
5

Finalizar

Usa logout para desconectar manteniendo la instancia, o delete para eliminar todo permanentemente.

​
Configuración inline al crear

Los bloques webhook, WebSocket y Chatwoot pueden enviarse dentro del cuerpo de POST /api/instance/new, de modo que la instancia nace ya integrada, sin necesidad de llamadas adicionales. Consulta la referencia completa en Crear instancia.

Webhook inline

Campos webhookEnabled, webhookURL, webhookEvents, webhookAuthorization…

WebSocket inline

Campos websocketEnabled, websocketEvents, websocketMediaBase64.

Chatwoot inline

Campos chatwootEnabled, chatwootBaseUrl, chatwootAccountId, chatwootApiToken, chatwootInboxName…

​
Gestión de instancias

Crear instancia

POST /api/instance/new, aprovisiona una nueva, aplicando proxy, webhook, websocket, chatwoot, settings y S3 inline.

Listar instancias

GET /api/instance/list, todas las de tu cuenta (con TokenAccount) o solo la propia (con TokenInstance). Acepta ?instanceName= para filtrar.

Eliminar

DELETE /api/instance/delete/:instance, elimina todo permanentemente.

​
Conexión a WhatsApp

Conectar (QR o pairing)

GET /api/instance/connect/:instance, genera QR code o pairing code para vincular el número.

Reconectar

POST /api/instance/reconnect/:instance, restaura una sesión caída, sin necesidad de un nuevo QR.

Logout

DELETE /api/instance/logout/:instance, desconecta de WhatsApp manteniendo la instancia (necesitará un nuevo QR para reconectar).

​
Configuración de la instancia

Leer settings

GET /api/instance/getSettings/:instance

Actualizar settings

POST /api/instance/settings/:instance, auto-rechazo de llamadas, ignorar grupos, mantener online, etc.

Leer proxy

GET /api/instance/getProxy/:instance

Actualizar proxy

POST /api/instance/proxy/:instance, HTTP, HTTPS o SOCKS5.

Leer configuración S3

GET /api/instance/getS3/:instance

Actualizar configuración S3

POST /api/instance/s3/:instance, almacena media recibida en tu propio bucket.

​
Estados posibles de una instancia

EstadoQué significa
disconnectedInstancia creada pero sin sesión activa
connectingEsperando conexión vía QR Code o Pairing Code con WhatsApp
connectedLista para enviar y recibir
loggedoutUsuario desvinculó en el teléfono o se realizó logout vía API
bannedCuenta baneada por WhatsApp
Para inspeccionar el estado actual, usa GET /api/instance/list?instanceName=<name>. La respuesta incluye connection.state, connection.numberJid, connection.presenceStatus, connection.displayStatus y el objeto profile (nombre, foto, business).

​
Forma del error

La API siempre devuelve la misma forma de error en cualquier endpoint de este módulo: 
{
  "success": false,
  "error": {
    "message": "<actionable description>"
  }
}
No hay un campo code, usa el status HTTP y el texto de error.message para clasificar.

​
Mejores prácticas

Para verificar el estado de la instancia, usa GET /api/instance/list?instanceName=<name> en lugar de polling agresivo, los webhooks/WebSocket son la forma recomendada de reaccionar a los cambios.
Monitorea los eventos instance.state vía webhook/WebSocket para reaccionar a disconnected / loggedout automáticamente.

​
Relacionado

Enviar mensajes

Una vez conectada, comienza a enviar.

Configurar webhook

Recibe eventos de la instancia en tiempo real.