← Back to Docs
Conversations API
Access conversation history and message data programmatically.
Overview
The Conversations API lets you retrieve chat conversations and messages from your widget. Use it to analyze visitor questions, export chat history, or build custom analytics.
List Conversations
Get all conversations for a website, sorted by most recent.
GET /api/websites/:website_id/conversations?page=1&limit=20
Response:
{
"items": [
{
"id": "uuid",
"visitor_id": "visitor-session-id",
"message_count": 6,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:35:00Z"
}
],
"total": 142,
"page": 1,
"pages": 8
}Get Conversation Messages
Retrieve all messages in a specific conversation, including source citations.
GET /api/websites/:website_id/conversations/:conversation_id/messages
Response:
[
{
"id": "uuid",
"role": "user",
"content": "How do I reset my password?",
"sources": null,
"created_at": "2024-01-15T10:30:00Z"
},
{
"id": "uuid",
"role": "assistant",
"content": "To reset your password, go to Settings > Account...",
"sources": [
{
"document": "user-guide.pdf",
"chunk": "Password reset instructions...",
"score": 0.94
}
],
"created_at": "2024-01-15T10:30:02Z"
}
]Chat via API
Send a chat message and receive a streamed response. This is the same endpoint the widget uses.
POST /api/chat
Authorization: Bearer rk_live_abc123
Body:
{
"message": "What are your return policies?",
"conversation_id": "uuid-or-null-for-new"
}
Response: Server-Sent Events (SSE) stream
data: {"type": "token", "content": "Based"}
data: {"type": "token", "content": " on"}
data: {"type": "token", "content": " your"}
...
data: {"type": "sources", "sources": [...]}
data: {"type": "done"}Delete a Conversation
Remove a conversation and all its messages. This action is irreversible.
DELETE /api/websites/:website_id/conversations/:conversation_id
Response:
{
"message": "Conversation deleted"
}