Nova instância

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

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

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

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

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

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

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

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

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

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"
    },
    "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 nunca é retornado pela API (mesmo nesta resposta). O s3.secretKey e o proxy.password também não.

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.

Headers

token

string

obrigatório

Seu TokenAccount.

Content-Type

string

obrigatório

application/json

Request body

name

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.

token

string

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

Bloco proxy (opcional)

proxyEnabled

boolean

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

proxyHost

string

IP ou hostname do proxy.

proxyPort

string

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

proxyProtocol

string

http, https ou socks5.

proxyUsername

string

Usuário do proxy (opcional).

proxyPassword

string

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

Bloco webhook (opcional)

webhookEnabled

boolean

Ativa o envio de eventos para uma URL.

webhookURL

string

URL para onde a RyzeAPI vai fazer POST dos eventos.

webhookAuthorization

string

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

webhookByEvents

boolean

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

webhookEvents

string[]

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

webhookMediaBase64

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)

websocketEnabled

boolean

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

websocketEvents

string[]

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

websocketMediaBase64

boolean

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

Bloco Chatwoot (opcional)

chatwootEnabled

boolean

Ativa a integração Chatwoot via RyzeIntegrations bridge.

chatwootBaseUrl

string

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

chatwootAccountId

integer

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

chatwootApiToken

string

API token da conta Chatwoot (access_token do agente). Obrigatório se chatwootEnabled=true. Encriptado at-rest e nunca retornado pela API.

chatwootInboxName

string

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

chatwootSignMessages

boolean

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

chatwootIgnoreGroups

boolean

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

chatwootStartAsPending

boolean

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

chatwootReopenResolved

boolean

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

A integração depende do RyzeIntegrations bridge estar configurado no servidor. Se o bridge não está disponível, a criação da instância continua e o chatwoot retorna enabled: false (a falha aparece nos logs do servidor). Veja chatwoot.md para detalhes.

Bloco settings (opcional)

autoRejectCalls

boolean

Rejeita chamadas recebidas automaticamente.

callRejectMessage

string

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

ignoreGroupMessages

boolean

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

keepOnlineStatus

boolean

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

autoReadMessages

boolean

Marca automaticamente mensagens recebidas como lidas.

disableHistorySync

boolean

padrão:"true"

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

ignoreStatus

boolean

Ignora mensagens do tipo “status” (stories).

Bloco S3 (opcional, armazenamento de mídias)

s3Enabled

boolean

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

s3Region

string

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

s3Bucket

string

Nome do bucket.

s3AccessKey

string

Access Key ID.

s3SecretKey

string

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

s3Endpoint

string

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

s3PathPrefix

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.

Introdução

Instância

Eventos

Mensagens

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Observabilidade

Nova instância

Descrição

Exemplos

Mínimo

Com Token personalizado

Com configurações personalizadas

Com Proxy

Com Webhook

Com Websocket

Com S3

Com Chatwoot

Completo

Resposta de sucesso

Chatwoot com erro

Headers

Request body

Bloco proxy (opcional)

Bloco webhook (opcional)

Bloco WebSocket (opcional)

Bloco Chatwoot (opcional)

Bloco settings (opcional)

Bloco S3 (opcional, armazenamento de mídias)

Erros

Próximo

Conectar ao WhatsApp

Verificar estado

Introdução

Instância

Eventos

Mensagens

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Observabilidade

Documentation Index

​Descrição

​Exemplos

​Mínimo

​Com Token personalizado

​Com configurações personalizadas

​Com Proxy

​Com Webhook

​Com Websocket

​Com S3

​Com Chatwoot

​Completo

​Resposta de sucesso

​Chatwoot com erro

​Headers

​Request body

​Bloco proxy (opcional)

​Bloco webhook (opcional)

​Bloco WebSocket (opcional)

​Bloco Chatwoot (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

Completo

Resposta de sucesso

Chatwoot com erro

Headers

Request body

Bloco proxy (opcional)

Bloco webhook (opcional)

Bloco WebSocket (opcional)

Bloco Chatwoot (opcional)

Bloco settings (opcional)

Bloco S3 (opcional, armazenamento de mídias)

Erros

Próximo