How to Build an AI Chatbot With Dify: Step-by-Step Guide (2026)

Dify AI Chatbot

TL;DR

Dify is an open-source LLM application platform that lets you build AI chatbots, knowledge bases, and AI workflows without writing code. In this guide you will install Dify with Docker Compose, connect it to OpenAI or Claude, upload documents to a knowledge base, and embed a working chatbot on a website — all in about 30 minutes.

What Is Dify?

Dify is a visual development platform for building applications powered by large language models (LLMs). Think of it as WordPress for AI apps. It provides a drag-and-drop prompt orchestration interface, a built-in RAG (Retrieval-Augmented Generation) engine, and ready-to-use chatbot widgets.

Key capabilities include:

Chatbot & Agent apps — Build conversational bots with custom system prompts, tools, and knowledge retrieval
Workflow orchestration — Chain together LLM calls, code execution, HTTP requests, and conditional logic on a visual canvas
Knowledge base — Upload documents (PDF, DOCX, TXT, Markdown, web pages) and let the AI answer questions using your content
Model flexibility — Connect OpenAI, Anthropic Claude, Azure OpenAI, local Ollama models, or any OpenAI-compatible API
APIs & embedding — Every app exposes a REST API and can be embedded in websites with a single script tag

Dify comes in two editions: Community Edition (self-hosted, free) and Cloud (hosted by Dify, with a generous free tier).

Prerequisites

Before you start, make sure you have:

Docker Desktop installed (version 20.10 or later). If you do not have it, download from the Docker website and follow the install wizard. Docker is the container runtime that Dify runs on.
At least 4 GB of RAM available for Docker. On Windows or Mac, adjust this in Docker Desktop Settings under Resources.
An API key from at least one LLM provider. For this guide we will use OpenAI, but Claude or a local Ollama instance works too.
Git installed if you plan to clone the repository (optional — you can also download the ZIP).

Installation: Docker Compose vs Cloud

Option 1: Self-Hosted with Docker Compose (Recommended for Learning)

This gives you full control and zero usage limits. Open a terminal and run:

# Clone the Dify repository
git clone https://github.com/langgenius/dify.git
cd dify/docker

# Copy the example environment file
cp .env.example .env

# Start all services
docker compose up -d

After a minute or two, open your browser and go to http://localhost:3000. You will see the Dify setup wizard.

The .env file contains important settings. Open it in a text editor and look for these variables:

# Choose your default model provider
# Options: openai, azure_openai, anthropic, local, etc.
DEFAULT_LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here

# Required for embedding (for knowledge base)
VECTOR_STORE=weaviate

Set your API keys here so you do not have to enter them in the UI every time.

Option 2: Dify Cloud

Go to cloud.dify.ai and sign up with email or Google. You get 200 free OpenAI calls per month and can add your own API key for unlimited usage. The Cloud edition removes the Docker overhead but gives you less control over data privacy.

Comparison: Dify vs Alternatives

Feature	Dify	Traditional Coding	LangChain	Botpress
Coding required	No	Yes (Python/JS)	Yes (Python/JS)	No
Visual workflow builder	Yes	No	No	Yes (flow-based)
Built-in RAG	Yes (upload docs)	Manual setup	Manual with vector DB	Limited
Model flexibility	OpenAI, Claude, Ollama, any compatible API	Full flexibility	Any LangChain-supported LLM	Pre-configured providers
Embedding widget	One-line script	Custom frontend	Manual integration	Yes
Self-hosting	Yes (Docker)	Yes	Yes	Yes
Multi-agent support	Yes (Agent mode)	Programmatic	Yes (LangGraph)	Yes
Learning curve	Low	High	Medium-High	Low-Medium
Best for	Rapid prototyping, internal tools	Custom production apps	Complex AI pipelines	Customer support bots

Dify sits in a sweet spot: it is more flexible than no-code chatbot builders like Botpress, but far easier than coding from scratch with LangChain. If you need a chatbot that understands your documents and can be deployed in an afternoon, Dify is the right choice.

Creating Your First App

Once logged in, click the “Create from Blank” button. Dify offers four app types:

Chatbot — A conversational AI that can answer questions using your knowledge base.
Agent — A more advanced chatbot that can call tools (APIs, calculators, web search) and reason step by step.
Workflow — A visual canvas where you chain LLM calls, conditional branches, and code nodes. Batch processing, data transformation, or SEO content generation are good use cases.
Chatflow — A conversational version of Workflow where the AI responds based on a predefined conversation flow.

For this guide, choose Chatbot. Give it a name like “Customer Support Bot” and click Create.

Connecting LLM Models

