Tiqora
Docs AI Copilot

AI Copilot

Tiqora's AI Copilot provides intelligent assistance for support agents. It can summarize ticket conversations, find similar resolved tickets, analyze reply tone before sending, and automatically tag and prioritize incoming tickets. AI features consume credits from your plan's monthly allowance.

Generate Ticket Summary

POST /api/v1/tickets/{ticket_id}/ai-summary

Generates a concise AI-powered summary of the ticket conversation. The summary captures the customer's issue, actions taken so far, current status, and any outstanding items. Summaries are cached in the ticket's metadata to avoid redundant AI calls.

Example Request

POST /api/v1/tickets/01912345-6789-7abc-def0-123456789abc/ai-summary

No request body is required.

Example Response

{
  "data": {
    "ticket_id": "01912345-6789-7abc-def0-123456789abc",
    "summary": "Customer Jane Smith reported that payment processing fails when upgrading to the Professional plan (card ending 4242). Agent Alex Johnson identified an expired card on file, updated the payment method, and confirmed the charge went through. Customer confirmed the plan upgrade is now visible. Awaiting confirmation that the next billing cycle processes correctly.",
    "generated_at": "2025-01-15T10:45:00Z",
    "cached": false,
    "credits_used": 1
  }
}

Cached Response

When a summary already exists and the ticket has not been updated since, the cached version is returned:

{
  "data": {
    "ticket_id": "01912345-6789-7abc-def0-123456789abc",
    "summary": "Customer Jane Smith reported that payment processing fails...",
    "generated_at": "2025-01-15T10:45:00Z",
    "cached": true,
    "credits_used": 0
  }
}

Hint: The summary is regenerated automatically when the ticket receives new replies after the cached summary was created. You can also force regeneration by including "force": true in the request body.

Force Regeneration

{
  "force": true
}

Find Similar Tickets

GET /api/v1/tickets/{ticket_id}/similar

Uses pgvector cosine similarity search to find tickets with similar content. Results are weighted toward resolved tickets, making this useful for agents to find solutions that worked for similar issues in the past.

Query Parameters

Parameter Type Default Description
limit integer 5 Maximum results to return (max: 20)
min_score float 0.7 Minimum similarity score threshold (0.0-1.0)
status string — Filter by status (e.g., resolved)

Example Request

GET /api/v1/tickets/01912345-6789-7abc-def0-123456789abc/similar?limit=3&status=resolved

Example Response

{
  "data": [
    {
      "id": "01912345-aaaa-7abc-def0-123456789abc",
      "ticket_number": "987",
      "subject": "Credit card payment failing on upgrade",
      "status": "resolved",
      "priority": "high",
      "similarity_score": 0.92,
      "resolution_summary": "Expired card on file. Updated payment method and reprocessed charge.",
      "resolved_at": "2025-01-10T16:00:00Z",
      "created_at": "2025-01-10T14:00:00Z"
    },
    {
      "id": "01912345-bbbb-7abc-def0-123456789abc",
      "ticket_number": "1012",
      "subject": "Payment declined when changing plan",
      "status": "resolved",
      "priority": "medium",
      "similarity_score": 0.87,
      "resolution_summary": "Card issuer was blocking international transactions. Customer contacted bank and retried successfully.",
      "resolved_at": "2025-01-13T11:00:00Z",
      "created_at": "2025-01-12T09:00:00Z"
    },
    {
      "id": "01912345-cccc-7abc-def0-123456789abc",
      "ticket_number": "1025",
      "subject": "Billing error on plan renewal",
      "status": "resolved",
      "priority": "medium",
      "similarity_score": 0.78,
      "resolution_summary": "Subscription was stuck in a pending state. Manual re-sync with payment provider resolved it.",
      "resolved_at": "2025-01-14T10:00:00Z",
      "created_at": "2025-01-13T15:00:00Z"
    }
  ]
}

Hint: Similar tickets are computed using vector embeddings generated by the AI pipeline when tickets are created. If a ticket has no embedding yet (e.g., AI pipeline is still processing), this endpoint returns an empty array.

Tone Check

POST /api/v1/tickets/{ticket_id}/tone-check

Analyzes the tone of a draft reply before an agent sends it. Returns a tone score, detected issues, and suggestions for improvement. This helps ensure professional and empathetic communication.

Request Body

Field Type Required Description
text string Yes The draft reply text to analyze

Example Request

{
  "text": "As I've already explained, you need to update your card. This is the third time you've asked about this. Go to billing settings and fix it."
}

Example Response

