Departamentos

Organize a equipe em departamentos (Suporte, Financeiro…), vincule cada atendente a um departamento e transfira conversas entre eles. O modelo de dados, a regra de visibilidade e os endpoints para automatizar a partir do seu sistema.

Um departamento agrupa atendentes por área (Suporte, Financeiro, Comercial…). Cada atendente fica vinculado a um departamento; cada conversa "está" em um departamento e pode ser transferida entre eles. O caso típico: o contato cai no Suporte, o atendente percebe que é uma questão financeira e transfere a conversa para o Financeiro — ela sai da visão do Suporte e entra na fila do Financeiro.

Departamentos são escopados ao Projeto da sua API key e seguem a mesma autenticação por Authorization: Bearer do resto da API. O CRUD e a transferência também estão disponíveis para integradores via API key.

O modelo

Atendente → 1 departamento. Cada membro da equipe pode estar vinculado a um departamento (ou a nenhum). Definido na página Equipe do painel (ou via API do painel).
Conversa → 1 departamento (ou nenhum). Uma conversa "está" em um departamento por vez. Sem departamento = fila geral, visível a todos os atendentes.
Como a conversa cai num departamento: (1) pelo número — cada instância pode ter um departamento padrão (no cadastro da instância) que o ticket novo herda; (2) pelo chatbot — o nó "Transferir" do construtor de fluxo pode mandar pra um departamento; (3) por transferência manual (botão no topo do chat) ou pela API. Sem nenhum desses, a conversa fica na fila geral (sem departamento, visível a todos).
Roteamento automático respeita o departamento: quando a Equipe usa atribuição automática (menos ocupado / rodízio), o atendente escolhido sai do departamento da conversa; na fila geral, de qualquer atendente online.

Visibilidade por departamento

A regra de quem enxerga o quê depende da permissão ver_todas_conversas:

Quem	Enxerga
Dono/Admin, ou atendente com `ver_todas_conversas`	Todas as conversas do Projeto.
Atendente sem `ver_todas_conversas`	As conversas atribuídas a ele + as sem dono do seu departamento + as sem dono da fila geral (sem departamento).

Ou seja: ao transferir uma conversa do Suporte para o Financeiro, ela deixa de aparecer para os atendentes do Suporte (que não têm "ver todas") e passa a aparecer para os do Financeiro. Conversas sem departamento ficam visíveis para todos — é a fila de triagem.

Transferir uma conversa

Transferir é o caminho principal e foi feito para ser rápido:

No painel: no topo do chat, ao lado das etiquetas, há um botão com o departamento atual. Clique e escolha o destino (ou "Fila geral" para tirar o departamento).
Na API: POST /v1/inbox/conversations/{id}/department com { "departmentId": "..." }.

A transferência solta o atendente atual: a conversa volta para a fila do departamento de destino (sem dono), para que alguém daquele departamento assuma. Envie departmentId: null para mandar para a fila geral.

No painel

Ação	Onde
Criar/excluir departamento	Inbox → engrenagem Configurar atendimento → aba Deptos
Vincular atendente a um departamento	Equipe → seletor de departamento no atendente
Departamento padrão do número	Instâncias → seletor "Departamento padrão" na instância
Transferir a conversa	Inbox → botão de departamento no topo do chat
Filtrar o inbox por departamento	Inbox → chips de departamento acima da lista
Chatbot transfere pra um departamento	Fluxos → nó Transferir → campo "Transferir para o departamento"

Gerenciar o catálogo de departamentos e vincular atendentes exige um usuário dono ou administrador. Transferir uma conversa é liberado a qualquer atendente com acesso à conversa.

Na API

Operação	Método e rota
Listar departamentos	`GET /v1/inbox/departments`
Criar departamento	`POST /v1/inbox/departments`
Atualizar departamento	`PATCH /v1/inbox/departments/{id}`
Remover departamento	`DELETE /v1/inbox/departments/{id}`
Transferir a conversa	`POST /v1/inbox/conversations/{id}/department`

A conversa no Inbox traz departmentId e departmentName; a listagem aceita o filtro ?departmentId= para ver só um departamento. O vínculo do atendente a um departamento é feito pelo painel (não exposto na API de integração).

Exemplos

Criar um departamento:

curl -X POST https://api.pepinozap.com.br/v1/inbox/departments \
  -H "Authorization: Bearer pzk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Financeiro", "description": "Cobrança, boletos e notas fiscais" }'

Transferir uma conversa para esse departamento:

curl -X POST https://api.pepinozap.com.br/v1/inbox/conversations/conv_123/department \
  -H "Authorization: Bearer pzk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{ "departmentId": "dep_financeiro" }'

Devolver a conversa para a fila geral (sem departamento):

curl -X POST https://api.pepinozap.com.br/v1/inbox/conversations/conv_123/department \
  -H "Authorization: Bearer pzk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{ "departmentId": null }'

Pontos importantes

Soft-delete: remover um departamento o desativa. As conversas que estavam nele voltam para a fila geral e os atendentes vinculados perdem o vínculo — nada de histórico quebra.
Nome único por Projeto (case-insensitive); nome repetido retorna 409.
Departamentos e etiquetas são ortogonais: o departamento diz qual fila atende a conversa; a etiqueta é uma marcação livre. Uma conversa pode ter os dois.

Veja também Equipe e permissões (atendentes, presença e a permissão ver_todas_conversas que rege a visibilidade acima).