Concepts

Understanding these core concepts saves hours of debugging. Read this before opening any module.

Account

Your account on RyzeAPI is what groups all of your WhatsApp instances. It has:

A unique TokenAccount (your main credential)
An instance limit that you can create
Access to all of its instances

Think of it as your “client area”: inside it live your instances, each one representing a connected WhatsApp number.

Instance

An instance is an active connection to a WhatsApp number. Each instance has:

A unique name within your account (e.g., myInstance, support, service)
Its own token (TokenInstance) generated automatically when you create the instance
Persistent session, after connecting to WhatsApp, it stays connected even after restarting
Individual settings (webhook, proxy, etc.)

The instance name appears in every URL that has :instance in the path. Example: POST /api/message/text/myInstance operates on the instance named myInstance.

Tokens: Account vs Instance

TokenAccount

Delivered when your account is created. Used to administer your account. Use cases: create, list, or delete instances.

TokenInstance

Generated by the API when you create an instance. Used for day-to-day operations. Use cases: send a message, create a group, configure a webhook, etc.

See Authentication for details on when to use each.

JID (Jabber ID)

Every contact, group, or channel on WhatsApp has a JID, a unique identifier in email style. The API accepts and returns JIDs in every endpoint that references recipients.

Type	Format	Example
User	`<number>@s.whatsapp.net`	`5511999999999@s.whatsapp.net`
Group	`<id>@g.us`	`120363024567890123@g.us`
Newsletter (channel)	`<id>@newsletter`	`123456789@newsletter`

In send endpoints for contacts, you can pass just the number (e.g., 5511999999999) in the number field, and the API builds the full JID automatically. For groups, always pass the full JID (the one ending in @g.us).

Webhook vs WebSocket

RyzeAPI offers two complementary channels to receive events in real time (new messages, delivery status, group changes, etc.). You can use both at the same time.

Webhook (HTTP push)

When an event happens on your instance, RyzeAPI makes a POST request to the URL you configured.Ideal for: server-to-server integrations, CRMs, automations, bots.Characteristics:

RyzeAPI retries if your endpoint is down (retry with backoff)
You can configure up to 3 simultaneous webhooks per instance (production, staging, logging)
Can include the media as base64 in the webhook body, or just the URL

WebSocket (persistent connection)

Your client keeps an open connection with RyzeAPI and receives events in real time over the same channel.Ideal for: live dashboards, browser applications, any interface where you want to see messages arrive without polling.Characteristics:

Automatic reconnection recommended on the client side
Same event shape as the webhook
Authenticated via query string (?token=) when in browser

The 6 event types

Event	When it happens
`message.exchange`	Message sent or received
`message.status`	Status change (sent → delivered → read)
`group.flow`	Group creation, exit, or change
`instance.state`	Connected, disconnected, new QR, logout
`call.update`	Call received, rejected, accepted
`label.update`	Label created, renamed, assigned

Response format

The API uses two envelope formats, which can vary across endpoints. Both start with the success field that indicates whether the operation succeeded.

Success
Error

{
  "success": true,
  "message": "Text message sent successfully",
  "status": "sent",
  "data": { "...": "..." }
}

Important fields:

success: always present
message: human-readable description of the result
status: stable business code (e.g., sent, connected, qr_ready). It is the best field for handling responses programmatically
data: useful payload (varies by endpoint)

{
  "success": false,
  "error": {
    "message": "Instance is not connected to WhatsApp"
  }
}

Priority order for handling:

The HTTP code (401, 403, 429, etc.), source of truth
The text in error.message, when you need to differentiate two errors with the same HTTP code

See Error types for the full catalog of literal messages.

Quick glossary

Term	Meaning
Account	Your main area on RyzeAPI. Groups all of your instances, with a quota of how many you can create.
Instance	Active connection to a WhatsApp number, managed by the API.
TokenAccount	Your main token, used to create/list/delete instances.
TokenInstance	Token for the specific instance, used for day-to-day operations.
JID	Unique identifier on WhatsApp (contact, group, or channel) in email format.
Webhook	`POST` request that RyzeAPI makes to your URL when an event happens.
WebSocket	Persistent connection that delivers events in real time to a client.
Pairing code	8-character code to connect an instance without scanning a QR.

Variables used in examples

The Base URL is always https://ryzeapi.cloud. The examples use these variables:

Variable	Meaning
`$Token_Account`	Your account token
`$Token_Instance`	Token of a specific instance
`$Instance_Name`	Instance name (e.g., `myInstance`)

Getting started

Fundamentals

MCP

Account

Instance

Tokens: Account vs Instance

TokenAccount

TokenInstance

JID (Jabber ID)

Webhook vs WebSocket

The 6 event types

Response format

Quick glossary

Variables used in examples

​Account

​Instance

​Tokens: Account vs Instance

TokenAccount

TokenInstance

​JID (Jabber ID)

​Webhook vs WebSocket

​The 6 event types

​Response format

​Quick glossary

​Variables used in examples

Account

Instance

Tokens: Account vs Instance

JID (Jabber ID)

Webhook vs WebSocket

The 6 event types

Response format

Quick glossary

Variables used in examples