New instance

Auth: TokenAccount • Rate-limit: 20/min • Idempotent: no

Description

Creates a new WhatsApp instance in your account. The instance is born disconnected, the next step is to call GET /api/instance/connect/:instance to obtain the QR code or pairing code. During creation, you can send, in the same body, the initial configuration of proxy, webhook, WebSocket, Chatwoot integration, behavior settings, and S3 storage. Each block is independent: send only what you need.

The instance is created within your account quota. If you’ve reached the limit, you receive 403 with the message Account instance quota exceeded, delete an instance you no longer use to free up space.

Failures in sub-blocks (webhook / websocket / chatwoot) do not abort the instance creation. Each block is log-and-continue: the instance is created, the sub-block appears as enabled: false or absent in the response, and the server logs describe the cause. For Chatwoot, the failure is also exposed in chatwoot.status: "error" + chatwoot.error: "<message>" in the return payload.

Examples

Minimum

Creates the instance with just the name. The TokenInstance is generated automatically by the server and returned in instance.token in the response, keep it to authenticate subsequent calls.

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

With custom token

Manually sets the TokenInstance in the token field instead of letting the server generate one. Useful for reusing a value already registered in another system, the token must be unique within your account.

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

With custom settings

Creates the instance with the settings block already defined: auto-rejects calls with a default message, keeps presence online, disables history sync, and ignores stories. Equivalent to calling POST /api/instance/settings/:instance right after.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-instance",
    "autoRejectCalls":      true,
    "callRejectMessage":    "This number does not accept calls.",
    "ignoreGroupMessages":  false,
    "keepOnlineStatus":     true,
    "autoReadMessages":     false,
    "disableHistorySync":   true,
    "ignoreStatus":         true
  }'

With proxy

Provisions the instance pointing to an authenticated SOCKS5 proxy. The password is encrypted at-rest with AES-256-GCM and is never returned in the response.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":          "my-instance",
    "proxyEnabled":  true,
    "proxyProtocol": "socks5",
    "proxyHost":     "proxy.company.com",
    "proxyPort":     "1080",
    "proxyUsername": "user",
    "proxyPassword": "proxy-password"
  }'

With webhook

In the same request, configures the default webhook to receive only the message.exchange and call.update events, with custom Authorization to validate the source. Media is not sent in base64, the destination fetches via the returned URL.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":                 "my-instance",
    "webhookEnabled":       true,
    "webhookURL":           "https://myapp.com/webhook",
    "webhookAuthorization": "Bearer secret-key-123",
    "webhookByEvents":      false,
    "webhookEvents":        ["message.exchange", "call.update"],
    "webhookMediaBase64":   false
  }'

With WebSocket

Enables real-time broadcast via WebSocket filtering by the message.exchange and call.update events. Useful for dashboards and bots that need minimum latency without exposing a public webhook endpoint.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":                 "my-instance",
    "websocketEnabled":     true,
    "websocketEvents":      ["message.exchange", "call.update"],
    "websocketMediaBase64": false
  }'

With S3

Points media storage to an AWS S3 bucket (us-east-1), with prefix media/ to organize uploads. The s3SecretKey is encrypted at-rest and never appears in the response.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "my-instance",
    "s3Enabled":    true,
    "s3Region":     "us-east-1",
    "s3Bucket":     "my-media-bucket",
    "s3AccessKey":  "AKIA...",
    "s3SecretKey":  "secret...",
    "s3Endpoint":   "https://s3.amazonaws.com",
    "s3PathPrefix": "media/"
  }'

With Chatwoot

Provisions the instance already linked to a Chatwoot inbox (WhatsApp - Orion), with active agent signature and automatic reopening of resolved conversations. If the bridge fails, the instance is created anyway and the chatwoot object returns with status: "error".

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":                  "support",
    "chatwootEnabled":       true,
    "chatwootBaseUrl":       "https://chatwoot.example.com",
    "chatwootAccountId":     5,
    "chatwootApiToken":      "sk_live_abc123...",
    "chatwootInboxName":     "WhatsApp - Orion",
    "chatwootSignMessages":  true,
    "chatwootIgnoreGroups":  false,
    "chatwootStartAsPending": false,
    "chatwootReopenResolved": true
  }'

Complete

