Router & Handoff

Documentation Index

Fetch the complete documentation index at: https://docs.zapthinker.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Key Features

• Rule-Based Routing: Define rules to route messages to specific bots
• AI Classification: Automatic message categorization using LLM models
• Priority System: Control rule execution order
• Human Handoff: Seamlessly transfer conversations to human agents
• Session Management: Track active handoff sessions
• Conversation Notes: Add internal notes for agent context
• Conversation Summary: AI-generated summaries of chat history
• Routing Logs: Complete audit trail of routing decisions
• Statistics: Analytics on routing performance

​

How It Works

​

Message Routing Flow

1. Message Received: New message arrives from user
2. Rule Evaluation: System evaluates routing rules in priority order
3. Condition Matching: Checks keywords, AI categories, or custom logic
4. Bot Selection: Routes to the matched bot
5. Response Generation: Selected bot processes and responds
6. Logging: Decision logged for analytics

​

Human Handoff Flow

1. Handoff Trigger: User requests human agent or bot escalates
2. Session Creation: Handoff session created with conversation context
3. Agent Notification: Human agent receives notification
4. Agent Takes Over: Agent claims the conversation
5. Direct Communication: Messages bypass bots and go to agent
6. Session Close: Agent marks conversation as resolved

​

Routing Rules

​

Rule Structure

{
  "name": "Support Queries",
  "enabled": true,
  "priority": 1,
  "conditions": {
    "type": "keyword",
    "keywords": ["help", "support", "problem"],
    "matchType": "any"
  },
  "action": {
    "targetType": "bot",
    "targetId": "support-bot-123"
  }
}

​

Condition Types

​

Keyword Matching

• Contains: Message contains any/all keywords
• Exact Match: Message exactly matches keyword
• Regex: Advanced pattern matching

​

AI Classification

• Categories: Define custom categories (sales, support, billing, etc.)
• Confidence Threshold: Minimum confidence for classification
• Model Selection: Choose LLM model for classification

​

Time-Based

• Business Hours: Route to bots during business hours
• After Hours: Route to different bot or auto-responder

​

User-Based

• VIP Customers: Priority routing for important customers
• New Users: Special onboarding flow
• Returning Users: Context-aware routing

​

Human Handoff

​

Taking Over Conversations

1. Manual Takeover: Agent claims conversation from queue
2. Bot Escalation: Bot automatically escalates complex queries
3. User Request: User explicitly asks for human agent
4. Timeout: Conversation idle for too long

​

Handoff Features

​

Session Status

• Active: Agent is handling conversation
• Waiting: Waiting for agent to claim
• Resolved: Conversation completed
• Transferred: Moved to another agent

​

Conversation Context

• Full message history
• User information
• Previous bot interactions
• AI-generated summary

​

Internal Notes

• Customer context
• Issue details
• Resolution steps
• Follow-up requirements

​

Conversation Summary

• Key topics discussed
• User sentiment
• Issues raised
• Actions taken

​

Releasing Conversations

1. Add final notes
2. Mark as resolved
3. Release back to bot routing
4. Conversation history preserved

​

AI Classification

​

How It Works

1. Message Analysis: LLM analyzes message content
2. Category Matching: Compares against defined categories
3. Confidence Scoring: Assigns confidence to each category
4. Threshold Check: Only routes if confidence exceeds threshold
5. Fallback: Uses keyword matching if AI classification fails

​

Category Definition

{
  "categories": [
    {
      "name": "sales",
      "description": "Questions about products, pricing, or purchasing",
      "examples": ["How much does it cost?", "I want to buy"]
    },
    {
      "name": "support",
      "description": "Technical issues or help requests",
      "examples": ["It's not working", "I need help"]
    }
  ]
}

​

Supported Models

• Groq Models: Fast, cost-effective classification
• OpenAI GPT: High accuracy classification
• Custom Models: Integrate your own classification API

​

Routing Logs

• Timestamp: When decision was made
• Message Content: What triggered the routing
• Rules Evaluated: Which rules were checked
• Matched Rule: Which rule was selected
• Target Bot: Where message was routed
• Confidence: AI classification confidence (if applicable)

​

Log Queries

• Date range
• Specific bot
• Rule name
• User/conversation
• Success/failure status

​

Statistics

• Total Messages Routed: Volume over time
• Bot Distribution: Which bots receive most messages
• Rule Performance: Which rules match most often
• AI Accuracy: Classification confidence trends
• Handoff Metrics: Average resolution time, agent utilization
• Fallback Rate: How often default routing is used

​

Use Cases

​

Multi-Department Support

​

Tiered Support

​

Language Routing

​

Product-Specific Routing

​

VIP Customer Handling

​

Best Practices

1. Clear Categories: Define distinct, non-overlapping categories
2. Priority Order: Set priorities to handle edge cases
3. Testing: Use test mode to validate rules before deployment
4. Monitoring: Regularly review routing logs and statistics
5. Fallback Strategy: Always have a default route
6. Agent Training: Ensure agents understand handoff workflow
7. Response Time: Set expectations for human response times
8. Conversation Notes: Encourage detailed note-taking

​

Testing Rules

{
  "message": "I need help with my order",
  "userId": "user-123"
}

• Which rules matched
• Which bot would be selected
• Confidence scores
• Execution path

​

Advanced Features

​

Context Stickiness

• Configurable timeout
• Explicit context reset
• Cross-session memory

​

Conditional Routing

• Multiple keyword groups
• Combined AI + keyword matching
• Time-based overrides

​

A/B Testing

• Split traffic between bots
• Compare performance metrics
• Gradual rollout of new rules

​

Webhook Integration

• CRM updates
• Analytics tracking
• Custom notifications

​

Getting Started

1. Define your routing categories
2. Create routing rules with priorities
3. Test rules with sample messages
4. Deploy to production
5. Monitor logs and statistics
6. Refine rules based on performance
7. Configure human handoff workflow
8. Train agents on handoff system