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.

A RyzeAPI usa dois tipos de token para autenticar cada requisição. Todos são enviados no header token. Entenda quando usar cada um e como tratar os erros mais comuns.

​
Dois tipos de token

TokenAccount

É o seu token principal. Com ele você cria e administra suas instâncias de WhatsApp.Escopo: sua conta inteira, todas as instâncias que ela possui.Quando usar: criar uma instância, listar todas as suas instâncias, deletar uma instância, ou qualquer operação em que você precise agir como “dono da conta”.

TokenInstance

Gerado automaticamente quando você cria uma instância nova. Cada instância tem o seu.Escopo: apenas aquela instância específica.Quando usar: operações do dia a dia, enviar mensagem, criar grupo, configurar webhook, ler contatos, etc. É o token que você vai usar em 99% das chamadas.
Como regra prática: use o TokenInstance sempre que o endpoint tem :instance no path. Use o TokenAccount apenas para criar/listar/deletar instâncias.

​
Ciclo de vida dos tokens

1

Você recebe seu TokenAccount

É entregue quando sua conta é criada. Guarde em local seguro, ele não pode ser recuperado depois.
2

Crie uma instância

Chame POST /api/instance/new enviando seu TokenAccount. A resposta traz o campo data.token, que é o TokenInstance daquela instância.
3

Use o TokenInstance no dia a dia

A partir daí, toda operação sobre aquela instância (mandar mensagem, ler contatos, configurar webhook) usa o TokenInstance.
4

Precisa criar outra instância?

Volte a usar seu TokenAccount para provisionar mais uma.

​
Três formas de enviar o token

Recomendamos sempre usar o header token. As outras formas existem apenas para casos específicos.

​
Header token (padrão recomendado)

POST /api/message/text/$Instance_Name HTTP/1.1
Host: ryzeapi.cloud
Content-Type: application/json
token: seu-token-aqui

{"number": "5511999999999", "message": "Olá!"}

​
Header Authorization: Bearer (compatibilidade)

Caso sua ferramenta só permita o padrão Bearer. 
Authorization: Bearer seu-token-aqui

​
Query string ?token= (apenas WebSocket em navegador)

Usado quando não é possível enviar headers, o caso típico é WebSocket em JavaScript do browser, já que new WebSocket(...) não aceita headers customizados. 
const ws = new WebSocket(
  `wss://ryzeapi.cloud/ws/$Instance_Name?token=${instanceToken}`
);
Query strings aparecem em logs de proxy e CDN. Não use em produção fora do caso WebSocket/browser.

​
Quem pode fazer o quê

  • Qualquer endpoint :instance da própria instância: enviar mensagem, ler contatos, configurar webhook, criar grupo, etc.
  • Inspecionar o estado atual da própria instância (GET /api/instance/list)
  • Abrir conexão WebSocket para receber eventos em tempo real
  • TokenInstance não cria instâncias novas, use TokenAccount para isso
  • TokenInstance de uma instância não opera outra instância, cada token só vale para a sua própria
  • TokenAccount/TokenInstance de uma conta não operam instâncias de outra conta

​
Proteção de acesso (ownership)

A RyzeAPI verifica automaticamente, antes de cada operação, se o token enviado tem permissão para aquele recurso específico. Isso impede que um token vaze acesso a instâncias de terceiros. Exemplos do que é bloqueado automaticamente:
  • Tentar enviar mensagem na instância B usando o token da instância A → 403
  • Tentar deletar uma instância que pertence a outra conta → 403
  • TokenAccount tentando criar mais instâncias do que sua cota permite → 403

​
Erros de autenticação

Todas respostas de erro de auth vêm com HTTP 401 (token inválido) ou 403 (sem permissão) e seguem o formato: 
{
  "success": false,
  "error": {
    "message": "descrição legível do problema"
  }
}

​
Mensagens que você pode encontrar

HTTPMensagemCausa mais provável
401Missing token in headerVocê não enviou o header token
401Missing token in header, Authorization header, or query parameterNenhuma das 3 formas de token foi usada
401Invalid tokenToken não existe, está errado, ou foi revogado
401Invalid instance tokenO token não corresponde à instância no path
403Instance token does not match requested instanceEstá usando o TokenInstance de A no path :instance=B
403Instance does not belong to your accountTokenAccount tentando operar instância de outra conta
403Account instance quota exceededAtingiu o limite de instâncias da sua conta
Se receber Invalid token sem saber por quê, verifique: (1) se o token está completo e sem espaços; (2) se está usando o tipo certo de token para aquele endpoint; (3) se a instância existe e está ativa.

​
Segurança: boas práticas

Trate todo token como credencial, armazene em variáveis de ambiente ou cofre de segredos, nunca no frontend ou em repositórios públicos.
Use um TokenInstance por instância, se um vazar, você revoga só aquele.
Use HTTPS em produção, a RyzeAPI aceita apenas conexões seguras.
Use o header token (não a query string) na maioria dos casos, headers não vão parar em logs de proxy.
Monitore o header X-RateLimit-Remaining para evitar ser bloqueado por excesso de requisições.

​
Próximo

Tipos de erro

Os formatos de resposta e como interpretar cada código HTTP.

Rate limit

Quanto você pode chamar por minuto e como reagir ao 429.