Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

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.
TipoFormatoExemplo
Usuário<número>@s.whatsapp.net5511999999999@s.whatsapp.net
Grupo<id>@g.us120363024567890123@g.us
Canal (newsletter)<id>@newsletter123456789@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.
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
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

EventoQuando acontece
message.exchangeMensagem enviada ou recebida
message.statusMudança de status (enviada → entregue → lida)
group.flowCriação, saída ou alteração em grupo
instance.stateConectou, desconectou, QR novo, logout
call.updateChamada recebida, rejeitada, aceita
label.updateEtiqueta 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. 
{
  "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)
Veja Tipos de erro para o catálogo completo de mensagens literais.

​
Glossário rápido

TermoSignificado
ContaSua área principal na RyzeAPI. Agrupa todas as suas instâncias, com uma cota de quantas você pode criar.
InstânciaConexão ativa com um número de WhatsApp, gerenciada pela API.
TokenAccountSeu token principal, usado para criar/listar/deletar instâncias.
TokenInstanceToken da instância específica, usado nas operações do dia a dia.
JIDIdentificador único no WhatsApp (contato, grupo ou canal) no formato email.
WebhookRequisição POST que a RyzeAPI faz para a sua URL quando um evento acontece.
WebSocketConexão persistente que entrega eventos em tempo real para um cliente.
Pairing codeCó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ávelSignificado
$Token_AccountSeu token de conta
$Token_InstanceToken de uma instância específica
$Instance_NameNome da instância (ex.: minhaInstancia)