Dify supports multiple model providers out of the box. Here is how to connect the most common ones.

OpenAI

Go to Settings > Model Provider > OpenAI and paste your API key. Dify will auto-discover available models: GPT-4o, GPT-4o-mini, GPT-4-turbo, and o-series reasoning models. Choose GPT-4o-mini for chat and text-embedding-3-small for embeddings (cheaper and faster for knowledge base tasks).

Anthropic Claude

Under Settings > Model Provider > Anthropic, paste your API key. You will see Claude 3.5 Sonnet, Claude 3 Opus, and Claude 3 Haiku. Claude is excellent at following long, detailed instructions — ideal if your chatbot needs nuanced responses.

Local Models via Ollama

First, install Ollama on your machine and pull a model:

ollama pull llama3.2
ollama pull nomic-embed-text

Then in Dify, go to Settings > Model Provider > Ollama and set the endpoint to http://host.docker.internal:11434 (or http://localhost:11434 if Dify is not in Docker). Click “Add Model” and enter the model name exactly as it appears in ollama list. Use nomic-embed-text for embeddings.

This setup keeps all data processing on your machine — no API calls leave your network.

Building a Knowledge Base

The knowledge base is what makes your chatbot useful beyond generic ChatGPT responses. It lets the AI answer questions about your specific documents.

Step 1: Create a Knowledge Base

Click Knowledge in the sidebar, then Create Knowledge. Name it “Product Manuals” or whatever describes your content.

Step 2: Upload Documents

Click Upload and drag in your files. Dify accepts:

PDF — Standard documents, scanned files (OCR handled automatically)
DOCX / DOC — Microsoft Word documents
TXT — Plain text files
Markdown — .md files
HTML — Web page exports
CSV / Excel — Tabular data
Notion — Sync directly from Notion pages

You can upload dozens of files at once. Dify will process them in the background.

Step 3: Choose Chunking Settings

Dify splits your documents into “chunks” — smaller pieces that the AI retrieves when answering a question. The settings matter:

Chunk size: 500 tokens is a good default. Smaller chunks (200-300) give more precise retrieval but may lose context. Larger chunks (1000+) preserve context but may bring back irrelevant content.
Chunk overlap: 50 tokens. This means each chunk shares 50 tokens with the next one, preventing ideas from being split across chunk boundaries.
Indexing method: High Quality uses the embedding model for semantic search. Economy uses keyword matching and is faster/cheaper but less accurate.

Click Save and Process. Depending on your document volume, processing takes 30 seconds to a few minutes.

Step 4: Link Knowledge Base to Your App

Go back to your chatbot app. In the Context section on the right panel, click Add and select your knowledge base. Now when a user asks a question, Dify will first search your documents, find the most relevant chunks, and feed them into the LLM’s prompt as context.

Writing the System Prompt

The system prompt defines your chatbot’s personality, behavior, and boundaries. Here is a practical example for a customer support bot:

You are a helpful and professional customer support agent for Acme Inc.,
a SaaS company that sells project management software.

RULES:
1. Answer only using the provided knowledge base content. If the answer
   is not in the documents, say: "I don't have that information in my
   knowledge base. Would you like me to connect you with a human agent?"
2. Be concise. Aim for 2-4 sentences per response.
3. If the user is frustrated, acknowledge their feelings first before
   providing a solution.
4. Never make up feature names, pricing, or policies. Only use what is
   in the documents.
5. Always include a relevant help center article link when available.

Tone: Friendly, patient, and solution-oriented. Use plain language.

Paste this in the Prompt field of your chatbot configuration.

Pro tip: Use the {{#context#}} variable in your prompt to control where retrieved document chunks are inserted. Dify inserts them automatically at the end, but you can position them for better prompt engineering.

Testing Your Chatbot

Click the Preview button on the right side. The chat panel opens. Test with questions your users are likely to ask:

“How do I reset my password?” (should answer from docs)
“What is your refund policy?” (should answer from docs)
“Who is the president of France?” (should say it does not know, if outside the knowledge base)

Watch the Citation icons — they show which document chunks the AI used to answer. If citations are missing or wrong, try:

Increasing the Top K setting (number of chunks retrieved, default 3)
Adjusting the Score threshold (minimum relevance score, lower is more permissive)
Re-chunking your documents with different sizes

Deploying to Your Website

Dify provides an embed script that adds a chat bubble to any website. In your app, go to Overview > Embed and choose Script. You will get HTML like this:

<script>
 window.difyChatbotConfig = {
  token: 'YOUR_APP_TOKEN',
  baseUrl: 'http://localhost:3000'
 }
</script>
<script
 src="http://localhost:3000/embed.min.js"
 id="YOUR_APP_TOKEN"
 defer>
</script>
<style>
  #dify-chatbot-bubble-button {
    background-color: #1C64F2 !important;
  }
</style>

Paste this before the closing </body> tag of your website. Replace the baseUrl with your actual Dify instance URL. For production, serve Dify behind a reverse proxy (Nginx or Caddy) with HTTPS enabled.

For React / Vue apps, use the iframe embed option or call the Dify REST API directly:

const response = await fetch('http://localhost:3000/v1/chat-messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer app-YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'How do I reset my password?',
    user: 'user-123',
    response_mode: 'blocking'
  })
});
const data = await response.json();
console.log(data.answer);

