Beginner Guide to Building AI Chatbots with Flask

Flask remains a strong choice for learning chatbot development because it exposes the essentials: HTTP routes, JSON requests, templates, and application configuration. In 2026, a useful beginner project is not a rule-based demo or a fragile Socket.IO prototype. It is a small web application that sends a user message to a hosted or local language model, returns a response, and handles secrets, errors, and basic safety correctly.

This guide builds that foundation. It is suitable for students, early-stage founders, and developers creating support, education, internal knowledge, or multilingual products for Indian users. If you are choosing a project for your portfolio, pair this build with the ideas in machine learning portfolio projects for beginners in India and document your architecture, evaluation results, and deployment decisions.

What you will build

The application will include:

A Flask server with a /chat JSON endpoint.
A simple browser interface served from Flask.
A model-provider call kept on the server, so the API key is never exposed in JavaScript.
Short conversation history sent with each request.
Input validation, timeouts, error handling, and a basic health check.

You can connect the backend to a commercial model API, an organisation's internal inference service, or a local model. Flask is the web layer; it does not provide intelligence by itself.

Prerequisites and project setup

Install Python 3.11 or newer, Git, and a code editor. Create an isolated environment rather than installing packages globally:

mkdir flask-chatbot
cd flask-chatbot
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows PowerShell
.venv\\Scripts\\Activate.ps1
pip install Flask python-dotenv requests

Create this structure:

flask-chatbot/
├── app.py
├── .env
├── .gitignore
└── templates/
    └── index.html

Put the model provider's credential in .env and add .env to .gitignore:

MODEL_API_KEY=replace-with-your-key
MODEL_API_URL=https://your-provider.example/v1/chat/completions

Do not commit credentials, paste them into frontend code, or log complete user conversations. For a public Indian product, also decide where data is stored, who can access it, and whether sensitive information is sent to a third-party provider.

Create the Flask backend

Create app.py:

import os
from flask import Flask, jsonify, render_template, request
from dotenv import load_dotenv
import requests

load_dotenv()
app = Flask(__name__)

MODEL_API_URL = os.getenv("MODEL_API_URL")
MODEL_API_KEY = os.getenv("MODEL_API_KEY")

@app.get("/")
def home():
    return render_template("index.html")

@app.get("/health")
def health():
    return {"status": "ok"}

@app.post("/chat")
def chat():
    data = request.get_json(silent=True) or {}
    messages = data.get("messages", [])

    if not isinstance(messages, list) or not messages:
        return jsonify({"error": "Send at least one message."}), 400

    messages = messages[-10:]
    if any(not isinstance(item, dict) for item in messages):
        return jsonify({"error": "Invalid message format."}), 400

    payload = {
        "model": "your-model-name",
        "messages": [
            {"role": "system", "content": "You are a concise, helpful assistant."},
            *messages
        ],
        "temperature": 0.3
    }

    try:
        response = requests.post(
            MODEL_API_URL,
            json=payload,
            headers={"Authorization": f"Bearer {MODEL_API_KEY}"},
            timeout=30
        )
        response.raise_for_status()
        result = response.json()
        answer = result["choices"][0]["message"]["content"]
        return jsonify({"answer": answer})
    except (requests.RequestException, KeyError, IndexError, TypeError):
        app.logger.exception("Model request failed")
        return jsonify({"error": "The assistant is temporarily unavailable."}), 502

if __name__ == "__main__":
    app.run(debug=True)

Model APIs use different URLs and response formats, so replace MODEL_API_URL, the model name, and the response extraction path with your provider's documentation. Never enable debug=True on a public deployment.

The endpoint limits history to ten messages to control latency and cost. In a production application, add authentication, per-user rate limits, request-size limits, structured logging, and a persistent conversation store. If your application grows into multiple model calls or tool-using workers, study patterns for building distributed systems with AI agents before adding complexity.

Build the browser interface

