Conversations & Message History

Query conversation history, message details, and audit trails including gate results and retry counts.

List Conversations

Retrieve all conversations for your tenant.

GET /api/tenants/me/conversations?limit=20&status=active

Query Parameters

Param	Type	Default	Notes
status	enum	all	active, closed, escalated
limit	number	20	Page size (max 100)
after	string		Cursor for pagination

Response

{
  "data": [
    {
      "id": "conv_ulid",
      "customerId": "cust_ulid",
      "customerName": "Nguyen Van A",
      "channel": "pancake",
      "status": "active",
      "messageCount": 5,
      "startedAt": "2026-03-12T10:00:00Z",
      "lastMessageAt": "2026-03-12T10:05:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "cursor_token"
  }
}

---

Get Conversation Details

Retrieve full message history for a conversation.

GET /api/tenants/me/conversations/:conversationId

Response

{
  "id": "conv_ulid",
  "customerId": "cust_ulid",
  "customerName": "Nguyen Van A",
  "channel": "pancake",
  "status": "active",
  "messages": [
    {
      "id": "msg_ulid",
      "role": "customer",
      "content": "Mình muốn kiểm tra đơn hàng",
      "type": "text",
      "timestamp": "2026-03-12T10:00:00Z"
    },
    {
      "id": "msg_ulid",
      "role": "assistant",
      "content": "Đơn hàng YD-001 đã được gửi...",
      "type": "text",
      "timestamp": "2026-03-12T10:00:05Z",
      "gateResults": {
        "repetition": { "pass": true, "score": 0.45 },
        "hallucination": { "pass": true, "claims": [] },
        "tone": { "pass": true },
        "relevance": { "pass": true, "score": 0.92 },
        "length": { "pass": true, "wordCount": 42 }
      },
      "retryCount": 0,
      "modelUsed": "claude-3-5-haiku",
      "latencyMs": 1200,
      "inputTokens": 500,
      "outputTokens": 45
    }
  ],
  "startedAt": "2026-03-12T10:00:00Z",
  "updatedAt": "2026-03-12T10:05:00Z"
}

Gate Results Breakdown

Each AI message includes full gate audit trail:

• repetition: Cosine similarity score vs last 5 messages (threshold: < 0.75)
• hallucination: Unverified claims (should be empty for pass)
• tone: Banned phrases found (should be empty for pass)
• relevance: Cross-encoder score vs customer message (threshold: > 0.3)
• length: Word count check (should be ≤ max configured)

---

Message Audit Trail

Click on any AI message to see:

• Retry count — How many times gates failed before passing
• Model used — LLM that generated response (Haiku or GPT-4o-mini fallback)
• Latency — Time from question to answer (ms)
• Token usage — Input + output tokens (for cost tracking)
• Tool calls — If a tool was executed, name + params + result

Example:

{
  "role": "assistant",
  "content": "Đơn hàng YD-001 đã được gửi...",
  "toolCalls": [
    {
      "name": "check_order_status",
      "params": { "order_id": "YD-001" },
      "result": {
        "status": "shipped",
        "tracking": "VNP123456"
      }
    }
  ],
  "retryCount": 2,
  "retryReasons": [
    "Gate 3 (Tone) failed: banned phrase detected",
    "Gate 1 (Repetition) failed: too similar to previous message"
  ],
  "modelUsed": "claude-3-5-haiku",
  "latencyMs": 3200,
  "inputTokens": 650,
  "outputTokens": 78
}

---

Search Conversations

Search for conversations by customer name.

GET /api/tenants/me/conversations/search?q=Nguyen&limit=10

Response

{
  "results": [
    {
      "id": "conv_ulid",
      "customerName": "Nguyen Van A",
      "channel": "pancake",
      "lastMessage": "...",
      "lastMessageAt": "2026-03-12T10:05:00Z"
    }
  ]
}

---

Conversation Export

Export conversation as JSON or PDF.

GET /api/tenants/me/conversations/:conversationId/export?format=json

---

Error Responses

Error	HTTP	Cause
NOT_FOUND	404	Conversation does not exist
INTERNAL_ERROR	500	Server error