AI Features API

The AI Features API provides intelligent assistance for support operations including ticket summarization, sentiment analysis, smart suggestions, and similarity detection.

Overview

Relay's AI features use large language models to help agents work more efficiently. Features include:

• Ticket Summarization: Automatically summarize ticket threads
• Sentiment Analysis: Detect customer sentiment and urgency
• Priority Prediction: Suggest appropriate priority levels
• Reply Suggestions: Generate draft replies
• Tag Suggestions: Recommend relevant tags
• Assignee Suggestions: Match tickets to the best agent
• Article Suggestions: Find relevant knowledge base articles
• Similar Tickets: Find related tickets for context

Plan Requirements

AI features require specific subscription plans:

AI operations are usage-limited per billing period.

Summarize Ticket

Generate an AI-powered summary of a ticket and its conversation history.

Procedure: ai.summarizeTicket

Authentication: Required

Input:

{
  ticketId: string;  // UUID of the ticket
}

Example:

curl -X POST "https://your-domain.com/api/trpc/ai.summarizeTicket" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"ticketId":"ticket-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "summary": "Customer is experiencing login issues after password reset. They've tried clearing browser cache without success. The issue started after the recent system update on January 10th."
      }
    }
  }
}

Side Effects:

• Summary is automatically stored in the ticket's ai_summary field
• Increments organization's AI usage counter

Notes:

• Analyzes the ticket subject, description, and recent conversations (up to 5)
• Subject to AI usage limits based on subscription plan

Analyze Sentiment

Analyze the sentiment of text content to understand customer mood and urgency.

Procedure: ai.analyzeSentiment

Authentication: Required

Input:

{
  text: string;  // Text to analyze (minimum 1 character)
}

Example:

curl -X POST "https://your-domain.com/api/trpc/ai.analyzeSentiment" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"text":"I have been waiting for a response for 3 days now. This is unacceptable!"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "sentiment": "negative",
        "score": -0.75,
        "emotions": ["frustration", "anger"],
        "urgency": "high"
      }
    }
  }
}

Sentiment Values

Predict Priority

Suggest an appropriate priority level based on ticket content.

Procedure: ai.predictPriority

Authentication: Required

Input:

{
  subject: string;     // Ticket subject
  description: any;    // Ticket description (TipTap JSON or text)
}

Example:

curl -X POST "https://your-domain.com/api/trpc/ai.predictPriority" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "subject": "URGENT: Production server down",
      "description": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Our main production server is completely down. All customers are affected."}]}]}
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "priority": "urgent",
        "confidence": 0.95,
        "reasoning": "Production outage affecting all customers indicates urgent priority. Keywords: 'down', 'production', 'all customers affected'."
      }
    }
  }
}

Priority Values

Generate Reply Suggestions

Generate AI-powered draft replies for a ticket.

Procedure: ai.generateReplySuggestions

Authentication: Required

Input:

{
  ticketId: string;  // UUID of the ticket
}

Example:

curl -X POST "https://your-domain.com/api/trpc/ai.generateReplySuggestions" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"ticketId":"ticket-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "suggestions": [
          {
            "text": "Thank you for reaching out. I understand you're experiencing issues with login after your password reset. Let me help you resolve this.\n\nCould you please try the following steps:\n1. Clear your browser cookies specifically for our domain\n2. Try using an incognito/private browsing window\n3. Attempt the password reset process again\n\nIf the issue persists, I'll be happy to manually reset your credentials.",
            "tone": "helpful",
            "length": "detailed"
          },
          {
            "text": "I apologize for the inconvenience you're experiencing. I've looked into your account and can manually reset your credentials if the steps below don't work. Please try clearing your cookies and cache first.",
            "tone": "empathetic",
            "length": "concise"
          }
        ]
      }
    }
  }
}

Notes:

• Generates multiple suggestions with different tones
• Considers ticket subject, description, and conversation history

Suggest Tags

Recommend relevant tags based on ticket content.

Procedure: ai.suggestTags

Authentication: Required

Input:

{
  subject: string;     // Ticket subject
  description: any;    // Ticket description (TipTap JSON or text)
}

Example:

curl -X POST "https://your-domain.com/api/trpc/ai.suggestTags" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "subject": "Cannot login to mobile app",
      "description": "Getting authentication error on iOS app version 2.3.1"
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "tags": ["mobile", "ios", "authentication", "login"]
      }
    }
  }
}

Suggest Assignee

Recommend the best agent to handle a ticket based on content and agent expertise.

Procedure: ai.suggestAssignee

Authentication: Required

Input:

{
  ticketId?: string;   // Optional ticket UUID for context
  subject: string;     // Ticket subject
  description: any;    // Ticket description
}

Example:

curl -X POST "https://your-domain.com/api/trpc/ai.suggestAssignee" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "subject": "API integration issue with webhooks",
      "description": "Having trouble setting up webhooks for order updates"
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "suggestion": {
          "agentId": "user-uuid",
          "agentName": "Alex Developer",
          "confidence": 0.85,
          "reasoning": "Agent has expertise in API integrations and webhook implementations. Has resolved 15 similar tickets with high satisfaction."
        }
      }
    }
  }
}

Notes:

