Primeiros passos
Escopos
O que cada permissão libera, e quais rotas uma chave nunca alcança.
Cada chave tem uma lista de escopos. Uma requisição a uma rota cujo escopo a chave não tem é recusada com 403 MISSING_SCOPE, e a resposta diz qual escopo faltou.
| Escopo | Libera |
|---|---|
chats:read | Listar conversas, contatos, mensagens, etiquetas e mídia. |
chats:write | Resolver, atribuir e anotar conversas; colocar ou tirar etiqueta de uma conversa; atualizar um contato. |
messages:send | Enviar e editar mensagens, iniciar conversas, subir mídia. |
tags:write | Criar, renomear e apagar etiquetas. |
groups:read | Dados de grupo e link de convite. |
groups:write | Criar grupos, gerenciar participantes, convidar pessoas, editar nome, descrição e foto. |
Uma chave criada sem escolher escopos é somente leitura: chats:read e groups:read. O poder de enviar precisa ser concedido explicitamente.
Rotas abertas a qualquer chave
GET /health, GET /integrations e o endpoint MCP não pedem escopo específico. Dentro do MCP, cada chamada de tool é conferida contra o escopo da rota que ela usa.
O que uma chave nunca faz
Conectar ou desconectar número, ler QR code, sincronizar histórico, cobrança e configurações da conta são exclusivos do dashboard. Qualquer rota que não está nesta referência responde 403 ROUTE_NOT_PUBLIC, mesmo para uma chave com todos os escopos.