Nueva instancia

Auth: TokenAccount • Rate-limit: 20/min • Idempotente: no

Descripción

Crea una nueva instancia de WhatsApp en tu cuenta. La instancia nace disconnected, el siguiente paso es llamar a GET /api/instance/connect/:instance para obtener el QR code o pairing code. Durante la creación, puedes enviar, en el mismo body, la configuración inicial de proxy, webhook, WebSocket, integración Chatwoot, ajustes de comportamiento y almacenamiento S3. Cada bloque es independiente: envía solo lo que necesites.

La instancia se crea dentro de la cuota de tu cuenta. Si has alcanzado el límite, recibirás 403 con el mensaje Account instance quota exceeded, elimina una instancia que ya no uses para liberar espacio.

Las fallas en sub-bloques (webhook / websocket / chatwoot) no abortan la creación de la instancia. Cada bloque es log-and-continue: la instancia se crea, el sub-bloque aparece como enabled: false o ausente en la respuesta y los logs del servidor describen la causa. Para Chatwoot, la falla también se expone en chatwoot.status: "error" + chatwoot.error: "<message>" en el payload de retorno.

Ejemplos

Mínimo

Crea la instancia con solo el name. El TokenInstance es generado automáticamente por el servidor y devuelto en instance.token en la respuesta, guárdalo para autenticar las llamadas subsiguientes.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-instance"}'

Con token personalizado

Define manualmente el TokenInstance en el campo token en lugar de dejar que el servidor genere uno. Útil para reutilizar un valor ya registrado en otro sistema, el token debe ser único dentro de tu cuenta.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":  "my-instance",
    "token": "my-custom-token-123"
  }'

Con settings personalizados

Crea la instancia con el bloque settings ya definido: rechaza llamadas automáticamente con un mensaje por defecto, mantiene presencia online, deshabilita la sincronización de historial e ignora estados. Equivale a llamar a POST /api/instance/settings/:instance justo después.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-instance",
    "autoRejectCalls":      true,
    "callRejectMessage":    "This number does not accept calls.",
    "ignoreGroupMessages":  false,
    "keepOnlineStatus":     true,
    "autoReadMessages":     false,
    "disableHistorySync":   true,
    "ignoreStatus":         true
  }'

Con proxy

Aprovisiona la instancia apuntando a un proxy SOCKS5 autenticado. La contraseña se cifra at-rest con AES-256-GCM y nunca se devuelve en la respuesta.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":          "my-instance",
    "proxyEnabled":  true,
    "proxyProtocol": "socks5",
    "proxyHost":     "proxy.company.com",
    "proxyPort":     "1080",
    "proxyUsername": "user",
    "proxyPassword": "proxy-password"
  }'

Con webhook

En la misma solicitud, configura el webhook default para recibir solo los eventos message.exchange y call.update, con Authorization personalizado para validar el origen. La media no se envía en base64, el destino la obtiene vía la URL devuelta.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":                 "my-instance",
    "webhookEnabled":       true,
    "webhookURL":           "https://myapp.com/webhook",
    "webhookAuthorization": "Bearer secret-key-123",
    "webhookByEvents":      false,
    "webhookEvents":        ["message.exchange", "call.update"],
    "webhookMediaBase64":   false
  }'

Con WebSocket

Habilita el broadcast en tiempo real vía WebSocket filtrando por los eventos message.exchange y call.update. Útil para dashboards y bots que necesitan latencia mínima sin exponer un endpoint público de webhook.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":                 "my-instance",
    "websocketEnabled":     true,
    "websocketEvents":      ["message.exchange", "call.update"],
    "websocketMediaBase64": false
  }'

Con S3

Apunta el almacenamiento de media a un bucket AWS S3 (us-east-1), con prefijo media/ para organizar las subidas. La s3SecretKey se cifra at-rest y nunca aparece en la respuesta.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "my-instance",
    "s3Enabled":    true,
    "s3Region":     "us-east-1",
    "s3Bucket":     "my-media-bucket",
    "s3AccessKey":  "AKIA...",
    "s3SecretKey":  "secret...",
    "s3Endpoint":   "https://s3.amazonaws.com",
    "s3PathPrefix": "media/"
  }'

Con Chatwoot

