Project: Build a Customer Support Chatbot with Claude API

Customer support chatbots have a well-earned poor reputation. They fail to understand questions, give irrelevant answers from a FAQ list, and ultimately frustrate customers into demanding a human agent. The difference between a bad support bot and a useful one is not the technology — it is the design of the knowledge base, the system prompt, and the escalation logic.

Claude's conversational ability, combined with a well-structured knowledge base and clear behavioural instructions, produces a support bot that genuinely helps. This project builds a complete customer support chatbot with a static knowledge base, multi-turn conversation management, prompt caching for cost efficiency, and a clear escalation path to human support.

What We Are Building

The chatbot handles these core responsibilities:

Answers questions from a company knowledge base — products, policies, account management, troubleshooting
Maintains conversation context across multiple turns — no need for users to repeat themselves
Recognises when to escalate — complex complaints, billing disputes, and repeated-failure scenarios get handed to a human
Handles out-of-scope questions gracefully — redirects rather than guessing or confabulating

Prerequisites

Python 3.9 or later
pip install anthropic
An Anthropic API key set as ANTHROPIC_API_KEY

The Knowledge Base

The knowledge base is the most important component of a support bot. Claude should answer only from this content — not from its general training knowledge about your industry. Define it clearly in your system prompt.

python

KNOWLEDGE_BASE = """
=== MERIDIAN CLOUD SERVICES — SUPPORT KNOWLEDGE BASE ===

PRODUCTS AND PLANS:
- Starter Plan: £29/month. 5 users. 100 GB storage. Email support only.
- Professional Plan: £99/month. 25 users. 1 TB storage. Priority email and chat support.
- Enterprise Plan: Custom pricing. Unlimited users. Custom storage. Dedicated support manager.

BILLING AND PAYMENTS:
- Billing cycle is monthly, charged on the 1st of each month.
- Payment methods accepted: Visa, Mastercard, American Express, BACS transfer.
- Invoices are emailed to the account billing email within 24 hours of charge.
- Refunds are available within 14 days of charge for annual plans. Monthly plans are non-refundable.
- To update payment details, go to Account Settings → Billing → Payment Methods.

ACCOUNT MANAGEMENT:
- Password reset: Account Settings → Security → Reset Password, or use the login page "Forgot Password" link.
- Adding users: Account Settings → Team → Invite Users. Admin role required.
- Changing plan: Account Settings → Subscription → Change Plan. Takes effect at next billing date.
- Cancellation: Account Settings → Subscription → Cancel. Data retained for 30 days after cancellation.

TECHNICAL SUPPORT:
- Service status: status.meridiancloud.com
- Supported browsers: Chrome 108+, Firefox 108+, Safari 16+, Edge 108+.
- Mobile app available for iOS 15+ and Android 10+.
- API documentation: docs.meridiancloud.com
- For persistent technical issues, collect: browser console errors, network tab HAR file, account ID.

KNOWN ISSUES (as of this knowledge base update):
- Export to Excel feature may show a loading spinner for up to 2 minutes on large datasets — this is expected behaviour.
- Safari users may experience intermittent login issues — recommended workaround: clear browser cache and cookies.
"""

The System Prompt

python

def build_system_prompt(knowledge_base: str) -> str:
    return f"""You are a helpful customer support agent for Meridian Cloud Services.
Your name is Alex. You are helpful, professional, and concise.

KNOWLEDGE BASE:
{knowledge_base}

BEHAVIOUR RULES:
1. Answer questions using ONLY information in the knowledge base above.
2. If the answer is not in the knowledge base, say: "I don't have information on that in my support resources. I can connect you with our team for more help."
3. Do not make up policies, prices, or features that are not stated above.
4. Keep answers focused — 2-4 sentences for most queries.
5. For billing disputes, account security concerns, or complex complaints: say "This is something I want to make sure gets handled perfectly — let me connect you with a specialist."
6. If the user expresses frustration or has repeated the same problem more than once: acknowledge their frustration first, then respond.
7. Never ask for passwords, payment card numbers, or full account credentials.

ESCALATION TRIGGER PHRASES — if the user says any of these, offer to escalate:
- "I want to speak to a human"
- "This is unacceptable" / "I want to make a complaint"
- "My account has been charged incorrectly" / "My card was charged without permission"
- "I've been trying to fix this for days"
"""

The Complete Chatbot

python

import anthropic
import json

client = anthropic.Anthropic()

KNOWLEDGE_BASE = """[Your knowledge base content here]"""

ESCALATION_KEYWORDS = [
    "speak to a human", "real person", "manager", "complaint",
    "unacceptable", "charged incorrectly", "days trying", "this is ridiculous"
]

