Quickstart

This guide covers the minimum path to get an instance connected and exchange your first message.

Prerequisites

You already have your RyzeAPI TokenAccount.

A phone with WhatsApp Business (or regular WhatsApp) installed.

1. Set your token

export Token_Account="your-account-token"

In all examples, the Base URL is always https://ryzeapi.cloud.

2. Create an instance

Use your TokenAccount to provision a new WhatsApp instance.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{"name": "$Instance_Name"}'

const res = await fetch(`https://ryzeapi.cloud/api/instance/new`, {
  method: "POST",
  headers: {
    "token": Token_Account,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "$Instance_Name" }),
});
const { data } = await res.json();
console.log(data.token); // this is the TokenInstance

import os, requests

r = requests.post(
    "https://ryzeapi.cloud/api/instance/new",
    headers={"token": os.environ["Token_Account"]},
    json={"name": "myInstance"},
)
print(r.json()["data"]["token"])  # this is the TokenInstance

Expected response:

{
  "success": true,
  "message": "Instance created successfully",
  "status": "created",
  "data": {
    "id": "01953abc-...",
    "name": "$Instance_Name",
    "token": "a1b2c3d4-...",
    "status": "disconnected",
    "createdAt": "2026-04-21T12:00:00Z"
  }
}

Save the data.token, this is your TokenInstance. From now on, use it (not the TokenAccount) to operate this instance.

export Token_Instance="a1b2c3d4-..."

3. Connect to WhatsApp

Use your TokenInstance from here on.

Via QR code
Via pairing code

curl -X GET "https://ryzeapi.cloud/api/instance/connect/$Instance_Name" \
  -H "token: $Token_Instance"

The response includes:

data.qrCodes, strings that can be converted into a QR
data.qrImages, base64 PNGs ready to display as an image

Scan it on your phone in WhatsApp → Linked devices → Link a device.

Ideal for environments without a camera. Pass your number in the number parameter:

curl -X GET "https://ryzeapi.cloud/api/instance/connect/$Instance_Name?number=5511999999999" \
  -H "token: $Token_Instance"

The response includes an 8-character code to enter in Linked devices → Link with code.

4. Confirm that it is connected

curl -X GET "https://ryzeapi.cloud/api/instance/list?instanceName=$Instance_Name" \
  -H "token: $Token_Instance"

Wait for the instance’s status field to become "connected".

5. Send your first message

curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Hello from RyzeAPI 👋"
  }'

6. Configure a webhook (optional)

To receive events in real time (incoming messages, delivery status, etc.):

curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "default",
    "enabled": true,
    "url": "https://your-server.com/webhook",
    "events": ["message.exchange", "group.flow", "instance.state"],
    "mediaBase64": false
  }'

Each instance accepts up to 3 simultaneous webhooks (for example: production, staging, and a logging one). See Events for the 6 available types.

Next steps

Send media and advanced features

Images, videos, audio, documents, buttons, carousels, lists, and forms.

Manage contacts and labels

Organize conversations, create labels, archive, block, and pin chats.

Authentication

Understand TokenAccount vs TokenInstance in detail.

Error types

How to interpret and handle each HTTP code.

Getting started

Fundamentals

MCP

Prerequisites

1. Set your token

2. Create an instance

3. Connect to WhatsApp

4. Confirm that it is connected

5. Send your first message

6. Configure a webhook (optional)

Next steps

Send media and advanced features

Manage contacts and labels

Authentication

Error types

​Prerequisites

​1. Set your token

​2. Create an instance

​3. Connect to WhatsApp

​4. Confirm that it is connected

​5. Send your first message

​6. Configure a webhook (optional)

​Next steps

Send media and advanced features

Manage contacts and labels

Authentication

Error types

Prerequisites

1. Set your token

2. Create an instance

3. Connect to WhatsApp

4. Confirm that it is connected

5. Send your first message

6. Configure a webhook (optional)

Next steps