Respostas Prontas

As respostas prontas (canned responses) são os templates e macros do atendimento: textos completos que o agente insere na resposta com um clique ou atalho, em vez de redigir do zero.

O recurso tem ownership pessoal: toda resposta pronta pertence ao agente que a criou (helpdeskAgentId é preenchido automaticamente no cadastro). Apenas o autor ou um admin pode editá-la ou removê-la — demais agentes recebem 403 FORBIDDEN. O contador usageCount mostra quais templates realmente pegaram.

Headers obrigatórios

Todas as requisições devem incluir o header X-Helpdesk-Id (UUID) e Authorization: Bearer {token} com o token do agente (guard helpdeskAgent).

---

Estrutura de Dados Principal

Campo	Tipo	Descrição
id	Number	Identificador da resposta pronta.
helpdeskAgentId	Number	Agente autor (preenchido automaticamente na criação).
title	String	Título da resposta (máx. 150 caracteres).
shortcut	String	Atalho para inserção rápida (máx. 40 caracteres, opcional).
body	String	Conteúdo do template.
usageCount	Number	Quantas vezes a resposta foi utilizada.
isActive	Boolean	Resposta ativa.

---

Endpoints

Listar Respostas Prontas

Lista as respostas prontas da instância, com paginação, busca e filtros.

GET /v1/helpdesk/agent/canned-responses

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
page	number	Não	O número da página (mínimo: 1).
perPage	number	Não	Itens por página (entre 1 e 100, padrão: 25).
search	string	Não	Busca por termo no título (máx. 150 caracteres).
helpdeskAgentId	number	Não	Filtra por autor.
isActive	boolean	Não	Filtra por ativas/inativas.
orderBy	string	Não	Campo de ordenação: id, title, usageCount ou createdAt.
orderDirection	string	Não	Direção: asc ou desc.

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de respostas prontas.

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "helpdeskAgentId": 1,
      "title": "Boas-vindas",
      "shortcut": "/oi",
      "body": "Olá! Obrigado por entrar em contato. Já estou analisando seu chamado.",
      "usageCount": 12,
      "isActive": true,
      "createdAt": "2026-09-01T10:05:33.000+00:00",
      "updatedAt": "2026-09-01T10:05:33.000+00:00"
    }
  ]
}

Listar para Dropdown

Retorna as respostas prontas em formato simplificado (value/label), ideal para o seletor de macros na tela de atendimento.

GET /v1/helpdesk/agent/canned-responses/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
search	string	Não	Busca por termo no título (máx. 150 caracteres).
helpdeskAgentId	number	Não	Filtra por autor.
limit	number	Não	Quantidade máxima de itens (entre 1 e 100).

Respostas

200 OK

Retorna um array com as respostas em formato value/label.

[
  {
    "value": 1,
    "label": "Boas-vindas"
  }
]

Obter Resposta Pronta por ID

GET /v1/helpdesk/agent/canned-responses/:id

Respostas

200 OK

Retorna os dados da resposta pronta.

404 Not Found

Ocorre quando a resposta não existe na instância.

Criar Resposta Pronta

Cria uma resposta pronta vinculada ao agente autenticado.

POST /v1/helpdesk/agent/canned-responses

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
title	string	Sim	Título da resposta (máx. 150 caracteres).
shortcut	string	Não	Atalho para inserção rápida (máx. 40 caracteres).
body	string	Sim	Conteúdo do template.
isActive	boolean	Não	Resposta ativa (padrão: true).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/helpdesk/agent/canned-responses" \
  -H "X-Helpdesk-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Boas-vindas",
    "shortcut": "/oi",
    "body": "Olá! Obrigado por entrar em contato. Já estou analisando seu chamado."
  }'

Respostas

201 Created

Retorna o ID da resposta criada.

{
  "id": 1
}

Atualizar Resposta Pronta

Atualiza uma resposta pronta. Apenas o autor ou um admin pode editar.

PUT /v1/helpdesk/agent/canned-responses/:id

Payload (Body)

Todos os campos da criação são opcionais no update; envie shortcut: null para remover o atalho.

Respostas

204 No Content

Atualização concluída com sucesso.

403 Forbidden

O agente autenticado não é o autor nem admin.

{
  "message": "Você não tem permissão para gerenciar esta resposta pronta",
  "code": "FORBIDDEN"
}

Remover Resposta Pronta

Remove uma resposta pronta (exclusão lógica). Mesma regra de ownership do update.

DELETE /v1/helpdesk/agent/canned-responses/:id

Respostas

204 No Content

Remoção concluída com sucesso.