Skip to main content

​
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

StatusDescrição
openConversa ativa, agente respondendo automaticamente
humanHumano assumiu o atendimento (handoff ativo)
closedConversa encerrada — agente não responde novas mensagens
waitingAguardando 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

CampoTipoDescrição
idstring (UUID)ID único da conversa
agent_idstring (UUID)Agente que gerencia a conversa
channel_idstring (UUID)Canal pelo qual a conversa chegou
contact_idstring (UUID)Contato associado
statusenumopen | human | closed | waiting
assigned_tostring (UUID)ID do atendente humano (se em handoff)
subjectstringAssunto ou resumo automático
tagsarrayTags para categorização
created_atstringISO 8601 de início da conversa
closed_atstringISO 8601 de encerramento
last_message_atstringISO 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.