Aprovisiona la instancia ya vinculada a un inbox de Chatwoot (WhatsApp - Orion), con firma de agente activa y reapertura automática de conversaciones resueltas. Si el bridge falla, la instancia se crea de todos modos y el objeto chatwoot regresa con status: "error".

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":                  "support",
    "chatwootEnabled":       true,
    "chatwootBaseUrl":       "https://chatwoot.example.com",
    "chatwootAccountId":     5,
    "chatwootApiToken":      "sk_live_abc123...",
    "chatwootInboxName":     "WhatsApp - Orion",
    "chatwootSignMessages":  true,
    "chatwootIgnoreGroups":  false,
    "chatwootStartAsPending": false,
    "chatwootReopenResolved": true
  }'

Completo

Combina todos los bloques en la misma solicitud: token personalizado, proxy SOCKS5, webhook, WebSocket, integración Chatwoot, ajustes de comportamiento y almacenamiento S3. Cada bloque permanece independiente, las fallas en sub-bloques no abortan la creación de la instancia.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":  "marketing",
    "token": "my-custom-token-123",

    "proxyEnabled":  true,
    "proxyProtocol": "socks5",
    "proxyHost":     "proxy.company.com",
    "proxyPort":     "1080",
    "proxyUsername": "user",
    "proxyPassword": "proxy-password",

    "webhookEnabled":       true,
    "webhookURL":           "https://myserver.com/webhook",
    "webhookAuthorization": "Bearer secret-key-123",
    "webhookByEvents":      false,
    "webhookEvents":        ["message.exchange", "call.update"],
    "webhookMediaBase64":   false,

    "websocketEnabled":     true,
    "websocketEvents":      ["message.exchange", "call.update"],
    "websocketMediaBase64": false,

    "chatwootEnabled":        true,
    "chatwootBaseUrl":        "https://chatwoot.example.com",
    "chatwootAccountId":      5,
    "chatwootApiToken":       "sk_live_abc123...",
    "chatwootInboxName":      "Marketing",
    "chatwootSignMessages":   true,
    "chatwootIgnoreGroups":   false,
    "chatwootStartAsPending": false,
    "chatwootReopenResolved": true,

    "autoRejectCalls":     true,
    "callRejectMessage":   "This number does not accept calls.",
    "ignoreGroupMessages": false,
    "keepOnlineStatus":    true,
    "autoReadMessages":    false,
    "disableHistorySync":  false,
    "ignoreStatus":        true,

    "s3Enabled":    true,
    "s3Region":     "us-east-1",
    "s3Bucket":     "my-media-bucket",
    "s3AccessKey":  "AKIA...",
    "s3SecretKey":  "secret...",
    "s3Endpoint":   "https://s3.amazonaws.com",
    "s3PathPrefix": "media/"
  }'

Respuesta exitosa

La respuesta incluye el TokenInstance generado y el resumen de cada integración configurada (proxy, webhook, websocket, chatwoot, settings, s3). Guarda el instance.token, es lo que autentica las llamadas subsiguientes de la propia instancia.

201 Created

{
  "success": true,
  "message": "Instance created",
  "instance": {
    "id": "5e1d...",
    "name": "my-instance",
    "token": "a1b2c3d4-...",
    "status": "disconnected",
    "numberJid": null,
    "proxy": {
      "enabled": false,
      "host": null,
      "port": null,
      "protocol": null,
      "username": null,
      "password": null
    },
    "webhook": {
      "enabled": true,
      "url": "https://myapp.com/webhook",
      "events": ["message.exchange", "call.update"]
    },
    "websocket": {
      "enabled": true,
      "events": ["message.exchange"],
      "mediaBase64": false
    },
    "chatwoot": {
      "enabled": true,
      "status": "active",
      "bridgeIntegrationId": "int_xyz789abc",
      "baseUrl": "https://chatwoot.example.com",
      "accountId": 5,
      "inboxName": "WhatsApp - Orion"
    },
    "settings": {
      "autoRejectCalls": false,
      "callRejectMessage": "",
      "ignoreGroupMessages": false,
      "keepOnlineStatus": false,
      "autoReadMessages": false,
      "disableHistorySync": true,
      "ignoreStatus": false
    },
    "s3": {
      "enabled": false,
      "region": null,
      "bucket": null,
      "accessKey": null,
      "secretKey": null,
      "endpoint": null,
      "pathPrefix": null
    },
    "createdAt": "2026-04-28T10:30:00Z",
    "updatedAt": "2026-04-28T10:30:00Z"
  }
}