{
  "data": {
    "ticket_id": "01912345-6789-7abc-def0-123456789abc",
    "score": 3.2,
    "max_score": 10.0,
    "tone": "impatient",
    "issues": [
      {
        "type": "dismissive_language",
        "text": "As I've already explained",
        "suggestion": "Remove reference to previous explanations. Restate the solution clearly."
      },
      {
        "type": "blame_language",
        "text": "This is the third time you've asked about this",
        "suggestion": "Remove the count of previous requests. Focus on resolving the issue."
      },
      {
        "type": "directive_tone",
        "text": "Go to billing settings and fix it",
        "suggestion": "Use softer language: 'You can update your card in Billing > Payment Methods. Here are the steps...'"
      }
    ],
    "suggested_rewrite": "Hi Jane,\n\nI'd be happy to walk you through updating your payment method:\n\n1. Log in to your account\n2. Navigate to **Billing > Payment Methods**\n3. Click **Update Card** and enter your new details\n\nOnce updated, your next payment will process automatically. Let me know if you need any help with this!\n\nBest regards",
    "credits_used": 1
  }
}

Tone Scores

Score Range Rating Description
8.0 - 10.0 Excellent Professional, empathetic, clear
6.0 - 7.9 Good Generally appropriate, minor improvements possible
4.0 - 5.9 Needs Improvement Tone issues detected, review before sending
1.0 - 3.9 Poor Significant issues, rewrite recommended

Issue Types

Issue Type Description
dismissive_language Makes the customer feel their concern is unimportant
blame_language Places fault on the customer
directive_tone Overly commanding rather than helpful
negative_framing Focuses on what cannot be done rather than what can
jargon Uses technical terms the customer may not understand
missing_empathy Lacks acknowledgment of the customer's frustration

Auto-Tag and Auto-Prioritize

These features run automatically as part of the AI pipeline when a ticket is created. They do not have dedicated API endpoints — instead, the results are stored in the ticket's metadata.

How It Works

  1. When a ticket is created, it enters the 6-stage AI pipeline
  2. The categorize stage analyzes the ticket content and suggests tags and a priority level
  3. The apply stage writes the suggestions to the ticket (if auto-apply is enabled in settings)
  4. Suggestions are always stored in metadata.ai_suggestions regardless of auto-apply settings

AI Suggestions in Ticket Metadata

When you fetch a ticket, check the metadata field for AI suggestions:

{
  "data": {
    "id": "01912345-6789-7abc-def0-123456789abc",
    "subject": "Cannot access billing portal",
    "status": "open",
    "priority": "high",
    "tags": ["billing", "access-issue"],
    "metadata": {
      "ai_suggestions": {
        "tags": ["billing", "access-issue", "permissions"],
        "priority": "high",
        "category": "Account Access",
        "department": "Billing",
        "confidence": 0.89,
        "applied_at": "2025-01-15T09:30:05Z"
      },
      "ai_summary": "Customer reports 403 error when accessing the billing portal..."
    }
  }
}

AI Pipeline Configuration

The AI pipeline behavior can be configured per tenant in Settings > AI:

Setting Description Default
auto_categorize Automatically assign category based on content true
auto_tag Automatically add suggested tags true
auto_prioritize Automatically set priority based on content analysis false
auto_route Automatically assign to department based on content true
auto_reply Generate and send AI reply (if confidence is high) false
suggest_reply Generate a draft reply for agent review true

When auto-apply is disabled for a feature, the AI still generates suggestions in the metadata. Agents can review and apply them manually from the dashboard.

Credit Usage

Each AI operation consumes credits from your plan's monthly allowance:

Operation Credits
Generate summary 1
Find similar tickets 0 (uses pre-computed embeddings)
Tone check 1
Auto-categorize (pipeline) 1
Auto-tag (pipeline) 0 (included in categorize)
Auto-prioritize (pipeline) 0 (included in categorize)
Generate reply (pipeline) 2
Suggest KB metadata 1

Checking Credit Balance

Your current credit usage is available in the billing API:

GET /api/v1/billing/usage

{
  "data": {
    "ai_credits": {
      "used": 1847,
      "limit": 5000,
      "remaining": 3153,
      "resets_at": "2025-02-01T00:00:00Z"
    }
  }
}

Important: When credits are exhausted, AI endpoints return a 429 error with code AI_CREDITS_EXHAUSTED. The AI pipeline gracefully skips AI stages but still processes the ticket through non-AI stages (e.g., SLA timer start, webhook delivery).

Error Responses

No Embedding Available

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Ticket embeddings are not yet available. The AI pipeline may still be processing."
  }
}

Credits Exhausted

{
  "error": {
    "code": "AI_CREDITS_EXHAUSTED",
    "message": "Your AI credit allowance has been used for this billing period. Credits reset on 2025-02-01."
  }
}

Best Practices

  1. Use summaries for ticket handoffs — When reassigning a ticket to another agent, generate a summary so they can quickly get up to speed without reading the entire conversation.

  2. Run tone check on escalated tickets — Escalated customers are already frustrated. Tone-checking replies before sending can prevent further escalation.

  3. Review AI suggestions before auto-applying — Start with auto-apply disabled and review suggestions manually for the first few weeks. Enable auto-apply once you are confident in the accuracy.

  4. Monitor credit consumption — Track credits in the billing dashboard. If you are hitting limits, consider upgrading your plan or reducing auto-reply usage (the most credit-intensive feature).

  5. Use similar tickets for training — The similar tickets feature is valuable for onboarding new agents. It shows them how experienced agents resolved comparable issues.

Previous
Analytics