class SupportChatbot:
    def __init__(self):
        self.conversation_history = []
        self.escalation_triggered = False
        self.system_prompt = build_system_prompt(KNOWLEDGE_BASE)
    
    def should_escalate(self, user_message: str) -> bool:
        """Check if the user's message triggers escalation."""
        message_lower = user_message.lower()
        return any(keyword in message_lower for keyword in ESCALATION_KEYWORDS)
    
    def chat(self, user_message: str) -> str:
        """Process one turn of the conversation."""
        
        # Check for escalation triggers
        if self.should_escalate(user_message):
            self.escalation_triggered = True
        
        # Add user message to history
        self.conversation_history.append({
            "role": "user",
            "content": user_message
        })
        
        # Build system with cached knowledge base for cost efficiency
        system_messages = [
            {
                "type": "text",
                "text": self.system_prompt,
                "cache_control": {"type": "ephemeral"}  # Cache the large system prompt
            }
        ]
        
        # Add escalation note if triggered
        if self.escalation_triggered:
            system_messages.append({
                "type": "text",
                "text": "\n\n[SYSTEM NOTE: Escalation triggered. Offer to connect the user with a human specialist in your response.]"
            })
        
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            system=system_messages,
            messages=self.conversation_history
        )
        
        assistant_message = response.content[0].text
        
        # Add assistant response to history
        self.conversation_history.append({
            "role": "assistant",
            "content": assistant_message
        })
        
        return assistant_message
    
    def get_conversation_summary(self) -> str:
        """Produce a summary for handoff to a human agent."""
        if len(self.conversation_history) < 2:
            return "No conversation to summarise."
        
        # Format conversation for summary
        conv_text = "\n".join([
            f"{msg['role'].upper()}: {msg['content']}"
            for msg in self.conversation_history
        ])
        
        response = client.messages.create(
            model="claude-haiku-4-5",  # Use cheaper model for internal summaries
            max_tokens=512,
            messages=[
                {
                    "role": "user",
                    "content": f"""Summarise this customer support conversation for handoff to a human agent.
Include: the customer's issue, what was tried, and why escalation is needed.
Keep it under 100 words.

CONVERSATION:
{conv_text}"""
                }
            ]
        )
        
        return response.content[0].text
    
    def reset(self):
        """Reset conversation for a new user session."""
        self.conversation_history = []
        self.escalation_triggered = False


# ─── Interactive Demo ─────────────────────────────────────────────────────────

def run_demo():
    bot = SupportChatbot()
    
    print("Meridian Cloud Support — Alex is here to help.")
    print("Type 'quit' to exit, 'summary' to see the handoff summary.\n")
    
    while True:
        user_input = input("You: ").strip()
        
        if not user_input:
            continue
        
        if user_input.lower() == "quit":
            print("\nSession ended.")
            break
        
        if user_input.lower() == "summary":
            print("\n--- HANDOFF SUMMARY ---")
            print(bot.get_conversation_summary())
            print("--- END SUMMARY ---\n")
            continue
        
        response = bot.chat(user_input)
        print(f"\nAlex: {response}\n")
        
        if bot.escalation_triggered:
            print("[SYSTEM: Escalation flag active — prepare for human handoff if user accepts]\n")


if __name__ == "__main__":
    run_demo()

Extending the Project

FastAPI endpoint: Wrap in an API server so any frontend (React, Vue, or a third-party chat widget) can connect to it
Session storage: Store conversation history in Redis or PostgreSQL keyed by session ID to support concurrent users and persistent sessions
Dynamic knowledge base: Load the knowledge base from a database or CMS so it can be updated without redeploying the application
WebSocket streaming: Use the Claude streaming API to start showing the response character by character, reducing perceived latency for users
Analytics: Log every conversation with metadata (escalation rate, topic classification, resolution status) to identify knowledge gaps

Prompt Caching Makes Support Bots Much Cheaper

The knowledge base system prompt in this project is large — potentially 10,000+ tokens for a comprehensive product. By adding cache_control to the system prompt, you pay full input token cost only on the first request of each cache period (5 minutes minimum). All subsequent requests reuse the cached version at 10% of the cost. For a high-volume support bot handling thousands of conversations per day, this is a significant cost difference.

Summary

A well-designed support chatbot has three success factors: a high-quality knowledge base, clear behavioural boundaries, and a reliable escalation path. Claude handles the conversational intelligence — you provide the domain knowledge and the rules.

Use cache_control on the system prompt to reduce costs at scale
Maintain full conversation history so Claude has context for follow-up questions
Define explicit escalation triggers rather than relying on Claude to judge when to escalate
Use a cheaper model (Haiku) for internal tasks like summary generation

Next project: Project: Build an Automated Meeting Notes Summariser.

This post is part of the Anthropic AI Tutorial Series. Previous post: Project: Build a Smart CV / Resume Analyser with Claude.