Combines every block in the same request: custom token, SOCKS5 proxy, webhook, WebSocket, Chatwoot integration, behavior settings, and S3 storage. Each block remains independent, failures in sub-blocks don’t abort the instance creation.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":  "marketing",
    "token": "my-custom-token-123",

    "proxyEnabled":  true,
    "proxyProtocol": "socks5",
    "proxyHost":     "proxy.company.com",
    "proxyPort":     "1080",
    "proxyUsername": "user",
    "proxyPassword": "proxy-password",

    "webhookEnabled":       true,
    "webhookURL":           "https://myserver.com/webhook",
    "webhookAuthorization": "Bearer secret-key-123",
    "webhookByEvents":      false,
    "webhookEvents":        ["message.exchange", "call.update"],
    "webhookMediaBase64":   false,

    "websocketEnabled":     true,
    "websocketEvents":      ["message.exchange", "call.update"],
    "websocketMediaBase64": false,

    "chatwootEnabled":        true,
    "chatwootBaseUrl":        "https://chatwoot.example.com",
    "chatwootAccountId":      5,
    "chatwootApiToken":       "sk_live_abc123...",
    "chatwootInboxName":      "Marketing",
    "chatwootSignMessages":   true,
    "chatwootIgnoreGroups":   false,
    "chatwootStartAsPending": false,
    "chatwootReopenResolved": true,

    "autoRejectCalls":     true,
    "callRejectMessage":   "This number does not accept calls.",
    "ignoreGroupMessages": false,
    "keepOnlineStatus":    true,
    "autoReadMessages":    false,
    "disableHistorySync":  false,
    "ignoreStatus":        true,

    "s3Enabled":    true,
    "s3Region":     "us-east-1",
    "s3Bucket":     "my-media-bucket",
    "s3AccessKey":  "AKIA...",
    "s3SecretKey":  "secret...",
    "s3Endpoint":   "https://s3.amazonaws.com",
    "s3PathPrefix": "media/"
  }'

Success response

The response includes the generated TokenInstance and the summary of every configured integration (proxy, webhook, websocket, chatwoot, settings, s3). Save the instance.token, it’s what authenticates subsequent calls of the instance itself.

201 Created

{
  "success": true,
  "message": "Instance created",
  "instance": {
    "id": "5e1d...",
    "name": "my-instance",
    "token": "a1b2c3d4-...",
    "status": "disconnected",
    "numberJid": null,
    "proxy": {
      "enabled": false,
      "host": null,
      "port": null,
      "protocol": null,
      "username": null,
      "password": null
    },
    "webhook": {
      "enabled": true,
      "url": "https://myapp.com/webhook",
      "events": ["message.exchange", "call.update"]
    },
    "websocket": {
      "enabled": true,
      "events": ["message.exchange"],
      "mediaBase64": false
    },
    "chatwoot": {
      "enabled": true,
      "status": "active",
      "bridgeIntegrationId": "int_xyz789abc",
      "baseUrl": "https://chatwoot.example.com",
      "accountId": 5,
      "inboxName": "WhatsApp - Orion"
    },
    "settings": {
      "autoRejectCalls": false,
      "callRejectMessage": "",
      "ignoreGroupMessages": false,
      "keepOnlineStatus": false,
      "autoReadMessages": false,
      "disableHistorySync": true,
      "ignoreStatus": false
    },
    "s3": {
      "enabled": false,
      "region": null,
      "bucket": null,
      "accessKey": null,
      "secretKey": null,
      "endpoint": null,
      "pathPrefix": null
    },
    "createdAt": "2026-04-28T10:30:00Z",
    "updatedAt": "2026-04-28T10:30:00Z"
  }
}

The chatwootApiToken is never returned by the API (even in this response). The s3.secretKey and the proxy.password are not either.

Chatwoot with error

If the chatwoot* block was sent but the configuration failed (e.g., invalid token), the instance is created anyway and the chatwoot object in the response comes with status: "error" and an actionable error:

"chatwoot": {
  "enabled": false,
  "status": "error",
  "error": "Chatwoot API returned 401 — check the chatwootApiToken"
}

You can fix the credentials via POST /api/chatwoot/set/:instance without recreating the instance.

Headers

token

string

required

Your TokenAccount.

Content-Type

string

required

application/json

Request body

name

string

required

Instance identifier (used in the :instance paths in every other endpoint). Cannot be blank and must be unique within your account. Kebab-case or snake_case is recommended.

token

string

Custom token for the instance. If omitted, it’s generated automatically (recommended).

Proxy block (optional)

proxyEnabled

boolean

Enables the use of a proxy specific to this instance.

proxyHost

string

Proxy IP or hostname.

proxyPort

string

Port as a string (e.g., "8080").

proxyProtocol

string

http, https, or socks5.

proxyUsername

string

Proxy user (optional).

proxyPassword

string

Proxy password (optional, encrypted at-rest with AES-256-GCM).

Webhook block (optional)

webhookEnabled

boolean

Enables sending events to a URL.

webhookURL

string

URL where RyzeAPI will POST the events.

webhookAuthorization

string

Value RyzeAPI sends in the Authorization header of each POST (useful to validate origin). Ex.: Bearer secret-key-123.

webhookByEvents

boolean

If true, each event type can have its own URL (default: false).

webhookEvents

string[]

List of events the instance should dispatch. Ex.: ["message.exchange", "call.update"].

webhookMediaBase64

boolean

Includes received media as base64 inside the webhook body.

