Skip to main content
A permissão de um token é uma matriz de módulo × método. Cada rota da API pertence a um módulo, e o método é o verbo HTTP da requisição. Para uma chamada funcionar, o token precisa ter aquele método liberado naquele módulo.
Esse token pode ler e criar contatos e ler atendimentos, e nada mais. PUT /contacts/{id} responde 403, assim como qualquer chamada a produtos, campanhas ou CRM.
A permissão é a última verificação feita. Antes dela, a API confere se o token é válido, se a empresa está ativa, se o plano inclui a API e se o limite de requisições não foi atingido. Por isso, um 403 de escopo sempre significa que o token era válido e a chamada chegou ao endpoint certo.

​
Os módulos

contacts

Contatos, campos extras e origem de marketing.

tickets

Abertura, transferência, encerramento e qualificação.

messages

Envio assíncrono e leitura de mensagens.

channels

Canais e templates. Somente leitura.

webchat

Sessões e mensagens de visitantes do webchat.

tags

Tags e vínculo com atendimentos.

queues

Filas de atendimento e seus atendentes.

wrapups

Tipos de qualificação.

users

Atendentes, administradores e convites.

profiles

Perfis de permissões. Somente leitura.

schedules

Mensagens programadas.

quick-messages

Respostas rápidas.

campaigns

Disparos em massa e sua execução.

crm

Painéis, etapas, cards e indicadores.

products

Catálogo, categorias e desempenho.

custom-fields

Campos personalizados e variáveis globais.

reports

Relatórios e dashboards.
Os métodos são GET, POST, PUT e DELETE. Nenhuma rota da v1 usa PATCH, por isso ele não aparece na lista. O módulo profiles aceita apenas GET. Ele existe para você descobrir o profileId usado ao convidar ou editar um usuário; perfis são criados e editados no painel. O módulo webchat aceita GET e POST: com ele, o seu sistema abre a sessão de um visitante, envia as mensagens dele e lê as respostas. O webchat é configurado no painel.

​
Escolhendo o escopo

Dê ao token apenas as permissões que a integração precisa para funcionar. Alguns exemplos comuns:
Somente leitura. Mesmo que vaze, um token assim não consegue alterar nenhum dado, então é uma boa opção para ferramentas de terceiros.
Basta para enviar mensagens e descobrir o channelId do canal de saída. Não é preciso incluir contacts nem tickets, porque o envio já cria o contato e o atendimento quando necessário.
Esse escopo não inclui DELETE. Se a sincronização tiver um erro e apagar contatos, o prejuízo é difícil de desfazer. Se a integração precisar excluir contatos, use um segundo token, em uma rotina separada.
Move cards e registra anotações. Lê contatos e o catálogo sem poder alterá-los.
Permissão de escrita em users dá poder de administrador. Com users: ["POST"], o token convida pessoas para a empresa. Com users: ["PUT"], ele altera o perfil de quem já faz parte dela e pode até promover alguém a administrador. Conceda essas duas permissões apenas a integrações de RH ou de provisionamento que realmente precisem delas.

​
Quando falta permissão

A mensagem informa o método e o módulo que faltaram. Para corrigir, abra o token no painel e marque essa combinação.
A lista de módulos acima é a mesma que aparece no painel ao criar um token. Se o painel mostrar um módulo que não está aqui, considere o painel como a referência correta.

​
O que o token nunca faz

Independentemente das permissões marcadas:
  • Não gerencia tokens. Criar, editar, rotacionar e revogar tokens exige uma sessão de administrador no painel.
  • Não troca de empresa. A empresa é sempre a do próprio token. Um companyId enviado no corpo é ignorado.
  • Não enxerga o super admin. O vínculo de suporte da plataforma não aparece em GET /users e não pode ser alterado pela API.