Eventos de agente - Timely.ai

Esses eventos cobrem os momentos de transição do fluxo de atendimento — quando o agente de IA percebe que precisa de um humano, quando o humano assume de fato, e quando a conversa é transferida entre atendentes. Use-os para rastrear o tempo de handoff, medir qualidade da triagem da IA e monitorar filas de atendimento.

Lista de eventos

Evento	Quando dispara
`agent.handoff_started`	O agente de IA sinaliza que quer passar o controle para um humano
`agent.handoff_completed`	Um atendente humano assume a conversa efetivamente
`agent.transferred`	A conversa é transferida de um atendente para outro

`agent.handoff_started`

Quando dispara

O agente de IA detecta que a situação requer intervenção humana — pode ser por regra de transferência configurada (ex: cliente pedindo falar com humano, palavra-chave detectada, número de tentativas de resolução esgotadas) ou por decisão autônoma do modelo. Nesse momento, a conversa entra em fila de espera para um atendente, mas o agente ainda está no controle.

Payload

{
  "event": "agent.handoff_started",
  "event_id": "evt_01HX6A1K9MFQR4YZDNV7P9WCE",
  "timestamp": "2026-04-19T14:45:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "channel_id": "chan_789",
    "channel_type": "whatsapp",
    "agent_id": "agt_101",
    "handoff_reason": "user_requested",
    "handoff_note": "Cliente pediu explicitamente para falar com atendente",
    "queue_id": "queue_sales",
    "started_at": "2026-04-19T14:45:00Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`agent_id`	string	ID do agente de IA que iniciou o handoff
`handoff_reason`	enum	`user_requested`, `rule_triggered`, `max_attempts`, `sentiment_negative`, `autonomous`
`handoff_note`	string \| null	Contexto gerado pelo agente sobre o motivo
`queue_id`	string \| null	ID da fila de atendimento onde a conversa foi enfileirada
`started_at`	string	Timestamp ISO 8601 do início do handoff

Exemplo de uso

Use handoff_started com handoff_reason para medir o volume de handoffs por motivo. Um alto número de autonomous pode indicar que o agente não está treinado o suficiente para determinado tema.

`agent.handoff_completed`

Quando dispara

Um atendente humano aceita (ou é atribuído a) uma conversa que estava em handoff. A partir desse momento, o agente de IA para de responder automaticamente e o atendente está no controle.

Payload

{
  "event": "agent.handoff_completed",
  "event_id": "evt_01HX6B3M2PGTS6YADOV8Q1XDF",
  "timestamp": "2026-04-19T14:47:30Z",
  "workspace_id": "ws_abc123",
  "data": {
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "channel_id": "chan_789",
    "channel_type": "whatsapp",
    "agent_id": "agt_101",
    "attendant_id": "usr_321",
    "handoff_wait_seconds": 150,
    "handoff_note": "Cliente pediu explicitamente para falar com atendente",
    "completed_at": "2026-04-19T14:47:30Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`agent_id`	string	ID do agente de IA que iniciou o handoff
`attendant_id`	string	ID do atendente humano que assumiu
`handoff_wait_seconds`	integer	Tempo em segundos entre `handoff_started` e `handoff_completed`
`handoff_note`	string \| null	Contexto passado pelo agente para o atendente
`completed_at`	string	Timestamp ISO 8601 da conclusão do handoff

Exemplo de uso

Calcule o SLA de handoff com handoff_wait_seconds. Se esse valor estiver alto nos horários de pico, considere expandir a equipe ou ajustar as regras de roteamento de fila.

`agent.transferred`

Quando dispara

Uma conversa que já está com um atendente humano é transferida para outro atendente. Pode ser uma transferência manual (o próprio atendente escolhe passar) ou automática por regra de departamento.

Payload

{
  "event": "agent.transferred",
  "event_id": "evt_01HX6C5P4RHTW7ZBEPV9S2YEG",
  "timestamp": "2026-04-19T15:05:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "channel_id": "chan_789",
    "channel_type": "whatsapp",
    "from_attendant_id": "usr_321",
    "to_attendant_id": "usr_654",
    "transfer_reason": "manual",
    "transfer_note": "Encaminhando para o time financeiro",
    "transferred_at": "2026-04-19T15:05:00Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`from_attendant_id`	string	ID do atendente que transferiu
`to_attendant_id`	string	ID do atendente que recebeu
`transfer_reason`	enum	`manual`, `rule`, `api`
`transfer_note`	string \| null	Observação do atendente sobre o motivo da transferência
`transferred_at`	string	Timestamp ISO 8601 da transferência

Exemplo de uso

Rastreie agent.transferred para identificar gargalos. Se um mesmo atendente sempre transfere para o mesmo colega, pode ser que a fila de roteamento precise ser ajustada para já direcionar esses contatos corretamente desde o início.

Transferências entre agente de IA e humano geram handoff_started + handoff_completed. Transferências de humano para humano geram apenas agent.transferred. Não confunda os dois fluxos ao montar relatórios.

​Lista de eventos

​agent.handoff_started

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

​agent.handoff_completed

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

​agent.transferred

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

Lista de eventos

`agent.handoff_started`

Quando dispara

Payload

Campos principais

Exemplo de uso

`agent.handoff_completed`

Quando dispara

Payload

Campos principais

Exemplo de uso

`agent.transferred`

Quando dispara

Payload

Campos principais

Exemplo de uso