# AI Chatbot Guide

**Last Updated**: 2026-01-18

Learn how to configure and optimize AI-powered chatbot for WhatsApp conversations.

## Overview

The AI Chatbot uses Large Language Models (LLM) to provide intelligent, context-aware responses. Unlike rule-based automation, AI can:

- Understand natural language and intent
- Maintain context across turns
- Generate dynamic responses
- Handle unexpected questions
- Learn from conversation patterns

## Supported LLM Providers

| Provider | Model | Cost (per 1M tokens) | Latency |
|----------|-------|----------------------|---------|
| **OpenAI** | GPT-4-Turbo | $10 input / $30 output | ~2s |
| **OpenAI** | GPT-3.5-Turbo | $0.50 input / $1.50 output | ~1s |
| **Azure OpenAI** | GPT-4 | Custom pricing | ~2s |
| **Google Gemini** | Gemini Pro | $0.50 input / $1.50 output | ~1.5s |

**Recommendation**: Start with GPT-4-Turbo for quality, optimize to GPT-3.5 for simple queries.

## Creating an AI Agent

### Via API

```bash
POST /api/v1/whatsapp/ai-agents
Content-Type: application/json

{
  "shopId": "shop-guid",
  "agentName": "Customer Support AI",
  "personality": {
    "tone": "friendly",
    "language": "vietnamese",
    "constraints": [
      "Do NOT provide pricing without checking current catalog",
      "Do NOT process orders directly",
      "Always offer to connect to human agent for complex issues"
    ],
    "promptTemplate": "You are a helpful customer service agent for {shop_name}."
  },
  "knowledgeBaseId": "kb-guid",
  "isActive": false
}
```

### Response

```json
{
  "success": true,
  "data": {
    "agentId": "agent-guid",
    "agentName": "Customer Support AI",
    "createdAt": "2026-01-18T10:00:00Z"
  }
}
```

## Personality Configuration

### Tone Options

**Friendly** (Recommended for retail)
```
"You are a warm and enthusiastic assistant. Use emojis occasionally. 
Address customers in a casual but respectful manner."
```

**Professional** (Recommended for B2B)
```
"You are a professional business assistant. Use formal language.
Provide detailed, accurate information. Avoid emojis."
```

**Casual** (Recommended for young audience)
```
"You are a chill and relatable assistant. Use informal language.
Keep responses concise. Use trending slang when appropriate."
```

### Language

Set primary language:
```json
{
  "language": "vietnamese",
  "fallbackLanguage": "english"
}
```

The AI will:
1. Respond in Vietnamese by default
2. Switch to English if customer uses English
3. Handle mixed language (Vienglish)

### Constraints

Define what AI should NOT do:

```json
{
  "constraints": [
    "Never share personal information of other customers",
    "Do not promise discounts or refunds without approval",
    "Do not process financial transactions",
    "Always verify order numbers before providing status",
    "Redirect sensitive issues to human agent"
  ]
}
```

## Prompt Template

### Basic Template

```
You are a customer service agent for {shop_name}.

Role: Help customers with product inquiries, order tracking, and general questions.

Context:
- Customer name: {customer_name}
- Customer tags: {customer_tags}
- Previous purchases: {purchase_count}

Knowledge Base:
{knowledge_base_content}

Instructions:
- Be helpful and concise
- If unsure, say so and offer to connect to human agent
- Never make up information
- Always confirm before taking actions

Current date: {current_date}
Current time: {current_time}
```

### Advanced Template with Few-Shot Examples

```
You are a customer service agent for {shop_name}.

Here are examples of good responses:

Customer: "Do you have iPhone 15 in stock?"
Agent: "Let me check our inventory for you! 📱 Could you specify which color and storage capacity you're looking for? We typically carry Space Black, Blue, and Pink in 128GB, 256GB, and 512GB."

Customer: "Where is my order?"
Agent: "I'll help you track that! Could you please share your order number? It should look like #12345. You can find it in your confirmation email."

Customer: "This product is broken"
Agent: "I'm sorry to hear that! 😞 To help you quickly, I'll connect you with our support team who can process a return or replacement. Please hold for a moment."

Now respond to the customer's message:
{customer_message}
```