El chatwootApiToken nunca es devuelto por la API (incluso en esta respuesta). El s3.secretKey y la proxy.password tampoco.

Chatwoot con error

Si el bloque chatwoot* fue enviado pero la configuración falló (p. ej., token inválido), la instancia se crea de todos modos y el objeto chatwoot en la respuesta viene con status: "error" y un error accionable:

"chatwoot": {
  "enabled": false,
  "status": "error",
  "error": "Chatwoot API returned 401 — check the chatwootApiToken"
}

Puedes corregir las credenciales vía POST /api/chatwoot/set/:instance sin recrear la instancia.

Cabeceras

token

string

requerido

Tu TokenAccount.

Content-Type

string

requerido

application/json

Cuerpo de la solicitud

name

string

requerido

Identificador de la instancia (usado en las rutas :instance de todos los demás endpoints). No puede estar en blanco y debe ser único dentro de tu cuenta. Se recomienda kebab-case o snake_case.

token

string

Token personalizado para la instancia. Si se omite, se genera automáticamente (recomendado).

Bloque proxy (opcional)

proxyEnabled

boolean

Habilita el uso de un proxy específico para esta instancia.

proxyHost

string

IP o hostname del proxy.

proxyPort

string

Puerto como string (p. ej., "8080").

proxyProtocol

string

http, https o socks5.

proxyUsername

string

Usuario del proxy (opcional).

proxyPassword

string

Contraseña del proxy (opcional, cifrada at-rest con AES-256-GCM).

Bloque webhook (opcional)

webhookEnabled

boolean

Habilita el envío de eventos a una URL.

webhookURL

string

URL donde RyzeAPI hará POST de los eventos.

webhookAuthorization

string

Valor que RyzeAPI envía en la cabecera Authorization de cada POST (útil para validar origen). Ej.: Bearer secret-key-123.

webhookByEvents

boolean

Si es true, cada tipo de evento puede tener su propia URL (default: false).

webhookEvents

string[]

Lista de eventos que la instancia debe despachar. Ej.: ["message.exchange", "call.update"].

webhookMediaBase64

boolean

Incluye media recibida como base64 dentro del body del webhook.

El bloque webhook crea un webhook con label default. Para múltiples webhooks por instancia, usa POST /api/events/webhook después.

Bloque WebSocket (opcional)

websocketEnabled

boolean

Habilita el broadcasting de eventos vía WebSocket para esta instancia.

websocketEvents

string[]

Lista de eventos que serán emitidos vía WebSocket. Si está vacío con websocketEnabled=true, todos los eventos son emitidos.

websocketMediaBase64

boolean

Incluye media recibida como base64 en los frames del WebSocket.

Bloque Chatwoot (opcional)

chatwootEnabled

boolean

Habilita la integración con Chatwoot vía el bridge RyzeIntegrations.

chatwootBaseUrl

string

