Nueva instancia

POST

api

instance

new

Nueva instancia

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: no

Descripción

Crea una nueva instancia de WhatsApp en tu cuenta. La instancia nace disconnected, el siguiente paso es llamar a GET /api/instance/connect/:instance para obtener el QR code o pairing code. Durante la creación, puedes enviar, en el mismo body, la configuración inicial de proxy, webhook, WebSocket, integración Chatwoot, integración Typebot, ajustes de comportamiento y almacenamiento S3. Cada bloque es independiente: envía solo lo que necesites.

La instancia se crea dentro de la cuota de tu cuenta. Si has alcanzado el límite, recibirás 403 con el mensaje Account instance quota exceeded, elimina una instancia que ya no uses para liberar espacio.

Las fallas en sub-bloques (webhook / websocket / chatwoot) no abortan la creación de la instancia. Cada bloque es log-and-continue: la instancia se crea, el sub-bloque aparece como enabled: false o ausente en la respuesta y los logs del servidor describen la causa. Para Chatwoot, la falla también se expone en chatwoot.status: "error" + chatwoot.error: "<message>" en el payload de retorno.

Ejemplos

Mínimo

Crea la instancia con solo el name. El TokenInstance es generado automáticamente por el servidor y devuelto en instance.token en la respuesta, guárdalo para autenticar las llamadas subsiguientes.

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

Con token personalizado

Define manualmente el TokenInstance en el campo token en lugar de dejar que el servidor genere uno. Útil para reutilizar un valor ya registrado en otro sistema, el token debe ser único dentro de tu cuenta.

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

Con settings personalizados

Crea la instancia con el bloque settings ya definido: rechaza llamadas automáticamente con un mensaje por defecto, mantiene presencia online, deshabilita la sincronización de historial e ignora estados. Equivale a llamar a POST /api/instance/settings/:instance justo después.

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

Con proxy

Aprovisiona la instancia apuntando a un proxy SOCKS5 autenticado. La contraseña se cifra at-rest con AES-256-GCM y nunca se devuelve en la respuesta.

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

Con webhook

En la misma solicitud, configura el webhook default para recibir solo los eventos message.exchange y call.update, con Authorization personalizado para validar el origen. La media no se envía en base64, el destino la obtiene vía la URL devuelta.

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

Con WebSocket

Habilita el broadcast en tiempo real vía WebSocket filtrando por los eventos message.exchange y call.update. Útil para dashboards y bots que necesitan latencia mínima sin exponer un endpoint público de webhook.

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

Con S3

Apunta el almacenamiento de media a un bucket AWS S3 (us-east-1), con prefijo media/ para organizar las subidas. La s3SecretKey se cifra at-rest y nunca aparece en la respuesta.

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

Con Chatwoot

Aprovisiona la instancia ya vinculada a una inbox de Chatwoot (WhatsApp - Orion), con firma de agente activa y reapertura automática de conversaciones resueltas. Si la activación de Chatwoot falla, la instancia se crea de todos modos y el objeto chatwoot regresa con 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)
}

Con Typebot

Aprovisiona la instancia ya con un bot de Typebot registrado. Este bloque configura un único bot; agrega más después vía POST /api/typebot/set/:instance. Si la activación falla (bridge no disponible o campos inválidos), la instancia se crea de todos modos y el objeto typebot regresa con 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 los bloques en la misma solicitud: token personalizado, proxy SOCKS5, webhook, WebSocket, integración Chatwoot, ajustes de comportamiento y almacenamiento S3. Cada bloque permanece independiente, las fallas en sub-bloques no abortan la creación de la instancia.

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

Respuesta exitosa

La respuesta incluye el TokenInstance generado y el resumen de cada integración configurada (proxy, webhook, websocket, chatwoot, settings, s3). Guarda el instance.token, es lo que autentica las llamadas subsiguientes de la propia instancia.

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

El chatwootApiToken no es devuelto en esta respuesta (solo se expone en plaintext en GET /api/chatwoot/list/:instance). El s3.secretKey y la proxy.password nunca son devueltos por ningún endpoint.

Chatwoot con error

Si el bloque chatwoot* fue enviado pero la configuración falló (p. ej., token inválido), la instancia se crea de todos modos y el objeto chatwoot en la respuesta viene con status: "error" y un error accionable:

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

