Funcoes Personalizadas

Funcoes Personalizadas (custom roles) permitem definir niveis de acesso granulares que vao alem das funcoes base (agent e administrator). Cada funcao e um conjunto nomeado de permissoes que voce atribui a um agente pelo campo custom_role_id no endpoint de agentes.

Autenticacao: todas as operacoes deste recurso exigem um token de um usuario administrador da conta. Agentes com funcao personalizada nao gerenciam funcoes. Tudo e escopado a conta da URL — IDs de outra conta retornam 404.

Catalogo de permissoes

O campo permissions aceita qualquer combinacao dos valores abaixo. Valores fora deste catalogo sao rejeitados com 422.

Permissao	O que libera
conversation_manage	Gerenciar todas as conversas da conta
conversation_unassigned_manage	Gerenciar conversas nao atribuidas e as proprias
conversation_participating_manage	Gerenciar apenas conversas proprias / em que participa
contact_manage	CRUD de contatos
report_manage	Acesso aos relatorios
knowledge_base_manage	Gerenciar portais e artigos da central de ajuda
pipeline_manage	Pipeline Pro: CRUD completo e automacoes
pipeline_view	Pipeline Pro: somente leitura
follow_up_manage	Follow Up: templates e automacoes
appointment_manage	Atendimentos: acoes privilegiadas
commercial_analysis_manage	Analise Comercial: gerenciar

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

Lista todas as funcoes personalizadas da conta (mais recentes primeiro).

Parametros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numerico 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 funcoes 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 funcao personalizada.

Body (envolto em objeto custom_role)

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Sim	Nome da funcao
`description`	`string`	Nao	Descricao livre
`permissions`	`string[]`	Nao	Lista de permissoes do catalogo 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"]
    }
  }'

200Funcao 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}

Obtem uma funcao 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, descricao ou permissoes de uma funcao.

Body (envolto em objeto custom_role)

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Nao	Nome
`description`	`string`	Nao	Descricao
`permissions`	`string[]`	Nao	Substitui a lista de permissoes

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 funcao. Agentes que a possuiam 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"

200Funcao removida com sucesso