Intelligent Conversational Engine (ICE)
The conversation engine uses a 3-step LLM pipeline to generate context-aware replies to incoming social media messages. It supports auto-reply, escalation, human review, and A/B experiments on reply strategies.
Architecture
Pipeline Steps
Step 1: Intent Classification
Service: intent-classifier.service.ts
Analyzes the incoming message to determine:
| Output | Description | Examples |
|---|---|---|
| Intent type | Category of the message | question, complaint, praise, purchase_intent, support_request, spam |
| Sentiment | Emotional tone | positive, negative, neutral |
| Urgency | How time-sensitive | low, medium, high, critical |
| Auto-reply decision | Whether to auto-reply or escalate | Boolean based on bot config |
const classification = await intentClassifier.classify(message, botConfig);
// { intent: 'purchase_intent', sentiment: 'positive', urgency: 'medium', shouldAutoReply: true }
Uses Gemini with temperature 0.2 for deterministic, consistent classification.
Step 2: Context Building
Service: context-builder.service.ts
Gathers all relevant context for generating an informed reply:
| Context Source | Data | Model |
|---|---|---|
| Audience profile | Name, platform, engagement score, tags | AudienceNode |
| Conversation history | Recent messages in the thread | ConversationMessage |
| Memory (3 tiers) | Short-term, medium-term, long-term memories | ConversationMemory |
| Product information | If e-commerce connected, relevant products | EcommerceProduct |
| Brand voice | Tone, style, vocabulary guidelines | BrandVoice |
| Bot configuration | Auto-reply intents, confidence threshold, response style | BotConfiguration |
const context = await contextBuilder.build(threadId, audienceNodeId, workspaceId);
// { audienceProfile, conversationHistory, memory, products, brandVoice, botConfig }
Step 3: Response Generation
Service: conversation-brain.service.ts
Generates the reply using the classified intent and assembled context:
const reply = await conversationBrain.generateReply({
intent: classification,
context: assembledContext,
brandVoice: workspace.brandVoice,
language: thread.language,
});
// { text: "Thank you for your interest! ...", confidence: 0.92 }
Uses Gemini with temperature 0.6 for natural but controlled responses.
Core Service Functions
conversation-engine.service.ts orchestrates the full pipeline:
| Function | Description |
|---|---|
processIncomingMessage() | Main entry point -- runs the full 3-step pipeline |
listThreads() | List conversation threads (filtered, paginated) |
getThread() | Get a single thread with messages |
getThreadMessages() | Get messages for a thread |
sendAgentReply() | Human agent sends a manual reply |
resolveThread() | Mark thread as resolved |
reopenThread() | Reopen a resolved thread |
toggleThreadBot() | Enable/disable bot for a specific thread |
getBotConfig() | Get workspace bot configuration |
updateBotConfig() | Update workspace bot configuration |
getInboxStats() | Get inbox statistics (open, resolved, escalated counts) |
suggestReply() | Generate an AI-suggested reply without auto-sending |
API Endpoints
All ICE routes are under /api/v1/ice:
| Endpoint | Method | Function | Min Role |
|---|---|---|---|
/api/v1/ice/threads | GET | listThreads() | EDITOR |
/api/v1/ice/threads/:id/messages | GET | getThreadMessages() | EDITOR |
/api/v1/ice/reply | POST | sendAgentReply() | EDITOR |
/api/v1/ice/ai-suggest | POST | suggestReply() | EDITOR |
/api/v1/ice/threads/:id/resolve | PATCH | resolveThread() | EDITOR |
/api/v1/ice/threads/:id/reopen | PATCH | reopenThread() | EDITOR |
/api/v1/ice/threads/:id/bot-toggle | PATCH | toggleThreadBot() | ADMIN |
/api/v1/ice/bot-config | GET | getBotConfig() | ADMIN |
/api/v1/ice/bot-config | PATCH | updateBotConfig() | ADMIN |
/api/v1/ice/escalation-rules | CRUD | Escalation rule management | ADMIN |
/api/v1/ice/escalations | GET | List escalation records | EDITOR |
/api/v1/ice/experiments | GET | Reply experiment results | VIEWER |
/api/v1/ice/stats | GET | getInboxStats() | VIEWER |
Bot Configuration
Each workspace configures its bot via the BotConfiguration model:
| Setting | Description | Default |
|---|---|---|
enabled | Master switch for auto-reply | false |
autoReplyIntents | Which intents to auto-reply to | ['question', 'praise'] |
confidenceThreshold | Minimum confidence to auto-send | 0.85 |
responseStyle | Casual, professional, friendly, etc. | 'professional' |
maxAutoRepliesPerThread | Limit auto-replies before escalating | 3 |
businessHoursOnly | Only auto-reply during business hours | false |
Escalation Rules
Defined via EscalationRule model, evaluated during Step 1:
| Condition Type | Example | Action |
|---|---|---|
| Intent match | intent == 'complaint' | Escalate to support team |
| Sentiment | sentiment == 'negative' | Escalate to manager |
| Urgency | urgency == 'critical' | Immediate escalation |
| Keyword match | Message contains "refund" | Escalate to billing |
| Repeated contact | Same person > 3 unresolved threads | Escalate to senior agent |
Reply Experiments
The ReplyExperiment model enables A/B testing of reply strategies:
Related Queues
| Queue | Purpose | Trigger |
|---|---|---|
ice-process | Process incoming messages through the 3-step pipeline | Message webhook |
ice-escalation | Route escalated threads to human agents | Escalation rule match |
ice-experiment-eval | Evaluate experiment results after duration elapses | Timer |
Cross-Reference
- Memory System -- 3-tier memory details
- Gemini API -- underlying AI model
- Prompt Templates -- prompt engineering
- Queue System -- ICE queue processing
- Services -- conversation service listing