Puedes corregir las credenciales vía POST /api/chatwoot/set/:instance sin recrear la instancia.

Typebot con error

Si el bloque typebot* fue enviado pero la configuración falló (p. ej., bridge no configurado en el servidor, typebotUrl ausente o typebotTriggerType inválido), la instancia se crea de todos modos y el objeto typebot en la respuesta viene con status: "error" y un error accionable:

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

Puedes configurar el bot después vía POST /api/typebot/set/:instance sin recrear la instancia.

Cabeceras

string

requerido

Tu TokenAccount.

string

requerido

application/json

Cuerpo de la solicitud

string

requerido

Identificador de la instancia (usado en las rutas :instance de todos los demás endpoints). No puede estar en blanco y debe ser único dentro de tu cuenta. Se recomienda kebab-case o snake_case.

string

Token personalizado para la instancia. Si se omite, se genera automáticamente (recomendado).

Bloque proxy (opcional)

boolean

Habilita el uso de un proxy específico para esta instancia.

string

IP o hostname del proxy.

string

Puerto como string (p. ej., "8080").

string

http, https o socks5.

string

Usuario del proxy (opcional).

string

Contraseña del proxy (opcional, cifrada at-rest con AES-256-GCM).

Bloque webhook (opcional)

boolean

Habilita el envío de eventos a una URL.

string

URL donde RyzeAPI hará POST de los eventos.

string

Valor que RyzeAPI envía en la cabecera Authorization de cada POST (útil para validar origen). Ej.: Bearer secret-key-123.

boolean

Si es true, cada tipo de evento puede tener su propia URL (default: false).

string[]

Lista de eventos que la instancia debe despachar. Ej.: ["message.exchange", "call.update"].

boolean

Incluye media recibida como base64 dentro del body del webhook.

El bloque webhook crea un webhook con label default. Para múltiples webhooks por instancia, usa POST /api/events/webhook después.

Bloque WebSocket (opcional)

boolean

Habilita el broadcasting de eventos vía WebSocket para esta instancia.

string[]

Lista de eventos que serán emitidos vía WebSocket. Si está vacío con websocketEnabled=true, todos los eventos son emitidos.

boolean

Incluye media recibida como base64 en los frames del WebSocket.

Bloque Chatwoot (opcional)

boolean

Habilita la integración con Chatwoot.

string