Each Dify app generates its own API key (find it under App > API Access). The API returns the full answer along with citations and metadata.

Advanced Features Worth Knowing

Variables

Variables let you inject dynamic context into prompts. For example, {{user_language}} could set the response language based on user preference. Define them in the Variables section of your app and pass their values via the API or embed script:

<script>
 window.difyChatbotConfig = {
  token: 'YOUR_APP_TOKEN',
  baseUrl: 'http://localhost:3000',
  inputs: {
    user_name: 'John',
    user_language: 'Spanish'
  }
 }
</script>

Tools (Agent Mode)

Switch to Agent app type to give your chatbot superpowers. Tools include:

Web Search — Let the AI search Google/DuckDuckGo for up-to-date information
Calculator — Solve math problems accurately
HTTP Request — Call your own APIs to check order status, book appointments, etc.
Code Interpreter — Run Python code for data analysis

Conversation Logs

Under Monitoring > Conversations, you can review every chat, see user satisfaction ratings, and identify questions your knowledge base failed to answer. Use this to continuously improve your documents and prompt.

Annotation & Fine-Tuning

If the bot gives a wrong answer, you can annotate the correct response. Over time, these annotations improve retrieval accuracy without retraining the model.

FAQ

Q: Is Dify really free?

Yes. The Community Edition is open-source and free forever under the Apache 2.0 license. The Dify Cloud has a free tier with 200 AI calls per month. You only pay for model API costs (OpenAI, Claude, etc.) which go directly to those providers.

Q: Can I use Dify without Docker?

The recommended installation uses Docker Compose. However, you can install each component (API server, web frontend, PostgreSQL, Redis, Weaviate) manually. This is only recommended for advanced users who need custom deployment setups.

Q: How is Dify different from LangChain?

LangChain is a Python/JavaScript framework for developers to build LLM applications from code. Dify is a visual platform that abstracts away the code — you configure everything through a UI. Dify is faster for prototyping; LangChain gives you more control for custom logic. They are complementary: some teams prototype in Dify and then re-implement in LangChain for production.

Q: What happens to my documents? Are they secure?

In self-hosted mode, all documents stay on your server. The embedding process converts text into vector numbers, which are stored in your local Weaviate/PostgreSQL instance. In Cloud mode, documents are stored on Dify’s servers, so check their security policy for sensitive data.

Q: Can I connect Dify to my own database or CRM?

Yes, you can use the HTTP Request tool in Agent mode to call external APIs, or use the API node in Workflow mode. Dify can pull customer data from your CRM, check inventory in your database, or post tickets to your helpdesk — all during a conversation.

Q: How many documents can I upload to a knowledge base?

There is no hard limit on the number of documents. Practical limits depend on your server’s RAM and storage. A single knowledge base with 10,000+ documents is feasible on a machine with 16 GB RAM. For very large collections, consider splitting across multiple knowledge bases.

Q: Does Dify support non-English languages?

Yes. The UI supports English, Chinese, Japanese, Korean, and several other languages. The AI itself will respond in whatever language you specify in your prompt. For non-English documents, the embedding models work well with most major languages, though accuracy varies by model and language.

Q: Can multiple teammates collaborate on the same app?

Yes. In the Dify workspace, you can invite team members with different roles: Owner, Admin, Editor, and Viewer. Editors can modify prompts and knowledge bases; Viewers can only test and use the apps.

Q: What if the chatbot gives wrong answers (hallucinations)?

Use these techniques to reduce hallucinations: (a) include a strict instruction in your prompt like “Only answer from the knowledge base, never invent information,” (b) lower the Score threshold to only retrieve highly relevant chunks, (c) increase Top K to give the model more context, and (d) review conversation logs regularly to identify gaps in your documents.

This guide was updated in June 2026 for Dify version 0.15+. Features and UI may change in newer versions. Always check the official Dify documentation for the latest information.