• Considers agent expertise tags and past ticket history
• Returns null if no suitable match is found
• Only considers agents and admins in the organization

Suggest Articles

Find relevant knowledge base articles for a ticket.

Procedure: ai.suggestArticles

Authentication: Required

Input:

{
  ticketId: string;  // UUID of the ticket
}

Example:

curl -X POST "https://your-domain.com/api/trpc/ai.suggestArticles" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"ticketId":"ticket-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "suggestions": [
          {
            "articleId": "article-uuid",
            "relevance": 0.92,
            "reasoning": "Directly addresses password reset troubleshooting",
            "article": {
              "id": "article-uuid",
              "title": "Troubleshooting Password Reset Issues",
              "content": "..."
            }
          },
          {
            "articleId": "article-uuid-2",
            "relevance": 0.78,
            "reasoning": "Contains browser cache clearing instructions",
            "article": {
              "id": "article-uuid-2",
              "title": "Browser Troubleshooting Guide",
              "content": "..."
            }
          }
        ]
      }
    }
  }
}

Notes:

• Only suggests published articles
• Returns empty array if no relevant articles found

Analyze Ticket (Comprehensive)

Run multiple AI analyses on a ticket in parallel for comprehensive insights.

Procedure: ai.analyzeTicket

Authentication: Required

Input:

{
  ticketId: string;  // UUID of the ticket
}

Example:

curl -X POST "https://your-domain.com/api/trpc/ai.analyzeTicket" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"ticketId":"ticket-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "summary": "Customer experiencing login issues after password reset...",
        "priority": {
          "priority": "normal",
          "confidence": 0.8,
          "reasoning": "Standard account access issue, no production impact"
        },
        "tags": ["login", "password", "authentication"],
        "sentiment": {
          "sentiment": "negative",
          "score": -0.4,
          "emotions": ["frustration"],
          "urgency": "medium"
        }
      }
    }
  }
}

Side Effects:

• Stores AI summary in ticket's ai_summary field
• Updates ticket tags if suggestions are valid

Notes:

• Runs summarization, priority prediction, tag suggestion, and sentiment analysis in parallel
• More efficient than calling individual endpoints when you need multiple analyses

Find Similar Tickets

Find tickets with similar content for context and reference.

Procedure: ai.findSimilarTickets

Authentication: Required

Input:

{
  ticketId: string;  // UUID of the ticket
}

Example:

curl -X POST "https://your-domain.com/api/trpc/ai.findSimilarTickets" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"ticketId":"ticket-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "similarTickets": [
          {
            "ticketId": "similar-ticket-uuid",
            "similarity": 0.89,
            "reasoning": "Both tickets involve password reset issues on mobile",
            "ticket": {
              "id": "similar-ticket-uuid",
              "subject": "Password reset not working on Android",
              "status": "resolved",
              "priority": "normal"
            }
          },
          {
            "ticketId": "similar-ticket-uuid-2",
            "similarity": 0.75,
            "reasoning": "Related authentication issue after account change",
            "ticket": {
              "id": "similar-ticket-uuid-2",
              "subject": "Auth token expired after email change",
              "status": "resolved",
              "priority": "normal"
            }
          }
        ]
      }
    }
  }
}

Notes:

• Searches up to 50 recent tickets for similarity
• Only searches within the same organization
• Useful for finding resolution patterns

Generate Ticket Embedding

Generate and store a vector embedding for a ticket. Used for semantic search and similarity matching.

Procedure: ai.generateTicketEmbedding

Authentication: Required

Input:

{
  ticketId: string;  // UUID of the ticket
}

Example:

curl -X POST "https://your-domain.com/api/trpc/ai.generateTicketEmbedding" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"ticketId":"ticket-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true,
        "tokenCount": 245,
        "embeddingDimensions": 1536
      }
    }
  }
}

Side Effects:

• Stores embedding in ticket record
• Tracks token usage for billing

Notes:

• Uses text-embedding-3-small model
• Embeddings enable semantic search and similarity matching

Get Token Usage

Retrieve AI token usage statistics for the organization.

Procedure: ai.getTokenUsage

Authentication: Required

Input:

{
  startDate?: string;                              // ISO date filter
  endDate?: string;                                // ISO date filter
  groupBy?: 'day' | 'week' | 'month' | 'operation' | 'model';
}

Example:

curl -X GET "https://your-domain.com/api/trpc/ai.getTokenUsage?input=%7B%22startDate%22:%222024-01-01%22,%22endDate%22:%222024-01-31%22%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "usage": [
          {
            "id": "uuid",
            "operation": "ticket_summary",
            "model": "gpt-4",
            "prompt_tokens": 450,
            "completion_tokens": 120,
            "total_tokens": 570,
            "created_at": "2024-01-15T10:30:00.000Z"
          }
        ],
        "totals": {
          "totalTokens": 15420,
          "totalPromptTokens": 12350,
          "totalCompletionTokens": 3070
        }
      }
    }
  }
}

Notes:

• Returns up to 1000 usage records
• Useful for monitoring AI usage and costs

Error Codes

Rate Limits

AI operations are subject to both request rate limits and usage-based limits:

When AI usage limits are exceeded, the API returns a TOO_MANY_REQUESTS error with details about when the limit resets.