Skip to main content

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.

This is the complete API reference. Endpoints are organized into modules, each covering a specific aspect of WhatsApp. If you’re just starting, we recommend reading: Quickstart → Concepts → Authentication before diving into a specific module.

​
Base URL and conventions

  • Base URL: https://ryzeapi.cloud
  • Path prefix: every endpoint starts with /api/<module>/...
  • Health probe: /health (no /api/ prefix)
  • Real-time events: /ws/:instance (WebSocket)
  • Content-Type: application/json on every POST / PUT / DELETE with body
  • Authentication: token header on every route (see Authentication)
  • Rate limit: 100 req/min by default; instance creation has a strict limit of 20 req/min
  • Maximum body: 64 MB per request (covers base64 uploads)

​
Modules

Instance

Create, connect, configure, and operate your WhatsApp instances.

Messages

Text, media, sticker, location, contact, reaction, poll, carousel, buttons, list, form, PIX, and status.

Chat

Contacts, labels, archive, pin, mute, presence, history, forward, edit, delete, and more.

Groups

Create groups, manage participants, invite links, and moderation.

Communities

Create communities and link subgroups.

Newsletter

Create channels and manage subscriptions.

Profile

Name, picture, status message, and privacy of the connected WhatsApp account.

Events

Webhooks (with persisted queue + retry) and real-time WebSockets.

WebSocket

/ws/:instance upgrade, protocol, heartbeat, reconnection.

Chatwoot

Chatwoot integration via bridge (RyzeIntegrations).

Observability

/health, combined probe for orchestrators.

​
Response format

Every call returns a JSON with the success field indicating the result: 
{
  "success": true,
  "message": "Message sent successfully",
  "status": "sent",
  "data": { "...": "..." }
}
The error envelope has only success + error.message, there is no numeric code field. Programmatic differentiation uses the HTTP status + the message text. See Error types for the full message catalog.

​
WhatsApp identifiers (JIDs)

TypeFormatExample
Private<phone>@s.whatsapp.net5511999999999@s.whatsapp.net
Group<id>@g.us120363406289005073@g.us
Newsletter<id>@newsletter120363422585881117@newsletter
LID (hidden)<id>@lid199789077627112@lid
Broadcast (status)status@broadcaststatus@broadcast
Most endpoints accept a plain number (5511999999999) and convert it internally. For Brazilian numbers (with prefix 55), the API tries variations with/without the extra “9” after the area code.

​
Quick glossary

  • JID, the unique identifier in WhatsApp (contact, group, channel, LID).
  • Account, your space in RyzeAPI, identified by the TokenAccount.
  • Instance, an active connection to a WhatsApp number.
  • TokenAccount, account token; used to create/list/delete instances and operate any instance in the account.
  • TokenInstance, instance-specific token; used for day-to-day operations of that instance.
  • Webhook, a POST the API makes to your URL when an event happens (with exponential retry and DLQ).
  • WebSocket, persistent connection to receive events in real time.
  • RyzeIntegrations, optional microservice (bridge) that connects RyzeAPI to external integrations such as Chatwoot.

​
Variables in examples

The Base URL is always https://ryzeapi.cloud. The examples use these variables:
VariableMeaning
$Token_AccountYour TokenAccount
$Token_InstanceTokenInstance of a specific instance
$Instance_NameInstance name (e.g., myInstance)