Conceitos

Entender estes conceitos centrais evita horas de debug. Leia antes de abrir qualquer módulo.

Conta (Account)

A sua conta na RyzeAPI é o que agrupa todas as suas instâncias de WhatsApp. Ela tem:

Um TokenAccount único (sua credencial principal)
Um limite de instâncias que você pode criar
Acesso a todas as instâncias dela

Pense nela como sua “área de cliente”: dentro dela ficam suas instâncias, cada uma representando um número de WhatsApp conectado.

Instância

Uma instância é uma conexão ativa com um número de WhatsApp. Cada instância tem:

Nome único na sua conta (ex.: minhaInstancia, suporte, atendimento)
Token próprio (TokenInstance) gerado automaticamente quando você cria a instância
Sessão persistente, depois de conectar ao WhatsApp, ela se mantém ligada mesmo após reiniciar
Configurações individuais (webhook, proxy, etc.)

O nome da instância aparece em toda URL com :instance no path. Exemplo: POST /api/message/text/minhaInstancia opera na instância chamada minhaInstancia.

Tokens: Account vs Instance

TokenAccount

Entregue quando sua conta foi criada. Usado para administrar sua conta. Casos de uso: criar, listar ou deletar instâncias.

TokenInstance

Gerado pela API ao criar uma instância. Usado nas operações do dia a dia. Casos de uso: enviar mensagem, criar grupo, configurar webhook, etc.

Veja Autenticação para detalhes sobre quando usar cada um.

JID (Jabber ID)

Todo contato, grupo ou canal no WhatsApp tem um JID, um identificador único no estilo email. A API aceita e retorna JIDs em todos os endpoints que referenciam destinatários.

Tipo	Formato	Exemplo
Usuário	`<número>@s.whatsapp.net`	`5511999999999@s.whatsapp.net`
Grupo	`<id>@g.us`	`120363024567890123@g.us`
Canal (newsletter)	`<id>@newsletter`	`123456789@newsletter`

Em endpoints de envio para contatos, você pode passar só o número (ex.: 5511999999999) no campo number, a API monta o JID completo automaticamente. Para grupos, passe sempre o JID completo (o que termina em @g.us).

Webhook vs WebSocket

A RyzeAPI oferece dois canais complementares para receber eventos em tempo real (novas mensagens, status de entrega, mudanças de grupo, etc.). Você pode usar os dois ao mesmo tempo.

Webhook (HTTP push)

Quando um evento acontece na sua instância, a RyzeAPI faz uma requisição POST para a URL que você configurou.Ideal para: integrações servidor-a-servidor, CRMs, automações, bots.Características:

A RyzeAPI tenta novamente se seu endpoint estiver fora do ar (retry com backoff)
Você pode configurar até 3 webhooks simultâneos por instância (produção, staging, logging)
Pode incluir a mídia em base64 no corpo do webhook, ou apenas a URL

WebSocket (conexão persistente)

Seu cliente mantém uma conexão aberta com a RyzeAPI e recebe os eventos em tempo real pelo mesmo canal.Ideal para: dashboards ao vivo, aplicações browser, qualquer interface onde você quer ver as mensagens chegarem sem polling.Características:

Reconexão automática recomendada do lado do cliente
Mesmo shape de evento que o webhook
Autenticado via query string (?token=) quando em browser

Os 6 tipos de evento

Evento	Quando acontece
`message.exchange`	Mensagem enviada ou recebida
`message.status`	Mudança de status (enviada → entregue → lida)
`group.flow`	Criação, saída ou alteração em grupo
`instance.state`	Conectou, desconectou, QR novo, logout
`call.update`	Chamada recebida, rejeitada, aceita
`label.update`	Etiqueta criada, renomeada, atribuída

Formato das respostas

A API usa dois formatos de envelope, que podem variar entre os endpoints. Ambos começam com o campo success que indica se a operação deu certo.

Sucesso
Erro

{
  "success": true,
  "message": "Text message sent successfully",
  "status": "sent",
  "data": { "...": "..." }
}

Campos importantes:

success: sempre presente
message: descrição humana do resultado
status: código estável de negócio (ex.: sent, connected, qr_ready). É o melhor campo para tratar respostas programaticamente
data: payload útil (varia por endpoint)

{
  "success": false,
  "error": {
    "message": "Instance is not connected to WhatsApp"
  }
}

Ordem de prioridade para tratamento:

O código HTTP (401, 403, 429, etc.), fonte de verdade
O texto de error.message, quando precisar diferenciar dois erros do mesmo HTTP

Veja Tipos de erro para o catálogo completo de mensagens literais.

Glossário rápido

Termo	Significado
Conta	Sua área principal na RyzeAPI. Agrupa todas as suas instâncias, com uma cota de quantas você pode criar.
Instância	Conexão ativa com um número de WhatsApp, gerenciada pela API.
TokenAccount	Seu token principal, usado para criar/listar/deletar instâncias.
TokenInstance	Token da instância específica, usado nas operações do dia a dia.
JID	Identificador único no WhatsApp (contato, grupo ou canal) no formato email.
Webhook	Requisição `POST` que a RyzeAPI faz para a sua URL quando um evento acontece.
WebSocket	Conexão persistente que entrega eventos em tempo real para um cliente.
Pairing code	Código de 8 caracteres para conectar uma instância sem precisar escanear QR.

Variáveis usadas em exemplos

A Base URL é sempre https://ryzeapi.cloud. Os exemplos usam estas variáveis:

Variável	Significado
`$Token_Account`	Seu token de conta
`$Token_Instance`	Token de uma instância específica
`$Instance_Name`	Nome da instância (ex.: `minhaInstancia`)

Primeiros passos

Fundamentos

MCP

Conta (Account)

Instância

Tokens: Account vs Instance

TokenAccount

TokenInstance

JID (Jabber ID)

Webhook vs WebSocket

Os 6 tipos de evento

Formato das respostas

Glossário rápido

Variáveis usadas em exemplos

​Conta (Account)

​Instância

​Tokens: Account vs Instance

TokenAccount

TokenInstance

​JID (Jabber ID)

​Webhook vs WebSocket

​Os 6 tipos de evento

​Formato das respostas

​Glossário rápido

​Variáveis usadas em exemplos

Conta (Account)

Instância

Tokens: Account vs Instance

JID (Jabber ID)

Webhook vs WebSocket

Os 6 tipos de evento

Formato das respostas

Glossário rápido

Variáveis usadas em exemplos