## Knowledge Base Integration

### Creating Knowledge Base

Upload documents (FAQ, product catalogs, policies):

```bash
POST /api/v1/whatsapp/knowledge-bases
Content-Type: application/json

{
  "shopId": "shop-guid",
  "name": "Customer Support KB",
  "documents": [
    {
      "title": "Shipping Policy",
      "content": "We offer free shipping on orders over 500,000 VNĐ..."
    },
    {
      "title": "Return Policy",
      "content": "You can return items within 30 days..."
    }
  ]
}
```

### Link to AI Agent

```bash
PUT /api/v1/whatsapp/ai-agents/{agentId}
Content-Type: application/json

{
  "knowledgeBaseId": "kb-guid"
}
```

The AI will automatically reference KB when responding.

## Context Management

### Conversation History

AI automatically includes last 10 messages for context:

```json
{
  "messages": [
    {"role": "user", "content": "Do you sell laptops?"},
    {"role": "assistant", "content": "Yes! We have various laptop models..."},
    {"role": "user", "content": "What about gaming laptops?"}
  ]
}
```

The AI understands "gaming laptops" refers to the laptop discussion.

### Custom Context Variables

Inject dynamic context:

```json
{
  "contextVariables": {
    "customer_tier": "vip",
    "cart_value": "2500000",
    "last_purchase_date": "2026-01-10",
    "preferred_category": "electronics"
  }
}
```

Use in prompt:
```
Customer tier: {customer_tier}
Cart value: {cart_value} VNĐ

Provide personalized recommendations based on their preference for {preferred_category}.
```

## Response Generation

### API Request

When customer sends a message, AI agent automatically generates response:

```
Customer: "Tôi muốn mua áo thun size L"

[Internal AI Pipeline]
1. Load conversation history
2. Fetch customer profile (tags, custom fields)
3. Query knowledge base for relevant info
4. Build prompt with context
5. Call OpenAI API
6. Parse response
7. Apply safety filters
8. Send to customer
```

### Streaming Responses

For long responses, enable streaming:

```bash
PUT /api/v1/whatsapp/ai-agents/{agentId}
Content-Type: application/json

{
  "streamingEnabled": true,
  "streamingChunkSize": 500
}
```

Sends message in chunks (smoother UX for long answers).

## Fallback Handling

### When AI Should Escalate

Configure conditions to transfer to human:

```json
{
  "fallbackConditions": [
    {"type": "low_confidence", "threshold": 0.7},
    {"type": "contains_keywords", "keywords": ["complaint", "refund", "speak to manager"]},
    {"type": "conversation_length", "maxTurns": 10},
    {"type": "sentiment", "value": "negative"}
  ]
}
```

### Fallback Message

Custom handoff message:

```json
{
  "fallbackMessage": "I want to make sure you get the best help! Let me connect you with one of our specialists who can assist you further. Please hold on... 👨‍💼"
}
```

## Cost Optimization

### 1. Intent Classification

Before calling expensive GPT-4, use cheap classifier:

```json
{
  "intentClassifier": {
    "enabled": true,
    "model": "gpt-3.5-turbo",
    "categories": ["faq", "product_inquiry", "order_tracking", "complaint", "other"]
  }
}
```

Route to GPT-3.5 for FAQs, GPT-4 for complex queries.

### 2. Response Caching

Cache common questions:

```json
{
  "caching": {
    "enabled": true,
    "ttl": 3600,
    "similarityThreshold": 0.95
  }
}
```

If customer asks "Do you ship to Hanoi?" and cache has answer for similar question → return cached response (no API call = $0).

### 3. Token Limits

Set max tokens to avoid runaway costs:

```json
{
  "tokenLimits": {
    "maxPromptTokens": 2000,
    "maxCompletionTokens": 500
  }
}
```

### 4. Budget Alerts

Set spending limits:

```bash
POST /api/v1/whatsapp/ai-agents/{agentId}/budget
Content-Type: application/json

{
  "dailyBudgetUsd": 10.00,
  "monthlyBudgetUsd": 200.00,
  "alertThreshold": 0.8
}
```

