Threads & Timeline

As threads são a cronologia do ticket: cada mensagem do cliente, resposta do agente, nota interna e evento de sistema é uma linha na timeline, em ordem. Enquanto o ticket guarda o estado atual, as threads guardam o registro imutável de tudo que aconteceu.

A visão muda conforme o domínio: o staff enxerga a timeline completa (/v1/helpdesk/agent), enquanto o cliente recebe apenas a timeline pública (/v1/helpdesk/customer, filtro publicOnly) — notas internas e eventos de sistema não aparecem no portal.

Headers obrigatórios

Todas as requisições devem incluir o header X-Helpdesk-Id (UUID) e Authorization: Bearer {token} — token do agente na área de staff, token do cliente no portal.

---

Estrutura de Dados Principal

Campo	Tipo	Descrição
id	Number	Identificador da thread.
helpdeskTicketId	Number	Ticket ao qual a thread pertence.
senderType	String	Autor: customer, agent ou system.
helpdeskCustomerId	Number	Cliente autor (quando senderType = customer).
helpdeskAgentId	Number	Agente autor (quando senderType = agent).
senderLabel	String	Nome do autor no momento do envio (desnormalizado para exibição).
body	String	Conteúdo da mensagem ou descrição do evento.
isHtml	Boolean	Indica que o body é HTML.
isInternal	Boolean	Nota interna — invisível ao cliente.
channel	String	Canal da mensagem: portal, email, api, chat ou phone.
eventType	String	Tipo do evento de sistema (quando senderType = system).
eventData	Object	Dados estruturados do evento (origem, destino, ator, etc.).
helpdeskFiles	Array	Anexos da mensagem.

Tipos de Item na Timeline

Tipo	Visível ao cliente?	Descrição
Mensagem do cliente (customer)	Sim	Abertura e respostas do solicitante.
Resposta do agente (agent, isInternal: false)	Sim	Resposta pública do atendimento.
Nota interna (agent, isInternal: true)	Não	Comentário privado entre agentes.
Evento de sistema (system)	Não	Auditoria invisível de mudanças do ticket.

Auditoria Invisível (Eventos de Sistema)

Toda mudança relevante do ticket grava uma thread system com eventType e eventData estruturados, para o frontend renderizar diferente de uma mensagem comum:

eventType	Quando ocorre	eventData
assigned	Atribuição, transferência, devolução à fila ou auto-assign	{ from, to, actorAgentId, automatic? }
status_changed	Mudança de status (manual, auto-reopen, auto-pending, auto-close)	{ from, to, actorAgentId }
priority_changed	Mudança de prioridade (com recálculo de SLA)	{ from, to, actorAgentId }
category_changed	Mudança de categoria	{ from, to, actorAgentId }

---

Endpoints do Staff

Listar Timeline (Completa)

Lista todas as threads do ticket — mensagens, notas internas e eventos de sistema.

GET /v1/helpdesk/agent/tickets/:ticketId/threads

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
ticketId	number	Sim	O ID do ticket.

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).
orderDirection	string	Não	Direção da ordenação cronológica: asc ou desc.

Respostas

200 OK

Retorna um objeto de paginação com a timeline completa do ticket.

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "helpdeskTicketId": 1,
      "senderType": "customer",
      "helpdeskCustomerId": 1,
      "helpdeskAgentId": null,
      "senderLabel": "Carlos Pereira",
      "body": "Desde ontem o login retorna erro 500.",
      "isHtml": false,
      "isInternal": false,
      "channel": "portal",
      "eventType": null,
      "eventData": null,
      "createdAt": "2026-09-01T10:05:33.000+00:00",
      "helpdeskFiles": []
    },
    {
      "id": 2,
      "helpdeskTicketId": 1,
      "senderType": "system",
      "helpdeskCustomerId": null,
      "helpdeskAgentId": null,
      "senderLabel": null,
      "body": "Ticket atribuído automaticamente para Maria Silva",
      "isHtml": false,
      "isInternal": false,
      "channel": null,
      "eventType": "assigned",
      "eventData": { "from": null, "to": 1, "actorAgentId": null, "automatic": true },
      "createdAt": "2026-09-01T10:05:34.000+00:00",
      "helpdeskFiles": []
    }
  ]
}

404 Not Found

Ocorre quando o ticket não existe na instância.

Responder ou Anotar

Adiciona uma mensagem do agente à timeline — resposta pública ou nota interna. Anexos são vinculados por fileIds (arquivos enviados previamente em Arquivos).

Respostas públicas atualizam as métricas de tempo do ticket (firstReplyAt, lastAgentReplyAt) e disparam o auto-pending; notas internas não alteram métricas nem status.

POST /v1/helpdesk/agent/tickets/:ticketId/threads

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
body	string	Sim	Conteúdo da mensagem ou nota.
isHtml	boolean	Não	Indica que o body é HTML (padrão: false).
isInternal	boolean	Não	true para nota interna — invisível ao cliente (padrão: false).
channel	string	Não	Canal da mensagem; omitido, herda o canal do ticket.
fileIds	number[]	Não	IDs de arquivos anexados à mensagem.

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/helpdesk/agent/tickets/1/threads" \
  -H "X-Helpdesk-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Identificamos o problema e aplicamos a correção. Pode validar?",
    "fileIds": [4]
  }'

Respostas

201 Created

Retorna o ID da thread criada.

{
  "id": 3
}

---

Endpoints do Cliente

Listar Timeline (Pública)

Lista apenas as threads públicas do ticket do cliente autenticado (publicOnly): mensagens do próprio cliente e respostas públicas dos agentes. Notas internas e eventos de sistema nunca aparecem.

GET /v1/helpdesk/customer/tickets/:ticketId/threads

Parâmetros de Rota e Query

Mesmos parâmetros da listagem do staff (ticketId na rota; page, perPage e orderDirection na query).

Respostas

200 OK

Retorna um objeto de paginação com a timeline pública do ticket.

404 Not Found

Ocorre quando o ticket não existe ou pertence a outro cliente.

Como o cliente responde?

O portal não tem endpoint de criação de thread: a resposta do cliente é feita por POST /v1/helpdesk/customer/tickets/:id/reply (veja Tickets), que internamente cria a thread e aplica as regras automáticas (auto-reopen, métricas).