Referência de Conversations

Conceito

Uma Conversation representa o fio completo de uma troca entre um cliente e um agente Timely — do primeiro “olá” até o encerramento. Cada conversa pertence a exatamente um canal, um contato e um agente, e contém todas as mensagens trocadas em ordem cronológica. O status da conversa controla se o agente de IA está respondendo automaticamente ou se um humano assumiu o atendimento. Conversas são criadas automaticamente quando um cliente inicia contato por qualquer canal conectado. Você também pode criar conversas programaticamente via API — útil para proativamente iniciar um atendimento com um contato existente.

Status da conversa

Status	Descrição
`open`	Conversa ativa, agente respondendo automaticamente
`human`	Humano assumiu o atendimento (handoff ativo)
`closed`	Conversa encerrada — agente não responde novas mensagens
`waiting`	Aguardando resposta do cliente

Ciclo de vida

cliente envia mensagem → conversa criada (open)
    │
    ├── agente IA responde automaticamente
    │       │
    │       ├── handoff solicitado → human
    │       │       │
    │       │       └── humano resolve → retomar IA (open) ou fechar (closed)
    │       │
    │       └── conversa resolvida → closed
    │
    └── sem resposta do cliente → waiting → timeout → closed

Campos principais

Campo	Tipo	Descrição
`id`	string (UUID)	ID único da conversa
`agent_id`	string (UUID)	Agente que gerencia a conversa
`channel_id`	string (UUID)	Canal pelo qual a conversa chegou
`contact_id`	string (UUID)	Contato associado
`status`	enum	`open` \| `human` \| `closed` \| `waiting`
`assigned_to`	string (UUID)	ID do atendente humano (se em handoff)
`subject`	string	Assunto ou resumo automático
`tags`	array	Tags para categorização
`created_at`	string	ISO 8601 de início da conversa
`closed_at`	string	ISO 8601 de encerramento
`last_message_at`	string	ISO 8601 da última mensagem

Endpoints disponíveis

Consulte a barra lateral à esquerda para a lista completa de endpoints deste grupo. Cada endpoint tem sua própria página com schema de request/response, exemplos em cURL/JS/Python e playground interativo.

Próximos passos

Primeira requisição

Se você ainda não fez sua primeira chamada, comece por aqui.

Excluir contato Listar conversas

​Conceito

​Status da conversa

​Ciclo de vida

​Campos principais

​Endpoints disponíveis

​Próximos passos

Primeira requisição

Conceito

Status da conversa

Ciclo de vida

Campos principais

Endpoints disponíveis

Próximos passos