Create templates/index.html:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Flask AI Chatbot</title>
</head>
<body>
  <main>
    <h1>Ask the assistant</h1>
    <div id="messages" aria-live="polite"></div>
    <form id="chat-form">
      <input id="prompt" autocomplete="off" required maxlength="1000">
      <button type="submit">Send</button>
    </form>
  </main>
  <script>
    const history = [];
    const messages = document.querySelector('#messages');
    const form = document.querySelector('#chat-form');
    const prompt = document.querySelector('#prompt');

    function addMessage(label, text) {
      const p = document.createElement('p');
      p.textContent = `${label}: ${text}`;
      messages.appendChild(p);
    }

    form.addEventListener('submit', async (event) => {
      event.preventDefault();
      const text = prompt.value.trim();
      if (!text) return;
      history.push({role: 'user', content: text});
      addMessage('You', text);
      prompt.value = '';

      try {
        const response = await fetch('/chat', {
          method: 'POST',
          headers: {'Content-Type': 'application/json'},
          body: JSON.stringify({messages: history})
        });
        const data = await response.json();
        if (!response.ok) throw new Error(data.error || 'Request failed');
        history.push({role: 'assistant', content: data.answer});
        addMessage('Assistant', data.answer);
      } catch (error) {
        addMessage('Error', error.message);
      }
    });
  </script>
</body>
</html>

Use textContent, not innerHTML, when displaying model output. That prevents a response containing HTML or JavaScript from being injected into the page. Add loading states, a disabled submit button, Markdown sanitisation, and accessible keyboard behaviour before showing the interface to real users.

Run and test locally

Start the development server:

python app.py

Open http://127.0.0.1:5000. Test the health endpoint and chatbot endpoint separately:

curl http://127.0.0.1:5000/health
curl -X POST http://127.0.0.1:5000/chat \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"Explain photosynthesis simply."}]}'

Test more than whether the bot responds. Create a small evaluation set covering factual questions, ambiguous prompts, empty input, long input, prompt injection, Hindi or another target language, and requests involving personal data. Record latency, failure rate, token usage, and answer quality. For applications aimed at India's next billion users, prioritise mobile layouts, low-bandwidth behaviour, readable language, and language support rather than adding features prematurely. The broader product considerations are covered in building AI apps for the next billion users in India.

Deployment and production checklist

A Flask app can run behind Gunicorn or another WSGI server. Set production environment variables through your hosting platform and keep secrets outside the repository. Before launch:

Run with debug=False and HTTPS.
Add authentication and per-user rate limiting.
Set model and request timeouts.
Redact secrets and sensitive text from logs.
Store only the conversation data you genuinely need.
Add a clear privacy notice and a way to report harmful output.
Monitor cost, latency, error rates, and provider outages.
Pin dependencies and scan them for vulnerabilities.
Add automated tests for /health, invalid JSON, provider failures, and prompt length.

For a student or early-stage project, a small deployed demo with a clear README, architecture diagram, test cases, and known limitations is more valuable than a large codebase. You can extend it with retrieval-augmented generation, feedback buttons, citations, streaming responses, or a local model after the basic request path is reliable. Open-source components can also be evaluated through best open source AI projects for beginners.

Common mistakes to avoid

Calling the model directly from the browser: this exposes your key and makes abuse easy.
Treating model output as fact: show sources or qualify answers in high-stakes domains.
Sending unlimited history: costs and latency rise quickly.
Using Socket.IO immediately: ordinary fetch requests are simpler for a first build; add streaming or websockets only when the product needs them.
Ignoring Indian language and privacy needs: validate with real users and realistic data, not only English test prompts.
Confusing a demo with a product: reliability, moderation, observability, and support matter as much as the model.

Next steps

Once this chatbot works, separate the UI, model adapter, and conversation service so each can be tested independently. Then add retrieval from trusted documents, a feedback loop, and an evaluation dataset. If you are building for education, public services, or small businesses in India, start with one narrow workflow and measure whether the chatbot actually reduces effort or improves access.

A well-scoped Flask chatbot is also a credible starting point for an open-source AI project for students in India, especially when the repository includes setup instructions, responsible-use notes, and reproducible tests.

Apply for AI Grants India