Nova instância

POST

api

instance

new

Nova instância

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 • Idempotente: não

Descrição

Cria uma nova instância de WhatsApp na sua conta. A instância nasce desconectada, o próximo passo é chamar GET /api/instance/connect/:instance para obter o QR code ou pairing code. Durante a criação, você pode enviar, no mesmo body, a configuração inicial de proxy, webhook, WebSocket, integração Chatwoot, integração Typebot, ajustes de comportamento e armazenamento S3. Cada bloco é independente: passe apenas o que precisar.

A instância é criada dentro da cota da sua conta. Se você atingiu o limite, recebe 403 com mensagem Account instance quota exceeded, delete uma instância que não está mais usando para liberar espaço.

Falhas em sub-blocos (webhook / websocket / chatwoot) não abortam a criação da instância. Cada bloco é log-and-continue: a instância é criada, o sub-bloco aparece como enabled: false ou ausente na resposta, e os logs do servidor descrevem a causa. Para Chatwoot, a falha também é exposta em chatwoot.status: "error" + chatwoot.error: "<mensagem>" no payload de retorno.

Exemplos

Mínimo

Cria a instância só com o name. O TokenInstance é gerado automaticamente pelo servidor e devolvido em instance.token na resposta, guarde-o para autenticar chamadas subsequentes.

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

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: "minha-instancia" })
});

import os, requests

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

package main

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

func main() {
    body := strings.NewReader(`{"name":"minha-instancia"}`)
    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)
}

Com Token personalizado

Define manualmente o TokenInstance no campo token em vez de deixar o servidor gerar. Útil para reutilizar um valor já cadastrado em outro sistema, o token precisa ser único na sua conta.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":  "minha-instancia",
    "token": "meu-token-customizado-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:  "minha-instancia",
    token: "meu-token-customizado-123"
  })
});

import os, requests

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

package main

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

