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.

RyzeAPI utiliza dos tipos de token para autenticar cada solicitud. Ambos se envían en el header token. Comprende cuándo usar cada uno y cómo manejar los errores más comunes.

​
Dos tipos de token

TokenAccount

Es tu token principal. Con él creas y administras tus instancias de WhatsApp.Alcance: toda tu cuenta, todas las instancias que posee.Cuándo usarlo: crear una instancia, listar todas tus instancias, eliminar una instancia, o cualquier operación en la que necesites actuar como “propietario de la cuenta”.

TokenInstance

Generado automáticamente cuando creas una nueva instancia. Cada instancia tiene el suyo propio.Alcance: solo esa instancia específica.Cuándo usarlo: operaciones del día a día, enviar un mensaje, crear un grupo, configurar un webhook, leer contactos, etc. Es el token que usarás en el 99% de las llamadas.
Como regla general: usa el TokenInstance siempre que el endpoint tenga :instance en la ruta. Usa el TokenAccount solo para crear/listar/eliminar instancias.

​
Ciclo de vida del token

1

Recibes tu TokenAccount

Entregado al crearse tu cuenta. Guárdalo en un lugar seguro, no se puede recuperar después.
2

Crear una instancia

Llama a POST /api/instance/new enviando tu TokenAccount. La respuesta incluye el campo data.token, que es el TokenInstance de esa instancia.
3

Usa el TokenInstance día a día

A partir de ahí, cada operación sobre esa instancia (enviar un mensaje, leer contactos, configurar un webhook) usa el TokenInstance.
4

¿Necesitas crear otra instancia?

Vuelve a usar tu TokenAccount para aprovisionar una más.

​
Tres formas de enviar el token

Recomendamos usar siempre el header token. Las otras formas existen solo para casos específicos.

​
Header token (predeterminado recomendado)

POST /api/message/text/$Instance_Name HTTP/1.1
Host: ryzeapi.cloud
Content-Type: application/json
token: your-token-here

{"number": "5511999999999", "message": "Hello!"}

​
Header Authorization: Bearer (compatibilidad)

En caso de que tu herramienta solo soporte el estándar Bearer. 
Authorization: Bearer your-token-here

​
Query string ?token= (solo WebSocket en navegador)

Se usa cuando no es posible enviar headers, el caso típico es WebSocket en JavaScript de navegador, ya que new WebSocket(...) no acepta headers personalizados. 
const ws = new WebSocket(
  `wss://ryzeapi.cloud/ws/$Instance_Name?token=${instanceToken}`
);
Los query strings aparecen en los logs de proxies y CDNs. No los uses en producción fuera del caso de WebSocket/navegador.

​
Quién puede hacer qué

  • Cualquier endpoint :instance de la propia instancia: enviar un mensaje, leer contactos, configurar un webhook, crear un grupo, etc.
  • Inspeccionar el estado actual de la propia instancia (GET /api/instance/list)
  • Abrir una conexión WebSocket para recibir eventos en tiempo real
  • El TokenInstance no crea nuevas instancias, usa TokenAccount para eso
  • El TokenInstance de una instancia no opera otra instancia, cada token solo es válido para la suya propia
  • El TokenAccount/TokenInstance de una cuenta no opera instancias de otra cuenta

​
Protección de acceso (ownership)

RyzeAPI verifica automáticamente, antes de cada operación, si el token enviado tiene permiso para ese recurso específico. Esto evita que un token filtre acceso a instancias de terceros. Ejemplos de lo que se bloquea automáticamente:
  • Intentar enviar un mensaje en la instancia B usando el token de la instancia A → 403
  • Intentar eliminar una instancia que pertenece a otra cuenta → 403
  • TokenAccount intentando crear más instancias de las que permite su cuota → 403

​
Errores de autenticación

Todas las respuestas de error de auth vienen con HTTP 401 (token inválido) o 403 (sin permiso) y siguen el formato: 
{
  "success": false,
  "error": {
    "message": "human-readable description of the problem"
  }
}

​
Mensajes que puedes encontrar

HTTPMensajeCausa más probable
401Missing token in headerNo enviaste el header token
401Missing token in header, Authorization header, or query parameterNo se usó ninguna de las 3 formas de token
401Invalid tokenEl token no existe, es incorrecto o ha sido revocado
401Invalid instance tokenEl token no coincide con la instancia en la ruta
403Instance token does not match requested instanceEstás usando el TokenInstance de A en la ruta :instance=B
403Instance does not belong to your accountTokenAccount intentando operar una instancia de otra cuenta
403Account instance quota exceededAlcanzaste el límite de instancias de tu cuenta
Si recibes Invalid token sin saber por qué, verifica: (1) que el token esté completo y sin espacios; (2) que estés usando el tipo de token correcto para ese endpoint; (3) que la instancia exista y esté activa.

​
Seguridad: buenas prácticas

Trata cada token como una credencial, guárdalo en variables de entorno o en una bóveda de secretos, nunca en el frontend ni en repositorios públicos.
Usa un TokenInstance por instancia, si uno se filtra, solo revocas ese.
Usa HTTPS en producción, RyzeAPI solo acepta conexiones seguras.
Usa el header token (no el query string) en la mayoría de los casos, los headers no terminan en logs de proxies.
Monitorea el header X-RateLimit-Remaining para evitar ser bloqueado por exceso de solicitudes.

​
Siguiente

Tipos de error

Los formatos de respuesta y cómo interpretar cada código HTTP.

Límite de velocidad

Cuánto puedes llamar por minuto y cómo reaccionar a 429.