Funções Personalizadas

Funções Personalizadas (custom roles) permitem definir níveis de acesso granulares que vão além das funções base (agent e administrator). Cada função é um conjunto nomeado de permissões que você atribui a um agente pelo campo custom_role_id no endpoint de agentes.

Autenticação: todas as operações deste recurso exigem um token de um usuário administrador da conta. Agentes com função personalizada não gerenciam funções. Tudo é escopado à conta da URL — IDs de outra conta retornam 404.

Catálogo de permissões

O campo permissions aceita qualquer combinação dos valores abaixo. Valores fora deste catálogo são rejeitados com 422.

Permissão	O que libera
conversation_manage	Gerenciar todas as conversas da conta
conversation_unassigned_manage	Gerenciar conversas não atribuídas e as próprias
conversation_participating_manage	Gerenciar apenas conversas próprias / em que participa
contact_manage	CRUD de contatos
report_manage	Acesso aos relatórios
knowledge_base_manage	Gerenciar portais e artigos da central de ajuda
pipeline_manage	Pipeline Pro: CRUD completo e automações
pipeline_view	Pipeline Pro: somente leitura
follow_up_manage	Follow Up: templates e automações
appointment_manage	Atendimentos: ações privilegiadas
commercial_analysis_manage	Análise Comercial: gerenciar

GET/api/v1/accounts/{account_id}/custom_roles

Lista todas as funções personalizadas da conta (mais recentes primeiro).

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/custom_roles" \
  -H "api_access_token: YOUR_ADMIN_TOKEN" | jq .

200Lista de funções personalizadas

json

[
  {
    "id": 5,
    "name": "Atendente",
    "description": "Acesso limitado as conversas",
    "permissions": ["conversation_participating_manage"],
    "created_at": 1718640000,
    "updated_at": 1718640000
  }
]

POST/api/v1/accounts/{account_id}/custom_roles

Cria uma nova função personalizada.

Body (envolto em objeto custom_role)

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Sim	Nome da função
`description`	`string`	Nao	Descrição livre
`permissions`	`string[]`	Nao	Lista de permissões do catálogo acima

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/custom_roles" \
  -H "api_access_token: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_role": {
      "name": "Atendente",
      "description": "Acesso limitado as conversas",
      "permissions": ["conversation_participating_manage"]
    }
  }'

200Função criada

json

{
  "id": 5,
  "name": "Atendente",
  "description": "Acesso limitado as conversas",
  "permissions": ["conversation_participating_manage"],
  "created_at": 1718640000,
  "updated_at": 1718640000
}

GET/api/v1/accounts/{account_id}/custom_roles/{id}

Obtém uma função personalizada pelo ID.

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/custom_roles/5" \
  -H "api_access_token: YOUR_ADMIN_TOKEN" | jq .

PATCH/api/v1/accounts/{account_id}/custom_roles/{id}

Atualiza nome, descrição ou permissões de uma função.

Body (envolto em objeto custom_role)

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Nao	Nome
`description`	`string`	Nao	Descrição
`permissions`	`string[]`	Nao	Substitui a lista de permissões

bash

curl -X PATCH "https://chat.seudominio.com/api/v1/accounts/1/custom_roles/5" \
  -H "api_access_token: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "custom_role": { "permissions": ["conversation_manage", "contact_manage"] } }'

DELETE/api/v1/accounts/{account_id}/custom_roles/{id}

Remove uma função. Agentes que a possuíam voltam ao comportamento base (custom_role_id volta a null).

bash

curl -X DELETE "https://chat.seudominio.com/api/v1/accounts/1/custom_roles/5" \
  -H "api_access_token: YOUR_ADMIN_TOKEN"

200Função removida com sucesso