Receive alert at 80% budget usage.

## Safety & Moderation

### Content Filtering

Enable OpenAI moderation:

```json
{
  "moderation": {
    "enabled": true,
    "blockCategories": ["hate", "harassment", "violence", "self-harm"]
  }
}
```

Suspicious content is blocked before responding.

### PII Protection

Automatically redact sensitive data:

```json
{
  "piiProtection": {
    "enabled": true,
    "redactTypes": ["credit_card", "ssn", "email", "phone"]
  }
}
```

Logs will show `[REDACTED]` instead of actual values.

## Testing

### Test Mode

Simulate AI responses without sending to customer:

```bash
POST /api/v1/whatsapp/ai-agents/{agentId}/test
Content-Type: application/json

{
  "conversationHistory": [
    {"role": "user", "content": "Laptop nào tốt nhất?"}
  ],
  "customerContext": {
    "name": "Nguyễn Văn A",
    "tags": ["vip"]
  }
}
```

**Response**:
```json
{
  "generatedResponse": "Xin chào Nguyễn Văn A! 👋 ...",
  "tokensUsed": {
    "prompt": 450,
    "completion": 120,
    "total": 570
  },
  "estimatedCost": 0.0154,
  "latencyMs": 1850
}
```

### A/B Testing

Compare prompts:

- Agent A: Personality = "friendly"
- Agent B: Personality = "professional"

Route 50% traffic to each, measure:
- Customer satisfaction (implicit from conversation length)
- Resolution rate
- Cost per conversation

## Monitoring

### Metrics Dashboard

Track:
- **Token usage** (daily/monthly)
- **Cost** (per conversation, total)
- **Latency** (p50, p95, p99)
- **Fallback rate** (how often AI escalates)
- **Customer satisfaction** (thumbs up/down)

### Conversation Quality

Review random samples:

```bash
GET /api/v1/whatsapp/ai-agents/{agentId}/conversations/sample?count=10
```

Look for:
- Hallucinations (AI making up info)
- Off-brand tone
- Failure to escalate when needed

## Hybrid Approach

Combine automation + AI for best results:

### Strategy 1: Automation First

1. Incoming message → Check automation flows
2. If no match → Route to AI
3. AI response → Send to customer

### Strategy 2: AI for Classification

1. AI classifies intent
2. Route to appropriate automation flow
3. Fallback to AI if no flow matches

### Strategy 3: Time-Based

- Business hours (9 AM - 6 PM): AI enabled
- After hours: Automation only (simple FAQ)

## Best Practices

1. **Start with narrow scope** - Train AI on specific categories first
2. **Review regularly** - Sample conversations weekly
3. **Update knowledge base** - Keep product/policy info current
4. **Set clear constraints** - Define what AI can/cannot do
5. **Monitor costs** - Set budgets and alerts
6. **Human in the loop** - Always offer escalation path
7. **Optimize prompts** - Iterate based on performance
8. **Use examples** - Few-shot learning improves quality

## Troubleshooting

### AI Responses Are Generic

**Solution**: Add more context and examples to prompt template.

### AI Providing Wrong Information

**Solution**: 
1. Update knowledge base
2. Add constraint in prompt
3. Review and retrain

### High Costs

**Solution**:
1. Enable intent classification
2. Reduce max tokens
3. Use GPT-3.5 when possible
4. Implement caching

### Slow Responses

**Solution**:
1. Reduce context window (fewer history messages)
2. Enable streaming
3. Use faster model (GPT-3.5)

## Next Steps

- [API Documentation](API.md) - AI agent API reference
- [Automation Guide](AUTOMATION_GUIDE.md) - Combine with automation
- [Architecture](ARCHITECTURE.md) - Understanding AI pipeline

## Resources

- [OpenAI Best Practices](https://platform.openai.com/docs/guides/prompt-engineering)
- [Prompt Engineering Guide](https://www.promptingguide.ai/)
- [LLM Cost Calculator](https://docsbot.ai/tools/gpt-openai-api-pricing-calculator)
