Skip to main content

​
Concept

A Conversation represents the complete thread of an exchange between a customer and a Timely agent — from the first “hello” to closing. Each conversation belongs to exactly one channel, one contact, and one agent, and contains all messages exchanged in chronological order. The conversation status controls whether the AI agent is responding automatically or whether a human has taken over the support. Conversations are created automatically when a customer initiates contact through any connected channel. You can also create conversations programmatically via API — useful for proactively initiating a support session with an existing contact.

​
Conversation Status

StatusDescription
openActive conversation, agent responding automatically
humanHuman has taken over (active handoff)
closedConversation closed — agent does not respond to new messages
waitingWaiting for customer response

​
Lifecycle

customer sends message → conversation created (open)
    │
    ├── AI agent responds automatically
    │       │
    │       ├── handoff requested → human
    │       │       │
    │       │       └── human resolves → resume AI (open) or close (closed)
    │       │
    │       └── conversation resolved → closed
    │
    └── no customer response → waiting → timeout → closed

​
Main Fields

FieldTypeDescription
idstring (UUID)Unique conversation ID
agent_idstring (UUID)Agent managing the conversation
channel_idstring (UUID)Channel through which the conversation arrived
contact_idstring (UUID)Associated contact
statusenumopen | human | closed | waiting
assigned_tostring (UUID)ID of the human agent (if in handoff)
subjectstringSubject or automatic summary
tagsarrayTags for categorization
created_atstringISO 8601 conversation start timestamp
closed_atstringISO 8601 closing timestamp
last_message_atstringISO 8601 last message timestamp

​
Available Endpoints

See the left sidebar for the full list of endpoints in this group. Each endpoint has its own page with request/response schema, cURL/JS/Python examples, and an interactive playground.

​
Next Steps

Your first request

If you haven’t made your first call yet, start here.