New instance - RyzeAPI

POST

api

instance

new

New instance

curl --request POST \
  --url https://api.example.com/api/instance/new \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "name": "<string>",
  "token": "<string>",
  "proxyEnabled": true,
  "proxyHost": "<string>",
  "proxyPort": "<string>",
  "proxyProtocol": "<string>",
  "proxyUsername": "<string>",
  "proxyPassword": "<string>",
  "webhookEnabled": true,
  "webhookURL": "<string>",
  "webhookAuthorization": "<string>",
  "webhookByEvents": true,
  "webhookEvents": [
    "<string>"
  ],
  "webhookMediaBase64": true,
  "websocketEnabled": true,
  "websocketEvents": [
    "<string>"
  ],
  "websocketMediaBase64": true,
  "chatwootEnabled": true,
  "chatwootBaseUrl": "<string>",
  "chatwootAccountId": 123,
  "chatwootApiToken": "<string>",
  "chatwootInboxName": "<string>",
  "chatwootSignMessages": true,
  "chatwootIgnoreGroups": true,
  "chatwootStartAsPending": true,
  "chatwootReopenResolved": true,
  "typebotEnabled": true,
  "typebotUrl": "<string>",
  "typebotTriggerType": "<string>",
  "typebotTriggerOperator": "<string>",
  "typebotTriggerValue": "<string>",
  "typebotExpireMinutes": 123,
  "typebotExpireMessage": "<string>",
  "typebotKeywordFinish": "<string>",
  "typebotFinishMessage": "<string>",
  "typebotTypingDelayMs": 123,
  "typebotStopBotFromMe": true,
  "typebotDebounceSeconds": 123,
  "typebotIgnoreGroups": true,
  "typebotDescription": "<string>",
  "autoRejectCalls": true,
  "callRejectMessage": "<string>",
  "ignoreGroupMessages": true,
  "keepOnlineStatus": true,
  "autoReadMessages": true,
  "disableHistorySync": true,
  "ignoreStatus": true,
  "s3Enabled": true,
  "s3Region": "<string>",
  "s3Bucket": "<string>",
  "s3AccessKey": "<string>",
  "s3SecretKey": "<string>",
  "s3Endpoint": "<string>",
  "s3PathPrefix": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {token: '<token>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    name: '<string>',
    token: '<string>',
    proxyEnabled: true,
    proxyHost: '<string>',
    proxyPort: '<string>',
    proxyProtocol: '<string>',
    proxyUsername: '<string>',
    proxyPassword: '<string>',
    webhookEnabled: true,
    webhookURL: '<string>',
    webhookAuthorization: '<string>',
    webhookByEvents: true,
    webhookEvents: ['<string>'],
    webhookMediaBase64: true,
    websocketEnabled: true,
    websocketEvents: ['<string>'],
    websocketMediaBase64: true,
    chatwootEnabled: true,
    chatwootBaseUrl: '<string>',
    chatwootAccountId: 123,
    chatwootApiToken: '<string>',
    chatwootInboxName: '<string>',
    chatwootSignMessages: true,
    chatwootIgnoreGroups: true,
    chatwootStartAsPending: true,
    chatwootReopenResolved: true,
    typebotEnabled: true,
    typebotUrl: '<string>',
    typebotTriggerType: '<string>',
    typebotTriggerOperator: '<string>',
    typebotTriggerValue: '<string>',
    typebotExpireMinutes: 123,
    typebotExpireMessage: '<string>',
    typebotKeywordFinish: '<string>',
    typebotFinishMessage: '<string>',
    typebotTypingDelayMs: 123,
    typebotStopBotFromMe: true,
    typebotDebounceSeconds: 123,
    typebotIgnoreGroups: true,
    typebotDescription: '<string>',
    autoRejectCalls: true,
    callRejectMessage: '<string>',
    ignoreGroupMessages: true,
    keepOnlineStatus: true,
    autoReadMessages: true,
    disableHistorySync: true,
    ignoreStatus: true,
    s3Enabled: true,
    s3Region: '<string>',
    s3Bucket: '<string>',
    s3AccessKey: '<string>',
    s3SecretKey: '<string>',
    s3Endpoint: '<string>',
    s3PathPrefix: '<string>'
  })
};

