Conversations API

Conversations API

Retrieve and manage customer conversations.

List Conversations

GET /v1/projects/:project_id/conversations

Returns conversations for a project, with optional filters.

Query parameters:

Parameter	Type	Description
status	string	Filter by status: active, closed, escalated
channel	string	Filter by channel: telegram, jivo
limit	integer	Max results per page (default: 50)
offset	integer	Pagination offset

Response:

{
  "conversations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": "my-company",
      "channel": "telegram",
      "user_name": "John",
      "status": "active",
      "created_at": "2025-03-20T14:00:00Z",
      "updated_at": "2025-03-20T14:15:00Z"
    }
  ]
}

Get Messages

GET /v1/conversations/:id/messages

Returns all messages in a conversation.

Response:

{
  "messages": [
    {
      "id": "msg-001",
      "role": "user",
      "content": "My server is not responding",
      "created_at": "2025-03-20T14:00:00Z"
    },
    {
      "id": "msg-002",
      "role": "assistant",
      "content": "I'll check the status of your server right away...",
      "model": "gpt-4",
      "created_at": "2025-03-20T14:00:02Z"
    }
  ]
}

Update Conversation Status

PATCH /v1/conversations/:id/status

Change the status of a conversation.

Request body:

{
  "status": "closed"
}

Valid statuses: active, closed, escalated.

Get Conversation Quality

GET /v1/conversations/:id/quality

Returns quality metrics for a conversation, including B-score components.

Rate Conversation

POST /v1/conversations/:id/rate

Submit a quality rating for a conversation.