The webhook block creates one webhook with label default. For multiple webhooks per instance, use POST /api/events/webhook afterwards.

WebSocket block (optional)

websocketEnabled

boolean

Enables event broadcasting via WebSocket for this instance.

websocketEvents

string[]

List of events that will be emitted via WebSocket. If empty with websocketEnabled=true, all events are emitted.

websocketMediaBase64

boolean

Includes received media as base64 in the WebSocket frames.

Chatwoot block (optional)

chatwootEnabled

boolean

Enables the Chatwoot integration via the RyzeIntegrations bridge.

chatwootBaseUrl

string

URL of the Chatwoot installation (e.g., https://chatwoot.example.com). Required if chatwootEnabled=true.

chatwootAccountId

integer

Numeric ID of the Chatwoot account. Required if chatwootEnabled=true.

chatwootApiToken

string

Chatwoot account API token (the agent’s access_token). Required if chatwootEnabled=true. Encrypted at-rest and never returned by the API.

chatwootInboxName

string

Name of the inbox that will be created in Chatwoot (e.g., "WhatsApp - Orion").

chatwootSignMessages

boolean

If true, messages sent through the API are prefixed with the Chatwoot agent signature.

chatwootIgnoreGroups

boolean

If true, group messages do not become conversations in Chatwoot.

chatwootStartAsPending

boolean

If true, new conversations start as pending instead of open.

chatwootReopenResolved

boolean

If true, new messages on resolved conversations reopen them automatically.

The integration depends on the RyzeIntegrations bridge being configured on the server. If the bridge isn’t available, the instance creation continues and chatwoot returns enabled: false (the failure shows up in the server logs). See chatwoot.md for details.

Settings block (optional)

autoRejectCalls

boolean

Automatically rejects incoming calls.

callRejectMessage

string

Automatic message sent to the caller when the call is rejected.

ignoreGroupMessages

boolean

Does not process group messages (useful for 1-to-1 bots).

keepOnlineStatus

boolean

Keeps the instance marked as “online” in WhatsApp.

autoReadMessages

boolean

Automatically marks received messages as read.

disableHistorySync

boolean

default:"true"

Default true (history is not synced on the first connection). Send false if you want to receive the backlog.

ignoreStatus

boolean

Ignores “status” type messages (stories).

S3 block (optional, media storage)

s3Enabled

boolean

Enables uploading received media to S3 or MinIO.

s3Region

string

Region (e.g., us-east-1).

s3Bucket

string

Bucket name.

s3AccessKey

string

Access Key ID.

s3SecretKey

string

Secret Access Key (encrypted at-rest, never returned).

s3Endpoint

string

Custom endpoint for MinIO or DigitalOcean Spaces. Omit for official AWS S3.

s3PathPrefix

string

Path prefix (e.g., media/).

Errors

HTTP	`error.message`	When
400	`Invalid request body`	Malformed JSON
400	`The 'name' field is required`	`name` missing or blank
401	`Invalid token`	Invalid TokenAccount
403	`Account instance quota exceeded`	Instance quota reached
409	`Instance or token already exists`	Name or token already in use
429	`Rate limit exceeded. Try again later.`	More than 20 creations per minute
500	`Failed to create instance`	Internal error

Error example:

{
  "success": false,
  "error": {
    "message": "Instance or token already exists"
  }
}

Connect to WhatsApp

Generate the QR code or pairing code to link the number.

Check state

Use GET /api/instance/list?instanceName=<name> to inspect the current status.

Introduction

Instance

Events

Messages

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Observability

Description

Examples

Minimum

With custom token

With custom settings

With proxy

With webhook

With WebSocket

With S3

With Chatwoot

Complete

Success response

Chatwoot with error

Headers

Request body

Proxy block (optional)

Webhook block (optional)

WebSocket block (optional)

Chatwoot block (optional)

Settings block (optional)

S3 block (optional, media storage)

Errors

Next

Connect to WhatsApp

Check state

Introduction

Instance

Events

Messages

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Observability

Documentation Index

​Description

​Examples

​Minimum

​With custom token

​With custom settings

​With proxy

​With webhook

​With WebSocket

​With S3

​With Chatwoot

​Complete

​Success response

​Chatwoot with error

​Headers

​Request body

​Proxy block (optional)

​Webhook block (optional)

​WebSocket block (optional)

​Chatwoot block (optional)

​Settings block (optional)

​S3 block (optional, media storage)

​Errors

​Next

Connect to WhatsApp

Check state

Description

Examples

Minimum

With custom token

With custom settings

With proxy

With webhook

With WebSocket

With S3

With Chatwoot

Complete

Success response

Chatwoot with error

Headers

Request body

Proxy block (optional)

Webhook block (optional)

WebSocket block (optional)

Chatwoot block (optional)

Settings block (optional)

S3 block (optional, media storage)

Errors

Next