Permissões (escopos)
Cada chave tem uma lista de permissões. account:read (quem sou eu, caixas de entrada, times, agentes, etiquetas) é
implícita. Não existe permissão "acesso total".
| Escopo | Permite | Observações |
|---|---|---|
contacts:read |
Listar e ler contatos, empresas e notas de contato | E-mail, telefone e identificador mascarados |
contacts:pii |
Ver dados pessoais sem máscara (também dentro das mensagens) | Para assistentes de IA, prefira deixar desligado |
contacts:write |
Criar e alterar contatos, notas e etiquetas | Nunca apaga contatos |
conversations:read |
Dados das conversas: status, caixa, responsável, time, etiquetas, espera | Sem texto das mensagens |
messages:read |
Texto das mensagens das conversas que a chave pode ver | Notas privadas só quando pedidas |
conversations:write |
Status, responsável, time, prioridade, etiquetas, notas privadas | Nunca fala com o cliente |
messages:send |
Enviar mensagem ao cliente numa conversa existente | Por padrão exige aprovação de uma pessoa |
crm:read |
Funis, negócios, tarefas, histórico, funil de vendas | Plano Business |
crm:write |
Criar, alterar, mover, ganhar, perder, reabrir negócios; tarefas | Plano Business |
knowledge:read |
Busca no conhecimento dos assistentes, FAQs aprovadas | |
knowledge:write |
Sugerir FAQs (ficam pendentes de revisão) | |
reports:read |
Relatórios do período e carga por agente | Só administradores |
webhooks:manage |
Criar, listar, alterar e remover webhooks da conta | Só administradores |
Regras
- As permissões são conferidas em toda requisição: se o plano mudar ou o papel da pessoa de uma chave pessoal diminuir, a chave perde o acesso na hora, sem edição.
- Sem a permissão da rota:
403 insufficient_scopecomrequired_scopes. No MCP, a ferramenta nem aparece emtools/list. - Chaves pessoais nunca podem mais do que a pessoa: um agente só vê as conversas das suas caixas e times.
- A restrição por caixas de entrada (opcional) limita conversas, mensagens, fila e envios; contatos continuam valendo para a conta toda.
Modelos
| Modelo | Tipo | Permissões |
|---|---|---|
| Assistente de IA (somente leitura) | pessoal | contacts:read, conversations:read, messages:read, crm:read, knowledge:read, reports:read |
| Assistente de IA (leitura e ações) | pessoal | o acima + escritas e messages:send com aprovação |
| ERP / sistema de gestão | serviço | contacts:read, contacts:pii, contacts:write, crm:read, crm:write, webhooks:manage |
| Automação (n8n, Make, Zapier) | serviço | contacts:read, contacts:write, conversations:read, conversations:write, webhooks:manage |