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.

Comprender estos conceptos clave ahorra horas de depuración. Léelos antes de abrir cualquier módulo.

​
Account

Tu cuenta en RyzeAPI es lo que agrupa todas tus instancias de WhatsApp. Tiene:
  • Un TokenAccount único (tu credencial principal)
  • Un límite de instancias que puedes crear
  • Acceso a todas sus instancias
Piénsalo como tu “área de cliente”: dentro de ella viven tus instancias, cada una representando un número de WhatsApp conectado.

​
Instance

Una instancia es una conexión activa a un número de WhatsApp. Cada instancia tiene:
  • Un nombre único dentro de tu cuenta (por ejemplo, myInstance, support, service)
  • Su propio token (TokenInstance) generado automáticamente al crear la instancia
  • Sesión persistente, después de conectarte a WhatsApp, permanece conectada incluso tras reiniciar
  • Configuración individual (webhook, proxy, etc.)
El nombre de la instancia aparece en cada URL que tiene :instance en la ruta. Ejemplo: POST /api/message/text/myInstance opera sobre la instancia llamada myInstance.

​
Tokens: Account vs Instance

TokenAccount

Entregado al crearse tu cuenta. Se usa para administrar tu cuenta. Casos de uso: crear, listar o eliminar instancias.

TokenInstance

Generado por la API al crear una instancia. Se usa para operaciones del día a día. Casos de uso: enviar un mensaje, crear un grupo, configurar un webhook, etc.
Consulta Autenticación para más detalles sobre cuándo usar cada uno.

​
JID (Jabber ID)

Cada contacto, grupo o canal en WhatsApp tiene un JID, un identificador único en estilo de correo electrónico. La API acepta y devuelve JIDs en cada endpoint que referencia destinatarios.
TipoFormatoEjemplo
Usuario<numero>@s.whatsapp.net5511999999999@s.whatsapp.net
Grupo<id>@g.us120363024567890123@g.us
Newsletter (canal)<id>@newsletter123456789@newsletter
En los endpoints de envío para contactos, puedes pasar solo el número (por ejemplo, 5511999999999) en el campo number, y la API construye el JID completo automáticamente. Para grupos, siempre pasa el JID completo (el que termina en @g.us).

​
Webhook vs WebSocket

RyzeAPI ofrece dos canales complementarios para recibir eventos en tiempo real (nuevos mensajes, estado de entrega, cambios de grupo, etc.). Puedes usar ambos al mismo tiempo.
Cuando ocurre un evento en tu instancia, RyzeAPI realiza una solicitud POST a la URL que configuraste.Ideal para: integraciones servidor a servidor, CRMs, automatizaciones, bots.Características:
  • RyzeAPI reintenta si tu endpoint está caído (retry con backoff)
  • Puedes configurar hasta 3 webhooks simultáneos por instancia (producción, staging, logs)
  • Puede incluir el archivo multimedia como base64 en el cuerpo del webhook, o solo la URL
Tu cliente mantiene una conexión abierta con RyzeAPI y recibe eventos en tiempo real por el mismo canal.Ideal para: dashboards en vivo, aplicaciones de navegador, cualquier interfaz donde quieras ver llegar los mensajes sin polling.Características:
  • Se recomienda reconexión automática del lado del cliente
  • Mismo formato de evento que el webhook
  • Autenticado vía query string (?token=) cuando se usa en navegador

​
Los 6 tipos de evento

EventoCuándo ocurre
message.exchangeMensaje enviado o recibido
message.statusCambio de estado (enviado → entregado → leído)
group.flowCreación, salida o cambio de grupo
instance.stateConectado, desconectado, nuevo QR, logout
call.updateLlamada recibida, rechazada, aceptada
label.updateEtiqueta creada, renombrada, asignada

​
Formato de respuesta

La API utiliza dos formatos de envoltorio, que pueden variar entre endpoints. Ambos comienzan con el campo success que indica si la operación fue exitosa. 
{
  "success": true,
  "message": "Text message sent successfully",
  "status": "sent",
  "data": { "...": "..." }
}
Campos importantes:
  • success: siempre presente
  • message: descripción legible del resultado
  • status: código de negocio estable (por ejemplo, sent, connected, qr_ready). Es el mejor campo para manejar respuestas de forma programática
  • data: payload útil (varía según el endpoint)
Consulta Tipos de error para el catálogo completo de mensajes literales.

​
Glosario rápido

TérminoSignificado
AccountTu área principal en RyzeAPI. Agrupa todas tus instancias, con una cuota de cuántas puedes crear.
InstanceConexión activa a un número de WhatsApp, gestionada por la API.
TokenAccountTu token principal, usado para crear/listar/eliminar instancias.
TokenInstanceToken de la instancia específica, usado para operaciones del día a día.
JIDIdentificador único en WhatsApp (contacto, grupo o canal) en formato de correo electrónico.
WebhookSolicitud POST que RyzeAPI hace a tu URL cuando ocurre un evento.
WebSocketConexión persistente que entrega eventos en tiempo real a un cliente.
Pairing codeCódigo de 8 caracteres para conectar una instancia sin escanear un QR.

​
Variables usadas en los ejemplos

La Base URL es siempre https://ryzeapi.cloud. Los ejemplos usan estas variables:
VariableSignificado
$Token_AccountTu token de cuenta
$Token_InstanceToken de una instancia específica
$Instance_NameNombre de la instancia (por ejemplo, myInstance)