Início rápido

Este guia cobre o caminho mínimo para ter uma instância conectada e trocar sua primeira mensagem.

Pré-requisitos

Já possuir o TokenAccount da RyzeAPI.

Um celular com WhatsApp Business (ou o normal) instalado.

1. Defina seu token

export Token_Account="seu-account-token"

Em todos os exemplos, a Base URL é sempre https://ryzeapi.cloud.

2. Crie uma instância

Use o seu TokenAccount para provisionar uma nova instância de WhatsApp.

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

const res = await fetch(`https://ryzeapi.cloud/api/instance/new`, {
  method: "POST",
  headers: {
    "token": Token_Account,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "$Instance_Name" }),
});
const { data } = await res.json();
console.log(data.token); // este é o TokenInstance

import os, requests

r = requests.post(
    "https://ryzeapi.cloud/api/instance/new",
    headers={"token": os.environ["Token_Account"]},
    json={"name": "minhaInstancia"},
)
print(r.json()["data"]["token"])  # este é o TokenInstance

Resposta esperada:

{
  "success": true,
  "message": "Instance created successfully",
  "status": "created",
  "data": {
    "id": "01953abc-...",
    "name": "$Instance_Name",
    "token": "a1b2c3d4-...",
    "status": "disconnected",
    "createdAt": "2026-04-21T12:00:00Z"
  }
}

Guarde o data.token, este é o seu TokenInstance. A partir de agora, use ele (não o TokenAccount) para operar esta instância.

export Token_Instance="a1b2c3d4-..."

3. Conecte ao WhatsApp

Use seu TokenInstance daqui em diante.

Via QR code
Via pairing code

curl -X GET "https://ryzeapi.cloud/api/instance/connect/$Instance_Name" \
  -H "token: $Token_Instance"

A resposta traz:

data.qrCodes, strings que podem ser convertidas em QR
data.qrImages, PNGs em base64 prontos para exibir como imagem

Escaneie no seu celular em WhatsApp → Dispositivos vinculados → Vincular um dispositivo.

Ideal para ambientes sem câmera. Passe seu número no parâmetro number:

curl -X GET "https://ryzeapi.cloud/api/instance/connect/$Instance_Name?number=5511999999999" \
  -H "token: $Token_Instance"

A resposta traz um código de 8 caracteres para digitar em Dispositivos vinculados → Vincular com código.

4. Confirme que está conectado

curl -X GET "https://ryzeapi.cloud/api/instance/list?instanceName=$Instance_Name" \
  -H "token: $Token_Instance"

Aguarde o campo status da instância ficar igual a "connected".

5. Envie sua primeira mensagem

curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Olá do RyzeAPI 👋"
  }'

6. Configure um webhook (opcional)

Para receber eventos em tempo real (mensagens chegando, status de entrega, etc.):

curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "default",
    "enabled": true,
    "url": "https://seu-servidor.com/webhook",
    "events": ["message.exchange", "group.flow", "instance.state"],
    "mediaBase64": false
  }'

Cada instância aceita até 3 webhooks simultâneos (por exemplo: produção, staging e um de log). Veja Eventos para os 6 tipos disponíveis.

Próximos passos

Enviar mídia e recursos avançados

Imagens, vídeos, áudios, documentos, botões, carrosséis, listas e formulários.

Gerenciar contatos e etiquetas

Organize conversas, crie etiquetas, arquive, bloqueie e fixe chats.

Autenticação

Entenda TokenAccount vs TokenInstance em detalhe.

Tipos de erro

Como interpretar e tratar cada código HTTP.

Primeiros passos

Fundamentos

MCP

Início rápido

Pré-requisitos

1. Defina seu token

2. Crie uma instância

3. Conecte ao WhatsApp

4. Confirme que está conectado

5. Envie sua primeira mensagem

6. Configure um webhook (opcional)

Próximos passos

Enviar mídia e recursos avançados

Gerenciar contatos e etiquetas

Autenticação

Tipos de erro

​Pré-requisitos

​1. Defina seu token

​2. Crie uma instância

​3. Conecte ao WhatsApp

​4. Confirme que está conectado

​5. Envie sua primeira mensagem

​6. Configure um webhook (opcional)

​Próximos passos

Enviar mídia e recursos avançados

Gerenciar contatos e etiquetas

Autenticação

Tipos de erro

Pré-requisitos

1. Defina seu token

2. Crie uma instância

3. Conecte ao WhatsApp

4. Confirme que está conectado

5. Envie sua primeira mensagem

6. Configure um webhook (opcional)

Próximos passos