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.

The Instance module is the starting point of any RyzeAPI integration. Each instance represents an active connection to a WhatsApp number, you can have several per account (one for sales, another for support, another for marketing, for example). Here you’ll find everything you need to:
  • Provision new instances in your account, optionally already configured with webhook, WebSocket, and Chatwoot in the same request
  • Connect each one to a number via QR code or pairing code
  • Inspect the current state and profile data
  • Configure proxy, behavior settings, and S3 storage
  • Disconnect (logout) keeping the instance, or delete completely
Current status of an instance is queried via GET /api/instance/list?instanceName=<name>. The response includes the connection state, profile, and a summary of integrations (webhook, websocket, chatwoot).

​
Typical lifecycle

1

Create

POST /api/instance/new provisions the instance and returns the TokenInstance. The instance is born in the disconnected state.
2

Connect

GET /api/instance/connect/:instance generates the QR code (or pairing code) for scanning on the phone.
3

Verify

GET /api/instance/list?instanceName=<name> confirms the state has become connected and exposes the full data (profile, integrations, settings).
4

Operate

The instance is ready to send/receive messages, manage groups, etc. Webhooks and WebSocket notify state changes in real time.
5

End

Use logout to disconnect while keeping the instance, or delete to remove everything permanently.

​
Inline configuration on creation

The webhook, WebSocket, and Chatwoot blocks can be sent inside the body of POST /api/instance/new, so the instance is born already integrated, with no need for additional calls. See the full reference at Create instance.

Inline webhook

Fields webhookEnabled, webhookURL, webhookEvents, webhookAuthorization…

Inline WebSocket

Fields websocketEnabled, websocketEvents, websocketMediaBase64.

Inline Chatwoot

Fields chatwootEnabled, chatwootBaseUrl, chatwootAccountId, chatwootApiToken, chatwootInboxName…

​
Instance management

Create instance

POST /api/instance/new, provisions a new one, applying proxy, webhook, websocket, chatwoot, settings, and S3 inline.

List instances

GET /api/instance/list, all of your account (with TokenAccount) or just your own (with TokenInstance). Accepts ?instanceName= to filter.

Delete

DELETE /api/instance/delete/:instance, removes everything permanently.

​
WhatsApp connection

Connect (QR or pairing)

GET /api/instance/connect/:instance, generates QR code or pairing code to link the number.

Reconnect

POST /api/instance/reconnect/:instance, restores a dropped session, no new QR needed.

Logout

DELETE /api/instance/logout/:instance, disconnects from WhatsApp keeping the instance (will need a new QR to reconnect).

​
Instance configuration

Read settings

GET /api/instance/getSettings/:instance

Update settings

POST /api/instance/settings/:instance, auto-reject calls, ignore groups, keep online, etc.

Read proxy

GET /api/instance/getProxy/:instance

Update proxy

POST /api/instance/proxy/:instance, HTTP, HTTPS, or SOCKS5.

Read S3 configuration

GET /api/instance/getS3/:instance

Update S3 configuration

POST /api/instance/s3/:instance, store received media in your own bucket.

​
Possible instance states

StateWhat it means
disconnectedInstance created but no active session
connectingWaiting for connection via QR Code or Pairing Code with WhatsApp
connectedReady to send and receive
loggedoutUser unlinked on the phone or logout was performed via the API
bannedAccount banned by WhatsApp
To inspect the current state, use GET /api/instance/list?instanceName=<name>. The response includes connection.state, connection.numberJid, connection.presenceStatus, connection.displayStatus, and the profile object (name, picture, business).

​
Error shape

The API always returns the same error shape on any endpoint of this module: 
{
  "success": false,
  "error": {
    "message": "<actionable description>"
  }
}
There is no code field, use the HTTP status and the error.message text to classify.

​
Best practices

To check the instance state, use GET /api/instance/list?instanceName=<name> instead of aggressive polling, webhooks/WebSocket are the recommended way to react to changes.
Monitor instance.state events via webhook/WebSocket to react to disconnected / loggedout automatically.

Send messages

Once connected, start sending.

Configure webhook

Receive instance events in real time.