Topic Strategies & Use Cases

Quadrillian organizes conversations into "topics" - each topic represents a conversation thread. The topic_key parameter identifies which conversation to show. This guide covers strategies for organizing topics effectively across different use cases.

Key Concept: Topics allow you to organize conversations logically, whether by user, support ticket, product feature, or any other meaningful grouping that fits your application.

Topic Key Patterns

Here are common patterns for organizing topic keys effectively:

User-Specific Topics

Create unique topics for each user or user session:

// User-specific conversation
topic_key: 'user-12345'

// User session-based
topic_key: 'session-abc123'
                    

Support Ticket Topics

Organize support conversations by ticket ID:

// Support ticket conversation
topic_key: 'support-ticket-12345'

// With priority level
topic_key: 'support-urgent-12345'
                    

Feature-Based Topics

Group conversations by product feature or page:

// Product feedback
topic_key: 'feedback-product-page'

// Feature-specific support
topic_key: 'support-billing'
                    

Sales & Marketing Topics

Organize sales conversations by lead source or company:

// Company-specific sales inquiry
topic_key: 'sales-company-abc'

// Lead source tracking
topic_key: 'sales-google-ads-123'
                    

Personal vs. Shared Topics

Important organizational principle: Decide whether topics should be personal to individual users or shared across multiple users.

Personal Topics (Include User ID)

Use when the conversation is specific to one user and their company:

// Personal user conversation
topic_key: 'user-12345'

// Personal support ticket
topic_key: 'support-user-12345-ticket-67890'

// Personal product inquiry
topic_key: 'inquiry-user-12345-product-abc'
                    

Shared Topics (Generic, No User ID)

Use when multiple users should have access to the same conversation:

// General support channel
topic_key: 'support-general'

// Product feedback channel
topic_key: 'feedback-product-x'

// Team collaboration
topic_key: 'team-marketing'
                    

⚠️ Access Control: For shared topics, you'll need to use the API multiple times to ensure all intended users have access to the same generic topic.

Database-Driven Topics

Create topics dynamically based on your database entities:

// Product-specific topics
topic_key: 'product-{product_id}'
// Examples: 'product-123', 'product-456'

// Event-specific topics
topic_key: 'event-{event_id}'
// Examples: 'event-789', 'event-101'

// Order-specific topics
topic_key: 'order-{order_id}'
// Examples: 'order-2023-001', 'order-2023-002'

// Project-specific topics
topic_key: 'project-{project_id}'
// Examples: 'project-abc123', 'project-def456'
                    

Creating Topics Programmatically

You can create topics programmatically using the Quadrillian API or JavaScript SDK:

Using the REST API (Recommended)

Topics should be created and managed from your backend for security reasons:

// Create a new topic (from your backend)
const response = await fetch('https://quadrillian.com/api/topic/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + jwtToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    external_key: 'support-ticket-12345',
    workspace_id: 456,
    topic_name: 'Support Request #12345'
  })
});

// Add user to existing topic (from your backend)
const addUserResponse = await fetch('https://quadrillian.com/api/topic/add-user', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + jwtToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    external_key: 'support-ticket-12345',
    workspace_id: 456
  })
});
                    

Security Considerations

All topic management operations must be performed from your backend server:

Topic Creation: Only your backend can create topics with external keys
User Addition: Only your backend can add users to topics
Access Control: Implement your own business logic for who can access which topics
JWT Authentication: All API calls must include valid JWT tokens

⚠️ Security Note: Never allow frontend users to directly create topics or add users. This must be controlled by your backend to prevent abuse and ensure proper access control.

Use Case Examples

Here are real-world examples of how to organize topics for different scenarios:

Customer Support System

Create unique topics for each support ticket with detailed organization:

support-ticket-12345 - Individual support tickets
support-urgent-12345 - High-priority tickets
support-billing-12345 - Billing-related issues
support-technical-12345 - Technical problems

E-commerce Platform

Organize conversations by order, product, or customer:

order-12345 - Order-specific conversations
product-feedback-widget-123 - Product feedback
customer-abc123 - Customer-specific chat
returns-12345 - Return/refund requests

SaaS Application

Group conversations by feature, team, or project:

feature-analytics - Analytics feature support
team-marketing - Marketing team chat
project-abc123 - Project-specific discussions
onboarding-user-123 - User onboarding help

Internal Team Communication

Organize internal conversations by department or project:

team-engineering - Engineering team chat
project-q4-launch - Project-specific discussions
meeting-standup-2024-01-15 - Meeting notes
announcement-company-wide - Company announcements

Best Practices

Follow these guidelines to organize topics effectively:

Naming Conventions

Use consistent prefixes: support-, sales-, feedback-
Include unique identifiers: Ticket numbers, user IDs, or timestamps
Keep it descriptive: Make topic keys self-explanatory
Avoid special characters: Use hyphens or underscores for separation

Topic Lifecycle Management

Archive old topics: Move completed conversations to archived state
Set expiration dates: Automatically close topics after inactivity
Monitor topic activity: Track which topics are most active
Clean up unused topics: Remove topics that are no longer needed

Security Considerations

Don't expose sensitive data: Avoid putting passwords or API keys in topic keys
Use workspace isolation: Topics are automatically isolated by workspace
Validate topic access: Ensure users can only access appropriate topics
Audit topic creation: Log who creates topics and when

Important: Topic keys are visible in URLs and logs, so avoid including sensitive information like passwords, API keys, or personal data in topic keys.