func main() {
    body := strings.NewReader(`{
        "name":  "minha-instancia",
        "token": "meu-token-customizado-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)
}

Com configurações personalizadas

Cria a instância já com o bloco de settings definido: rejeita chamadas automaticamente com mensagem padrão, mantém presença online, desativa sync de histórico e ignora stories. Equivale a chamar POST /api/instance/settings/:instance logo depois.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "minha-instancia",
    "autoRejectCalls":      true,
    "callRejectMessage":    "Este número não aceita ligações.",
    "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:                "minha-instancia",
    autoRejectCalls:     true,
    callRejectMessage:   "Este número não aceita ligações.",
    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":                "minha-instancia",
        "autoRejectCalls":     True,
        "callRejectMessage":   "Este número não aceita ligações.",
        "ignoreGroupMessages": False,
        "keepOnlineStatus":    True,
        "autoReadMessages":    False,
        "disableHistorySync":  True,
        "ignoreStatus":        True
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "name":                "minha-instancia",
        "autoRejectCalls":     true,
        "callRejectMessage":   "Este número não aceita ligações.",
        "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)
}

Com Proxy

Já provisiona a instância apontando para um proxy SOCKS5 autenticado. A senha é encriptada at-rest com AES-256-GCM e nunca volta na resposta.

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

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

import os, requests

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

package main

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

func main() {
    body := strings.NewReader(`{
        "name":          "minha-instancia",
        "proxyEnabled":  true,
        "proxyProtocol": "socks5",
        "proxyHost":     "proxy.empresa.com",
        "proxyPort":     "1080",
        "proxyUsername": "usuario",
        "proxyPassword": "senha-do-proxy"
    }`)
    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)
}

Com Webhook

Configura, no mesmo request, o webhook default recebendo apenas os eventos message.exchange e call.update, com Authorization custom para validar a origem. Mídias não vão em base64, o destino busca pela URL retornada.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":                 "minha-instancia",
    "webhookEnabled":       true,
    "webhookURL":           "https://meuapp.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:                 "minha-instancia",
    webhookEnabled:       true,
    webhookURL:           "https://meuapp.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":                 "minha-instancia",
        "webhookEnabled":       True,
        "webhookURL":           "https://meuapp.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":                 "minha-instancia",
        "webhookEnabled":       true,
        "webhookURL":           "https://meuapp.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)
}

Com Websocket

Habilita o broadcast em tempo real via WebSocket filtrando pelos eventos message.exchange e call.update. Útil para dashboards e bots que precisam de latência mínima sem expor um endpoint público para webhook.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":                 "minha-instancia",
    "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:                 "minha-instancia",
    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":                 "minha-instancia",
        "websocketEnabled":     True,
        "websocketEvents":      ["message.exchange", "call.update"],
        "websocketMediaBase64": False
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "name":                 "minha-instancia",
        "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)
}

Com S3

Já aponta o storage de mídia para um bucket AWS S3 (us-east-1), com prefixo media/ para organizar uploads. A s3SecretKey é encriptada at-rest e nunca aparece na resposta.

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "minha-instancia",
    "s3Enabled":    true,
    "s3Region":     "us-east-1",
    "s3Bucket":     "meu-bucket-media",
    "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:         "minha-instancia",
    s3Enabled:    true,
    s3Region:     "us-east-1",
    s3Bucket:     "meu-bucket-media",
    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":         "minha-instancia",
        "s3Enabled":    True,
        "s3Region":     "us-east-1",
        "s3Bucket":     "meu-bucket-media",
        "s3AccessKey":  "AKIA...",
        "s3SecretKey":  "secret...",
        "s3Endpoint":   "https://s3.amazonaws.com",
        "s3PathPrefix": "media/"
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "name":         "minha-instancia",
        "s3Enabled":    true,
        "s3Region":     "us-east-1",
        "s3Bucket":     "meu-bucket-media",
        "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)
}

Com Chatwoot

Provisiona a instância já vinculada a um inbox Chatwoot (WhatsApp - Orion), com assinatura de agente ativa e reabertura automática de conversas resolvidas. Se a ativação do Chatwoot falhar, a instância é criada mesmo assim e o objeto chatwoot volta com status: "error".

curl -X POST "https://ryzeapi.cloud/api/instance/new" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "name":                  "suporte",
    "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:                   "suporte",
    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":                   "suporte",
        "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":                   "suporte",
        "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)
}

Com Typebot

Provisiona a instância já com um bot do Typebot cadastrado. Este bloco configura um único bot; adicione mais depois via POST /api/typebot/set/:instance. Se a ativação falhar (bridge indisponível ou campos inválidos), a instância é criada mesmo assim e o objeto typebot volta com 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)
}

Completo

Combina todos os blocos no mesmo request: token custom, proxy SOCKS5, webhook, WebSocket, integração Chatwoot, settings de comportamento e storage S3. Cada bloco continua independente, falhas em sub-blocos não abortam a criação da instância.

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

    "proxyEnabled":  true,
    "proxyProtocol": "socks5",
    "proxyHost":     "proxy.empresa.com",
    "proxyPort":     "1080",
    "proxyUsername": "usuario",
    "proxyPassword": "senha-do-proxy",

    "webhookEnabled":       true,
    "webhookURL":           "https://meuservidor.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":   "Este número não aceita ligações.",
    "ignoreGroupMessages": false,
    "keepOnlineStatus":    true,
    "autoReadMessages":    false,
    "disableHistorySync":  false,
    "ignoreStatus":        true,

    "s3Enabled":    true,
    "s3Region":     "us-east-1",
    "s3Bucket":     "meu-bucket-media",
    "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: "meu-token-customizado-123",

    proxyEnabled:  true,
    proxyProtocol: "socks5",
    proxyHost:     "proxy.empresa.com",
    proxyPort:     "1080",
    proxyUsername: "usuario",
    proxyPassword: "senha-do-proxy",

    webhookEnabled:       true,
    webhookURL:           "https://meuservidor.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:   "Este número não aceita ligações.",
    ignoreGroupMessages: false,
    keepOnlineStatus:    true,
    autoReadMessages:    false,
    disableHistorySync:  false,
    ignoreStatus:        true,

    s3Enabled:    true,
    s3Region:     "us-east-1",
    s3Bucket:     "meu-bucket-media",
    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": "meu-token-customizado-123",

        "proxyEnabled":  True,
        "proxyProtocol": "socks5",
        "proxyHost":     "proxy.empresa.com",
        "proxyPort":     "1080",
        "proxyUsername": "usuario",
        "proxyPassword": "senha-do-proxy",

        "webhookEnabled":       True,
        "webhookURL":           "https://meuservidor.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":   "Este número não aceita ligações.",
        "ignoreGroupMessages": False,
        "keepOnlineStatus":    True,
        "autoReadMessages":    False,
        "disableHistorySync":  False,
        "ignoreStatus":        True,

        "s3Enabled":    True,
        "s3Region":     "us-east-1",
        "s3Bucket":     "meu-bucket-media",
        "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": "meu-token-customizado-123",

        "proxyEnabled":  true,
        "proxyProtocol": "socks5",
        "proxyHost":     "proxy.empresa.com",
        "proxyPort":     "1080",
        "proxyUsername": "usuario",
        "proxyPassword": "senha-do-proxy",

        "webhookEnabled":       true,
        "webhookURL":           "https://meuservidor.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":   "Este número não aceita ligações.",
        "ignoreGroupMessages": false,
        "keepOnlineStatus":    true,
        "autoReadMessages":    false,
        "disableHistorySync":  false,
        "ignoreStatus":        true,

        "s3Enabled":    true,
        "s3Region":     "us-east-1",
        "s3Bucket":     "meu-bucket-media",
        "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)
}

Resposta de sucesso

A resposta inclui o TokenInstance gerado e o resumo de cada integração configurada (proxy, webhook, websocket, chatwoot, settings, s3). Guarde o instance.token, é com ele que você autentica chamadas subsequentes da própria instância.

201 Created

{
  "success": true,
  "message": "Instance created",
  "instance": {
    "id": "5e1d...",
    "name": "minha-instancia",
    "token": "a1b2c3d4-...",
    "status": "disconnected",
    "numberJid": null,
    "proxy": {
      "enabled": false,
      "host": null,
      "port": null,
      "protocol": null,
      "username": null,
      "password": null
    },
    "webhook": {
      "enabled": true,
      "url": "https://meuapp.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"
  }
}

O chatwootApiToken não é retornado nesta resposta (é exposto em plaintext apenas em GET /api/chatwoot/list/:instance). O s3.secretKey e o proxy.password nunca são retornados por nenhum endpoint.

Chatwoot com erro

Se o bloco chatwoot* foi enviado mas a configuração falhou (ex.: token inválido), a instância é criada mesmo assim e o objeto chatwoot na resposta vem com status: "error" e uma error acionável:

"chatwoot": {
  "enabled": false,
  "status": "error",
  "error": "Chatwoot API returned 401 - verifique o chatwootApiToken"
}

Você pode corrigir as credenciais via POST /api/chatwoot/set/:instance sem precisar recriar a instância.

Typebot com erro

Se o bloco typebot* foi enviado mas a configuração falhou (ex.: bridge não configurado no servidor, typebotUrl ausente ou typebotTriggerType inválido), a instância é criada mesmo assim e o objeto typebot na resposta vem com status: "error" e uma error acionável:

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

Você pode configurar o bot depois via POST /api/typebot/set/:instance sem precisar recriar a instância.

Headers

string

obrigatório

Seu TokenAccount.

string

obrigatório

application/json

Request body

string

obrigatório

Identificador da instância (usado nos paths :instance em todos os outros endpoints). Não pode estar em branco e precisa ser único na sua conta. Recomenda-se kebab-case ou snake_case.

string

Token custom para a instância. Se omitido, é gerado automaticamente (recomendado).

Bloco proxy (opcional)

boolean

Ativa uso de proxy específico para esta instância.

string

IP ou hostname do proxy.

string

Porta como string (ex.: "8080").

string

http, https ou socks5.

string

Usuário do proxy (opcional).

string

Senha do proxy (opcional, encriptada at-rest com AES-256-GCM).

Bloco webhook (opcional)

boolean

Ativa o envio de eventos para uma URL.

string

URL para onde a RyzeAPI vai fazer POST dos eventos.

string

Valor que a RyzeAPI envia no header Authorization de cada POST (útil para validar origem). Ex.: Bearer secret-key-123.

boolean

Se true, cada tipo de evento pode ter sua própria URL (padrão: false).

string[]

Lista de eventos que a instância deve despachar. Ex.: ["message.exchange", "call.update"].

boolean

Inclui mídia recebida em base64 dentro do corpo do webhook.

O bloco webhook cria um webhook com label default. Para múltiplos webhooks por instância, use POST /api/events/webhook depois.

Bloco WebSocket (opcional)

boolean

Ativa o broadcast de eventos via WebSocket para essa instância.

string[]

Lista de eventos que serão emitidos via WebSocket. Se vier vazio com websocketEnabled=true, todos os eventos são emitidos.

boolean

Inclui mídia recebida em base64 nos frames do WebSocket.

Bloco Chatwoot (opcional)

boolean

Ativa a integração Chatwoot.

string

URL da instalação Chatwoot (ex.: https://chatwoot.example.com). Obrigatório se chatwootEnabled=true.

integer

ID numérico da conta Chatwoot. Obrigatório se chatwootEnabled=true.

string

API token da conta Chatwoot (access_token do agente). Obrigatório se chatwootEnabled=true. Encriptado at-rest. Não é retornado nesta resposta, mas é exposto em plaintext em GET /api/chatwoot/list/:instance.

string

Nome do inbox que será criado no Chatwoot (ex.: "WhatsApp - Orion").

boolean

Se true, mensagens enviadas pela API são prefixadas com a assinatura do agente Chatwoot.

boolean

Se true, mensagens de grupos não viram conversas no Chatwoot.

boolean

Se true, conversas novas começam como pending em vez de open.

boolean

Se true, mensagens novas em conversas resolvidas reabrem-nas automaticamente.

A integração Chatwoot precisa estar habilitada no servidor. Se não estiver disponível, a criação da instância continua e o chatwoot retorna enabled: false (a falha aparece nos logs do servidor). Veja a visão geral do Chatwoot para detalhes.

Bloco Typebot (opcional)

Configura um único bot do Typebot junto com a criação da instância. Para vários bots, use POST /api/typebot/set/:instance depois. Veja a visão geral do Typebot para o roteamento por trigger.

boolean

Ativa a integração Typebot.

string

URL do Typebot publicado (viewer). Obrigatório se typebotEnabled=true. Ex.: https://typebot.co/meu-bot-abc123.

string

Como o bot é acionado: all (qualquer mensagem) ou keyword. Obrigatório se typebotEnabled=true.

string

Operador do gatilho, obrigatório se typebotTriggerType é keyword. Um de: contains, equals, startsWith, endsWith, regex.

string

Palavra/expressão do gatilho, obrigatória se typebotTriggerType é keyword.

integer

padrão:"0"

Expira a sessão por inatividade após N minutos (0 = nunca).

string

Mensagem enviada ao usuário quando a sessão expira.

string

Palavra que finaliza o bot imediatamente (ex.: "sair").

string

Despedida enviada quando o bot é finalizado pela typebotKeywordFinish.

integer

padrão:"0"

Delay do indicador “digitando…” antes de cada resposta, em milissegundos.

boolean

padrão:"false"

Se true, pausa o bot naquela conversa quando o operador responde manualmente.

integer

padrão:"0"

Junta fragmentos enviados pelo cliente por N segundos antes de processar.

boolean

padrão:"true"

Se true, mensagens de grupo não acionam o bot. Ausente equivale a true.

string

Rótulo do bot no painel (ex.: "Bot de orçamento").

A integração Typebot precisa do Ryze Bridge configurado no servidor. Se não estiver disponível, a criação da instância continua e o typebot retorna status: "error" com a causa. Configure o bot depois via POST /api/typebot/set/:instance.

Bloco settings (opcional)

boolean

Rejeita chamadas recebidas automaticamente.

string

Mensagem automática enviada ao chamador quando a chamada é rejeitada.

boolean

Não processa mensagens de grupo (útil para bots 1-a-1).

boolean

Mantém a instância marcada como “online” no WhatsApp.

boolean

Marca automaticamente mensagens recebidas como lidas.

boolean

padrão:"true"

Padrão true (histórico não é sincronizado na primeira conexão). Envie false se quiser receber o backlog.

boolean

Ignora mensagens do tipo “status” (stories).

Bloco S3 (opcional, armazenamento de mídias)

boolean

Ativa upload de mídias recebidas para S3 ou MinIO.

string

Região (ex.: us-east-1).

string

Nome do bucket.

string

Access Key ID.

string

Secret Access Key (encriptada at-rest, nunca retornada).

string

Endpoint custom para MinIO ou DigitalOcean Spaces. Omita para AWS S3 oficial.

string

Prefixo de path (ex.: media/).

Erros

HTTP	`error.message`	Quando
400	`Invalid request body`	JSON malformado
400	`The 'name' field is required`	`name` ausente ou em branco
401	`Invalid token`	TokenAccount inválido
403	`Account instance quota exceeded`	Cota de instâncias atingida
409	`Instance or token already exists`	Nome ou token já em uso
429	`Rate limit exceeded. Try again later.`	Mais de 20 criações por minuto
500	`Failed to create instance`	Erro interno

Exemplo de erro:

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

Conectar ao WhatsApp

Gere o QR code ou pairing code para vincular o número.

Verificar estado

Use GET /api/instance/list?instanceName=<nome> para conferir o status atual.

​Descrição

​Exemplos

​Mínimo

​Com Token personalizado

​Com configurações personalizadas

​Com Proxy

​Com Webhook

​Com Websocket

​Com S3

​Com Chatwoot

​Com Typebot

​Completo

​Resposta de sucesso

​Chatwoot com erro

​Typebot com erro

​Headers

​Request body

​Bloco proxy (opcional)

​Bloco webhook (opcional)

​Bloco WebSocket (opcional)

​Bloco Chatwoot (opcional)

​Bloco Typebot (opcional)

​Bloco settings (opcional)

​Bloco S3 (opcional, armazenamento de mídias)

​Erros

​Próximo

Conectar ao WhatsApp

Verificar estado

Descrição

Exemplos

Mínimo

Com Token personalizado

Com configurações personalizadas

Com Proxy

Com Webhook

Com Websocket

Com S3

Com Chatwoot

Com Typebot

Completo

Resposta de sucesso

Chatwoot com erro

Typebot com erro

Headers

Request body

Bloco proxy (opcional)

Bloco webhook (opcional)

Bloco WebSocket (opcional)

Bloco Chatwoot (opcional)

Bloco Typebot (opcional)

Bloco settings (opcional)

Bloco S3 (opcional, armazenamento de mídias)

Erros

Próximo