URL de la instalación de Chatwoot (p. ej., https://chatwoot.example.com). Requerido si chatwootEnabled=true.

integer

ID numérico de la cuenta de Chatwoot. Requerido si chatwootEnabled=true.

string

Token de API de la cuenta de Chatwoot (el access_token del agente). Requerido si chatwootEnabled=true. Cifrado at-rest. No se devuelve en esta respuesta, pero se expone en plaintext en GET /api/chatwoot/list/:instance.

string

Nombre del inbox que se creará en Chatwoot (p. ej., "WhatsApp - Orion").

boolean

Si es true, los mensajes enviados a través de la API se prefijan con la firma del agente de Chatwoot.

boolean

Si es true, los mensajes de grupo no se convierten en conversaciones en Chatwoot.

boolean

Si es true, las nuevas conversaciones inician como pending en lugar de open.

boolean

Si es true, los nuevos mensajes en conversaciones resueltas las reabren automáticamente.

La integración Chatwoot necesita estar habilitada en el servidor. Si no está disponible, la creación de la instancia continúa y chatwoot regresa con enabled: false (la falla aparece en los logs del servidor). Consulta el resumen de Chatwoot para detalles.

Bloque Typebot (opcional)

Configura un único bot de Typebot junto con la creación de la instancia. Para varios bots, usa POST /api/typebot/set/:instance después. Consulta el resumen de Typebot para el enrutamiento por trigger.

boolean

Habilita la integración con Typebot.

string

URL del Typebot publicado (viewer). Requerido si typebotEnabled=true. Ej.: https://typebot.co/meu-bot-abc123.

string

Cómo se acciona el bot: all (cualquier mensaje) o keyword. Requerido si typebotEnabled=true.

string

Operador del trigger, requerido si typebotTriggerType es keyword. Uno de: contains, equals, startsWith, endsWith, regex.

string

Palabra/expresión del trigger, requerida si typebotTriggerType es keyword.

integer

predeterminado:"0"

Expira la sesión por inactividad tras N minutos (0 = nunca).

string

Mensaje enviado al usuario cuando la sesión expira.

string

Palabra que finaliza el bot de inmediato (p. ej., "sair").

string

Despedida enviada cuando el bot se finaliza por la typebotKeywordFinish.

integer

predeterminado:"0"

Delay del indicador “escribiendo…” antes de cada respuesta, en milisegundos.

boolean

predeterminado:"false"

Si es true, pausa el bot en esa conversación cuando el operador responde manualmente.

integer

predeterminado:"0"

Agrupa los fragmentos enviados por el cliente durante N segundos antes de procesar.

boolean

predeterminado:"true"

Si es true, los mensajes de grupo no accionan el bot. Ausente equivale a true.

string

Etiqueta del bot en el panel (p. ej., "Bot de orçamento").

La integración Typebot necesita el Ryze Bridge configurado en el servidor. Si no está disponible, la creación de la instancia continúa y typebot regresa con status: "error" con la causa. Configura el bot después vía POST /api/typebot/set/:instance.

Bloque settings (opcional)

boolean

Rechaza automáticamente las llamadas entrantes.

string

Mensaje automático enviado al llamante cuando la llamada es rechazada.

boolean

No procesa mensajes de grupo (útil para bots 1-a-1).

boolean

Mantiene la instancia marcada como “online” en WhatsApp.

boolean

Marca automáticamente los mensajes recibidos como leídos.

boolean

predeterminado:"true"

Default true (el historial no se sincroniza en la primera conexión). Envía false si quieres recibir el backlog.

boolean

Ignora mensajes de tipo “status” (stories).

Bloque S3 (opcional, almacenamiento de media)

boolean

Habilita el upload de media recibida a S3 o MinIO.

string

Región (p. ej., us-east-1).

string

Nombre del bucket.

string

Access Key ID.

string

Secret Access Key (cifrado at-rest, nunca devuelto).

string

Endpoint personalizado para MinIO o DigitalOcean Spaces. Omite para AWS S3 oficial.

string

Prefijo de path (p. ej., media/).

Errores

HTTP	`error.message`	Cuándo
400	`Invalid request body`	JSON malformado
400	`The 'name' field is required`	`name` faltante o en blanco
401	`Invalid token`	TokenAccount inválido
403	`Account instance quota exceeded`	Cuota de instancias alcanzada
409	`Instance or token already exists`	Nombre o token ya en uso
429	`Rate limit exceeded. Try again later.`	Más de 20 creaciones por minuto
500	`Failed to create instance`	Error interno

Ejemplo de error:

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

Conectar a WhatsApp

Genera el QR code o pairing code para vincular el número.

Verificar estado

Usa GET /api/instance/list?instanceName=<name> para inspeccionar el status actual.

​Descripción

​Ejemplos

​Mínimo

​Con token personalizado

​Con settings personalizados

​Con proxy

​Con webhook

​Con WebSocket

​Con S3

​Con Chatwoot

​Con Typebot

​Completo

​Respuesta exitosa

​Chatwoot con error

​Typebot con error

​Cabeceras

​Cuerpo de la solicitud

​Bloque proxy (opcional)

​Bloque webhook (opcional)

​Bloque WebSocket (opcional)

​Bloque Chatwoot (opcional)

​Bloque Typebot (opcional)

​Bloque settings (opcional)

​Bloque S3 (opcional, almacenamiento de media)

​Errores

​Siguiente

Conectar a WhatsApp

Verificar estado

Descripción

Ejemplos

Mínimo

Con token personalizado

Con settings personalizados

Con proxy

Con webhook

Con WebSocket

Con S3

Con Chatwoot

Con Typebot

Completo

Respuesta exitosa

Chatwoot con error

Typebot con error

Cabeceras

Cuerpo de la solicitud

Bloque proxy (opcional)

Bloque webhook (opcional)

Bloque WebSocket (opcional)

Bloque Chatwoot (opcional)

Bloque Typebot (opcional)

Bloque settings (opcional)

Bloque S3 (opcional, almacenamiento de media)

Errores

Siguiente