URL de la instalación de Chatwoot (p. ej., https://chatwoot.example.com). Requerido si chatwootEnabled=true.

chatwootAccountId

integer

ID numérico de la cuenta de Chatwoot. Requerido si chatwootEnabled=true.

chatwootApiToken

string

Token de API de la cuenta de Chatwoot (el access_token del agente). Requerido si chatwootEnabled=true. Cifrado at-rest y nunca devuelto por la API.

chatwootInboxName

string

Nombre del inbox que se creará en Chatwoot (p. ej., "WhatsApp - Orion").

chatwootSignMessages

boolean

Si es true, los mensajes enviados a través de la API se prefijan con la firma del agente de Chatwoot.

chatwootIgnoreGroups

boolean

Si es true, los mensajes de grupo no se convierten en conversaciones en Chatwoot.

chatwootStartAsPending

boolean

Si es true, las nuevas conversaciones inician como pending en lugar de open.

chatwootReopenResolved

boolean

Si es true, los nuevos mensajes en conversaciones resueltas las reabren automáticamente.

La integración depende de que el bridge RyzeIntegrations esté configurado en el servidor. Si el bridge no está disponible, la creación de la instancia continúa y chatwoot regresa con enabled: false (la falla aparece en los logs del servidor). Consulta chatwoot.md para detalles.

Bloque settings (opcional)

autoRejectCalls

boolean

Rechaza automáticamente las llamadas entrantes.

callRejectMessage

string

Mensaje automático enviado al llamante cuando la llamada es rechazada.

ignoreGroupMessages

boolean

No procesa mensajes de grupo (útil para bots 1-a-1).

keepOnlineStatus

boolean

Mantiene la instancia marcada como “online” en WhatsApp.

autoReadMessages

boolean

Marca automáticamente los mensajes recibidos como leídos.

disableHistorySync

boolean

predeterminado:"true"

Default true (el historial no se sincroniza en la primera conexión). Envía false si quieres recibir el backlog.

ignoreStatus

boolean

Ignora mensajes de tipo “status” (stories).

Bloque S3 (opcional, almacenamiento de media)

s3Enabled

boolean

Habilita el upload de media recibida a S3 o MinIO.

s3Region

string

Región (p. ej., us-east-1).

s3Bucket

string

Nombre del bucket.

s3AccessKey

string

Access Key ID.

s3SecretKey

string

Secret Access Key (cifrado at-rest, nunca devuelto).

s3Endpoint

string

Endpoint personalizado para MinIO o DigitalOcean Spaces. Omite para AWS S3 oficial.

s3PathPrefix

string

Prefijo de path (p. ej., media/).

Errores

HTTP	`error.message`	Cuándo
400	`Invalid request body`	JSON malformado
400	`The 'name' field is required`	`name` faltante o en blanco
401	`Invalid token`	TokenAccount inválido
403	`Account instance quota exceeded`	Cuota de instancias alcanzada
409	`Instance or token already exists`	Nombre o token ya en uso
429	`Rate limit exceeded. Try again later.`	Más de 20 creaciones por minuto
500	`Failed to create instance`	Error interno

Ejemplo de error:

{
  "success": false,
  "error": {
    "message": "Instance or token already exists"
  }
}

Conectar a WhatsApp

Genera el QR code o pairing code para vincular el número.

Verificar estado

Usa GET /api/instance/list?instanceName=<name> para inspeccionar el status actual.

Introducción

Instancia

Eventos

Mensajes

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Observabilidad

Nueva instancia

Descripción

Ejemplos

Mínimo

Con token personalizado

Con settings personalizados

Con proxy

Con webhook

Con WebSocket

Con S3

Con Chatwoot

Completo

Respuesta exitosa

Chatwoot con error

Cabeceras

Cuerpo de la solicitud

Bloque proxy (opcional)

Bloque webhook (opcional)

Bloque WebSocket (opcional)

Bloque Chatwoot (opcional)

Bloque settings (opcional)

Bloque S3 (opcional, almacenamiento de media)

Errores

Siguiente

Conectar a WhatsApp

Verificar estado

Introducción

Instancia

Eventos

Mensajes

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Observabilidad

Documentation Index

​Descripción

​Ejemplos

​Mínimo

​Con token personalizado

​Con settings personalizados

​Con proxy

​Con webhook

​Con WebSocket

​Con S3

​Con Chatwoot

​Completo

​Respuesta exitosa

​Chatwoot con error

​Cabeceras

​Cuerpo de la solicitud

​Bloque proxy (opcional)

​Bloque webhook (opcional)

​Bloque WebSocket (opcional)

​Bloque Chatwoot (opcional)

​Bloque settings (opcional)

​Bloque S3 (opcional, almacenamiento de media)

​Errores

​Siguiente

Conectar a WhatsApp

Verificar estado

Descripción

Ejemplos

Mínimo

Con token personalizado

Con settings personalizados

Con proxy

Con webhook

Con WebSocket

Con S3

Con Chatwoot

Completo

Respuesta exitosa

Chatwoot con error

Cabeceras

Cuerpo de la solicitud

Bloque proxy (opcional)

Bloque webhook (opcional)

Bloque WebSocket (opcional)

Bloque Chatwoot (opcional)

Bloque settings (opcional)

Bloque S3 (opcional, almacenamiento de media)

Errores

Siguiente