LiyaSupport
API Reference

Conversations API

Read conversation state, messages, and AI signals. Retrieve AI drafts programmatically.

6 min read Updated July 2026
Conversations and Tickets are closely related. A Ticket is the top-level support request; a Conversation is the same object with additional message and AI metadata. Both share the same ID prefix (tkt_) and most endpoints are interchangeable.

Endpoints

GET/v1/conversationsList conversations
GET/v1/conversations/:idRetrieve a conversation
GET/v1/conversations/:id/messagesList messages
POST/v1/conversations/:id/messagesSend a reply or note
GET/v1/conversations/:id/ai-draftGet the current AI draft
POST/v1/conversations/:id/ai-draft/approveApprove and send AI draft
PATCH/v1/conversations/:idUpdate status, assignee, priority

List conversations

GET /v1/conversations

bash
curl "https://api.liyasupport.com/v1/conversations?status=open&limit=25" \
  -H "Authorization: Bearer lsk_live_..."

Query parameters

ParameterTypeDescription
statusstringopen | resolved | pending | all (default: all)
assigneestringUser ID or 'unassigned'
groupstringGroup ID
channelstringemail | chat | widget | api
prioritystringurgent | high | normal | low
tagstringFilter by tag
contactstringContact ID — all conversations for a contact
ai_intentstringFilter by AI-detected intent
limitintegerResults per page (max 100, default 25)
cursorstringPagination cursor

Conversation object

json
{
  "id": "conv_01JABCDEF",
  "ticket_id": "tkt_01JABCDE123",
  "status": "open",
  "channel": "email",
  "subject": "Payment still processing",
  "contact": { "id": "cnt_01JXYZ789", "name": "Jane Doe", "email": "[email protected]" },
  "assignee": { "id": "usr_01JAGENT", "name": "Priya K." },
  "group": { "id": "grp_01BILLING", "name": "Billing Team" },
  "priority": "high",
  "tags": ["billing"],
  "ai": {
    "intent": "billing_issue",
    "urgency": "high",
    "sentiment": "frustrated",
    "confidence": 87,
    "draft_available": true
  },
  "message_count": 3,
  "first_reply_at": "2026-07-03T14:25:00Z",
  "resolved_at": null,
  "created_at": "2026-07-03T14:22:00Z",
  "updated_at": "2026-07-03T14:35:00Z"
}

Retrieving AI drafts

You can retrieve the current AI draft for a conversation programmatically. This is useful for building custom agent interfaces or reviewing drafts in external systems.

GET /v1/conversations/:id/ai-draft

bash
curl https://api.liyasupport.com/v1/conversations/conv_01JABCDEF/ai-draft \
  -H "Authorization: Bearer lsk_live_..."
json
{
  "conversation_id": "conv_01JABCDEF",
  "draft": "Hi Jane! Your payment of $49 was processed at 2:34 PM...",
  "confidence": 87,
  "intent": "billing_issue",
  "sources": [
    { "article_id": "kb_01BILLING", "title": "Payment processing delays", "relevance": 0.94 }
  ],
  "generated_at": "2026-07-03T14:22:05Z"
}

Approving an AI draft via API

Use the approve endpoint to programmatically send an AI draft without agent review. Requires the tickets:write scope. Typically used in fully automated workflows (e.g. auto-reply pipelines).

bash
curl -X POST https://api.liyasupport.com/v1/conversations/conv_01JABCDEF/ai-draft/approve \
  -H "Authorization: Bearer lsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "send_as_user_id": "usr_01JAGENT" }'
Auto-approving AI drafts via the API bypasses human review. Use with caution and only after validating draft quality for the specific intent. See Confidence thresholds for guidance.