fetch('https://api.example.com/api/instance/new', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/instance/new"

payload = {
    "name": "<string>",
    "token": "<string>",
    "proxyEnabled": True,
    "proxyHost": "<string>",
    "proxyPort": "<string>",
    "proxyProtocol": "<string>",
    "proxyUsername": "<string>",
    "proxyPassword": "<string>",
    "webhookEnabled": True,
    "webhookURL": "<string>",
    "webhookAuthorization": "<string>",
    "webhookByEvents": True,
    "webhookEvents": ["<string>"],
    "webhookMediaBase64": True,
    "websocketEnabled": True,
    "websocketEvents": ["<string>"],
    "websocketMediaBase64": True,
    "chatwootEnabled": True,
    "chatwootBaseUrl": "<string>",
    "chatwootAccountId": 123,
    "chatwootApiToken": "<string>",
    "chatwootInboxName": "<string>",
    "chatwootSignMessages": True,
    "chatwootIgnoreGroups": True,
    "chatwootStartAsPending": True,
    "chatwootReopenResolved": True,
    "typebotEnabled": True,
    "typebotUrl": "<string>",
    "typebotTriggerType": "<string>",
    "typebotTriggerOperator": "<string>",
    "typebotTriggerValue": "<string>",
    "typebotExpireMinutes": 123,
    "typebotExpireMessage": "<string>",
    "typebotKeywordFinish": "<string>",
    "typebotFinishMessage": "<string>",
    "typebotTypingDelayMs": 123,
    "typebotStopBotFromMe": True,
    "typebotDebounceSeconds": 123,
    "typebotIgnoreGroups": True,
    "typebotDescription": "<string>",
    "autoRejectCalls": True,
    "callRejectMessage": "<string>",
    "ignoreGroupMessages": True,
    "keepOnlineStatus": True,
    "autoReadMessages": True,
    "disableHistorySync": True,
    "ignoreStatus": True,
    "s3Enabled": True,
    "s3Region": "<string>",
    "s3Bucket": "<string>",
    "s3AccessKey": "<string>",
    "s3SecretKey": "<string>",
    "s3Endpoint": "<string>",
    "s3PathPrefix": "<string>"
}
headers = {
    "token": "<token>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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, Typebot 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"}'

const response = await fetch("https://ryzeapi.cloud/api/instance/new", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "my-instance" })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/new",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={"name": "my-instance"}
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{"name":"my-instance"}`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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"
  }'

await fetch("https://ryzeapi.cloud/api/instance/new", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name:  "my-instance",
    token: "my-custom-token-123"
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/new",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={
        "name":  "my-instance",
        "token": "my-custom-token-123"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "name":  "my-instance",
        "token": "my-custom-token-123"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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
  }'

await fetch("https://ryzeapi.cloud/api/instance/new", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name:                "my-instance",
    autoRejectCalls:     true,
    callRejectMessage:   "This number does not accept calls.",
    ignoreGroupMessages: false,
    keepOnlineStatus:    true,
    autoReadMessages:    false,
    disableHistorySync:  true,
    ignoreStatus:        true
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/new",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={
        "name":                "my-instance",
        "autoRejectCalls":     True,
        "callRejectMessage":   "This number does not accept calls.",
        "ignoreGroupMessages": False,
        "keepOnlineStatus":    True,
        "autoReadMessages":    False,
        "disableHistorySync":  True,
        "ignoreStatus":        True
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "name":                "my-instance",
        "autoRejectCalls":     true,
        "callRejectMessage":   "This number does not accept calls.",
        "ignoreGroupMessages": false,
        "keepOnlineStatus":    true,
        "autoReadMessages":    false,
        "disableHistorySync":  true,
        "ignoreStatus":        true
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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"
  }'

await fetch("https://ryzeapi.cloud/api/instance/new", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name:          "my-instance",
    proxyEnabled:  true,
    proxyProtocol: "socks5",
    proxyHost:     "proxy.company.com",
    proxyPort:     "1080",
    proxyUsername: "user",
    proxyPassword: "proxy-password"
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/new",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={
        "name":          "my-instance",
        "proxyEnabled":  True,
        "proxyProtocol": "socks5",
        "proxyHost":     "proxy.company.com",
        "proxyPort":     "1080",
        "proxyUsername": "user",
        "proxyPassword": "proxy-password"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "name":          "my-instance",
        "proxyEnabled":  true,
        "proxyProtocol": "socks5",
        "proxyHost":     "proxy.company.com",
        "proxyPort":     "1080",
        "proxyUsername": "user",
        "proxyPassword": "proxy-password"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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
  }'

await fetch("https://ryzeapi.cloud/api/instance/new", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name:                 "my-instance",
    webhookEnabled:       true,
    webhookURL:           "https://myapp.com/webhook",
    webhookAuthorization: "Bearer secret-key-123",
    webhookByEvents:      false,
    webhookEvents:        ["message.exchange", "call.update"],
    webhookMediaBase64:   false
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/new",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={
        "name":                 "my-instance",
        "webhookEnabled":       True,
        "webhookURL":           "https://myapp.com/webhook",
        "webhookAuthorization": "Bearer secret-key-123",
        "webhookByEvents":      False,
        "webhookEvents":        ["message.exchange", "call.update"],
        "webhookMediaBase64":   False
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "name":                 "my-instance",
        "webhookEnabled":       true,
        "webhookURL":           "https://myapp.com/webhook",
        "webhookAuthorization": "Bearer secret-key-123",
        "webhookByEvents":      false,
        "webhookEvents":        ["message.exchange", "call.update"],
        "webhookMediaBase64":   false
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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
  }'

await fetch("https://ryzeapi.cloud/api/instance/new", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name:                 "my-instance",
    websocketEnabled:     true,
    websocketEvents:      ["message.exchange", "call.update"],
    websocketMediaBase64: false
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/new",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={
        "name":                 "my-instance",
        "websocketEnabled":     True,
        "websocketEvents":      ["message.exchange", "call.update"],
        "websocketMediaBase64": False
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "name":                 "my-instance",
        "websocketEnabled":     true,
        "websocketEvents":      ["message.exchange", "call.update"],
        "websocketMediaBase64": false
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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/"
  }'

await fetch("https://ryzeapi.cloud/api/instance/new", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name:         "my-instance",
    s3Enabled:    true,
    s3Region:     "us-east-1",
    s3Bucket:     "my-media-bucket",
    s3AccessKey:  "AKIA...",
    s3SecretKey:  "secret...",
    s3Endpoint:   "https://s3.amazonaws.com",
    s3PathPrefix: "media/"
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/new",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={
        "name":         "my-instance",
        "s3Enabled":    True,
        "s3Region":     "us-east-1",
        "s3Bucket":     "my-media-bucket",
        "s3AccessKey":  "AKIA...",
        "s3SecretKey":  "secret...",
        "s3Endpoint":   "https://s3.amazonaws.com",
        "s3PathPrefix": "media/"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "name":         "my-instance",
        "s3Enabled":    true,
        "s3Region":     "us-east-1",
        "s3Bucket":     "my-media-bucket",
        "s3AccessKey":  "AKIA...",
        "s3SecretKey":  "secret...",
        "s3Endpoint":   "https://s3.amazonaws.com",
        "s3PathPrefix": "media/"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

With Chatwoot

Provisions the instance already linked to a Chatwoot inbox (WhatsApp - Orion), with active agent signature and automatic reopening of resolved conversations. If Chatwoot activation 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
  }'

await fetch("https://ryzeapi.cloud/api/instance/new", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    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
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/new",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={
        "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
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "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
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

With Typebot

Provisions the instance already with a Typebot bot registered. This block configures a single bot; add more later via POST /api/typebot/set/:instance. If activation fails (bridge unavailable or invalid fields), the instance is created anyway and the typebot 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":                    "suporte",
    "typebotEnabled":          true,
    "typebotUrl":              "https://typebot.co/meu-bot-abc123",
    "typebotTriggerType":      "keyword",
    "typebotTriggerOperator":  "contains",
    "typebotTriggerValue":     "orçamento",
    "typebotExpireMinutes":    30,
    "typebotKeywordFinish":    "sair",
    "typebotFinishMessage":    "Até logo! 👋",
    "typebotTypingDelayMs":    1500,
    "typebotStopBotFromMe":    true,
    "typebotDebounceSeconds":  6,
    "typebotIgnoreGroups":     true,
    "typebotDescription":      "Bot de orçamento"
  }'

await fetch("https://ryzeapi.cloud/api/instance/new", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name:                   "suporte",
    typebotEnabled:         true,
    typebotUrl:             "https://typebot.co/meu-bot-abc123",
    typebotTriggerType:     "keyword",
    typebotTriggerOperator: "contains",
    typebotTriggerValue:    "orçamento",
    typebotExpireMinutes:   30,
    typebotKeywordFinish:   "sair",
    typebotFinishMessage:   "Até logo! 👋",
    typebotTypingDelayMs:   1500,
    typebotStopBotFromMe:   true,
    typebotDebounceSeconds: 6,
    typebotIgnoreGroups:    true,
    typebotDescription:     "Bot de orçamento"
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/new",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={
        "name":                   "suporte",
        "typebotEnabled":         True,
        "typebotUrl":             "https://typebot.co/meu-bot-abc123",
        "typebotTriggerType":     "keyword",
        "typebotTriggerOperator": "contains",
        "typebotTriggerValue":    "orçamento",
        "typebotExpireMinutes":   30,
        "typebotKeywordFinish":   "sair",
        "typebotFinishMessage":   "Até logo! 👋",
        "typebotTypingDelayMs":   1500,
        "typebotStopBotFromMe":   True,
        "typebotDebounceSeconds": 6,
        "typebotIgnoreGroups":    True,
        "typebotDescription":     "Bot de orçamento"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "name":                   "suporte",
        "typebotEnabled":         true,
        "typebotUrl":             "https://typebot.co/meu-bot-abc123",
        "typebotTriggerType":     "keyword",
        "typebotTriggerOperator": "contains",
        "typebotTriggerValue":    "orçamento",
        "typebotExpireMinutes":   30,
        "typebotKeywordFinish":   "sair",
        "typebotFinishMessage":   "Até logo! 👋",
        "typebotTypingDelayMs":   1500,
        "typebotStopBotFromMe":   true,
        "typebotDebounceSeconds": 6,
        "typebotIgnoreGroups":    true,
        "typebotDescription":     "Bot de orçamento"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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/"
  }'

await fetch("https://ryzeapi.cloud/api/instance/new", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    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/"
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/new",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={
        "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/"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "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/"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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"
    },
    "typebot": {
      "enabled": true,
      "status": "active",
      "bridgeIntegrationId": "int_tb456def",
      "botId": "8f3a1c2e-...-b7d9",
      "typebotUrl": "https://typebot.co/meu-bot-abc123",
      "triggerType": "keyword"
    },
    "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 not returned in this response (it is exposed in plaintext only by GET /api/chatwoot/list/:instance). The s3.secretKey and the proxy.password are never returned by any endpoint.

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.

Typebot with error

If the typebot* block was sent but the configuration failed (e.g., bridge not configured on the server, missing typebotUrl, or invalid typebotTriggerType), the instance is created anyway and the typebot object in the response comes with status: "error" and an actionable error:

"typebot": {
  "enabled": false,
  "status": "error",
  "error": "typebotUrl and typebotTriggerType are required to activate the Typebot integration."
}

You can configure the bot later via POST /api/typebot/set/:instance without recreating the instance.

Headers

string

required

Your TokenAccount.

string

required

application/json

Request body

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.

string

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

Proxy block (optional)

boolean

Enables the use of a proxy specific to this instance.

string

Proxy IP or hostname.

string

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

string

http, https, or socks5.

string

Proxy user (optional).

string

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

Webhook block (optional)

boolean

Enables sending events to a URL.

string

URL where RyzeAPI will POST the events.

string

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

boolean

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

string[]

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

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)

boolean

Enables event broadcasting via WebSocket for this instance.

string[]

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

boolean

Includes received media as base64 in the WebSocket frames.

Chatwoot block (optional)

boolean

Enables the Chatwoot integration.

string

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

integer

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

string

Chatwoot account API token (the agent’s access_token). Required if chatwootEnabled=true. Encrypted at-rest. Not returned in this response, but exposed in plaintext by GET /api/chatwoot/list/:instance.

string

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

boolean

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

boolean

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

boolean

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

boolean

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

The Chatwoot integration must be enabled on the server. If it isn’t available, the instance creation continues and chatwoot returns enabled: false (the failure shows up in the server logs). See the Chatwoot overview for details.

Typebot block (optional)

Configures a single Typebot bot together with instance creation. For multiple bots, use POST /api/typebot/set/:instance afterwards. See the Typebot overview for routing by trigger.

boolean

Enables the Typebot integration.

string

URL of the published Typebot (viewer). Required if typebotEnabled=true. Ex.: https://typebot.co/meu-bot-abc123.

string

How the bot is triggered: all (any message) or keyword. Required if typebotEnabled=true.

string

Trigger operator, required if typebotTriggerType is keyword. One of: contains, equals, startsWith, endsWith, regex.

string

Trigger word/expression, required if typebotTriggerType is keyword.

integer

default:"0"

Expires the session by inactivity after N minutes (0 = never).

string

Message sent to the user when the session expires.

string

Word that ends the bot immediately (e.g., "sair").

string

Farewell sent when the bot is ended by the typebotKeywordFinish.

integer

default:"0"

Delay of the “typing…” indicator before each reply, in milliseconds.

boolean

default:"false"

If true, pauses the bot in that conversation when the operator replies manually.

integer

default:"0"

Groups fragments sent by the customer for N seconds before processing.

boolean

default:"true"

If true, group messages do not trigger the bot. Absent equals true.

string

Bot label in the panel (e.g., "Bot de orçamento").

The Typebot integration needs the Ryze Bridge configured on the server. If it isn’t available, the instance creation continues and typebot returns status: "error" with the cause. Configure the bot later via POST /api/typebot/set/:instance.

Settings block (optional)

boolean

Automatically rejects incoming calls.

string

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

boolean

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

boolean

Keeps the instance marked as “online” in WhatsApp.

boolean

Automatically marks received messages as read.

boolean

default:"true"

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

boolean

Ignores “status” type messages (stories).

S3 block (optional, media storage)

boolean

Enables uploading received media to S3 or MinIO.

string

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

string

Bucket name.

string

Access Key ID.

string

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

string

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

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.

​Description

​Examples

​Minimum

​With custom token

​With custom settings

​With proxy

​With webhook

​With WebSocket

​With S3

​With Chatwoot

​With Typebot

​Complete

​Success response

​Chatwoot with error

​Typebot with error

​Headers

​Request body

​Proxy block (optional)

​Webhook block (optional)

​WebSocket block (optional)

​Chatwoot block (optional)

​Typebot 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

With Typebot

Complete

Success response

Chatwoot with error

Typebot with error

Headers

Request body

Proxy block (optional)

Webhook block (optional)

WebSocket block (optional)

Chatwoot block (optional)

Typebot block (optional)

Settings block (optional)

S3 block (optional, media storage)

Errors

Next