Dify Integration

Dify is an open-source LLM app development platform that combines AI workflow, RAG pipeline, agent capabilities, model management, and observability features. You can integrate Dify with Evolution API to deploy AI-powered conversational agents on WhatsApp.

What is Dify?

Dify provides:

Visual workflow builder for AI applications
RAG (Retrieval Augmented Generation) pipeline
Agent capabilities with tool calling
Multi-model support (OpenAI, Anthropic, local models)
Prompt engineering and testing
Conversation memory and context management
Built-in observability and analytics

Enable Dify Integration

Add this environment variable to your .env file:

# Enable Dify integration
DIFY_ENABLED=true

Configuration Settings

Create Default Settings

Before creating Dify bots, configure default behavior settings for your instance.

curl -X POST https://your-api.com/dify/settings/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "expire": 300,
    "keywordFinish": "#EXIT",
    "delayMessage": 1000,
    "unknownMessage": "I did not understand your message.",
    "listeningFromMe": false,
    "stopBotFromMe": false,
    "keepOpen": false,
    "debounceTime": 10,
    "ignoreJids": [],
    "difyIdFallback": ""
  }'

Settings Parameters

expire

number

required

Session expiration time in seconds. Default: 300 (5 minutes)

keywordFinish

string

required

Keyword to terminate the bot session. Example: “#EXIT”, “bye”

delayMessage

number

required

Delay in milliseconds between messages. Default: 1000

unknownMessage

string

required

Message sent when bot encounters an error or cannot respond

listeningFromMe

boolean

required

Whether bot responds to messages sent by the instance owner

stopBotFromMe

boolean

required

Whether instance owner can stop the bot session

keepOpen

boolean

required

Keep session open after completion. Default: false

debounceTime

number

required

Seconds to wait before processing rapid messages. Default: 10

ignoreJids

array

required

List of JIDs (phone numbers) to ignore

difyIdFallback

string

Fallback Dify bot ID to use when primary bot fails

Dify Bot Types

Dify supports different application types:

Chatbot

Conversational AI with memory:

Multi-turn conversations
Context retention
Personality customization
Tool/function calling

Agent

Autonomous AI agent with reasoning:

ReAct/Function Calling modes
Tool integration
Multi-step reasoning
Goal-oriented behavior

Workflow

Custom AI workflows:

Visual workflow builder
Complex logic and branching
Data processing
API integrations

Text Generator

Simple text completion:

Single-turn interactions
Template-based responses
Quick answers

Create a Dify Bot

Create Dify Application

Create and configure your AI application in your Dify instance. Note the API endpoint and API key.

Get API credentials

From Dify dashboard → API Access, copy your API key.

Create bot in Evolution API

Test the integration

Send a message matching your trigger to start a Dify conversation.

curl -X POST https://your-api.com/dify/create/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "description": "Customer Support AI Agent",
    "botType": "chatbot",
    "apiUrl": "https://api.dify.ai/v1",
    "apiKey": "app-your-dify-api-key",
    "triggerType": "keyword",
    "triggerOperator": "equals",
    "triggerValue": "ai",
    "expire": 300,
    "keywordFinish": "#EXIT",
    "delayMessage": 1000,
    "unknownMessage": "Sorry, I encountered an error.",
    "listeningFromMe": false,
    "stopBotFromMe": false,
    "keepOpen": false,
    "debounceTime": 10
  }'

Request Parameters

enabled

boolean

required

Enable or disable this bot

description

string

required

Description of the bot purpose

botType

string

required

Dify application type: “chatbot”, “agent”, “workflow”, or “textGenerator”

apiUrl

string

required

Dify API base URL (e.g., “https://api.dify.ai/v1” or your self-hosted URL)

apiKey

string

required

Your Dify application API key (starts with “app-”)

triggerType

string

required

Trigger type: “all”, “keyword”, or “advanced”

triggerOperator

string

For keyword triggers: “equals”, “contains”, “startsWith”, “endsWith”, “regex”

triggerValue

string

The keyword or regex pattern to trigger this bot

Trigger Types

All Messages

Respond to every message (only one “all” trigger allowed per instance):

{
  "triggerType": "all"
}

Keyword Trigger

Trigger based on specific keywords:

{
  "triggerType": "keyword",
  "triggerOperator": "equals",
  "triggerValue": "support"
}

Available operators:

equals - Exact match
contains - Contains the keyword
startsWith - Message starts with keyword
endsWith - Message ends with keyword
regex - Regular expression match

Advanced Trigger

Use regex for complex pattern matching:

{
  "triggerType": "advanced",
  "triggerValue": "^(question|ask|help)\\s"
}

Update Dify Bot

Modify an existing Dify bot configuration:

curl -X PUT https://your-api.com/dify/update/{instance}/{botId} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "description": "Updated AI Agent",
    "triggerValue": "help"
  }'

Delete Dify Bot

Remove a Dify bot from your instance:

curl -X DELETE https://your-api.com/dify/delete/{instance}/{botId} \
  -H "apikey: your-api-key"

Fetch Dify Bots

Retrieve all Dify bots configured for your instance:

curl -X GET https://your-api.com/dify/fetch/{instance} \
  -H "apikey: your-api-key"

Session Management

Change Session Status

Update the status of an active Dify session:

curl -X POST https://your-api.com/dify/changeStatus/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "remoteJid": "[email protected]",
    "status": "closed"
  }'

Fetch Sessions

Get all active Dify sessions:

curl -X GET https://your-api.com/dify/fetchSessions/{instance} \
  -H "apikey: your-api-key"

Conversation Context

Dify maintains conversation context automatically:

Each WhatsApp contact gets a unique conversation ID
Context is preserved across messages within the session
Session expires based on the expire setting
Use keepOpen: true to maintain long-running conversations

Use Cases

Intelligent Customer Support

Deploy AI-powered support:

Answer customer questions using RAG (knowledge base)
Escalate complex issues to human agents
Provide product recommendations
Handle multi-turn troubleshooting conversations

Sales Assistant

Automate sales conversations:

Product information and recommendations
Lead qualification and scoring
Order status and tracking
Upsell and cross-sell suggestions

Appointment Booking

Intelligent scheduling agent:

Check availability via API calls
Book appointments through workflows
Send confirmations and reminders
Handle rescheduling requests

Knowledge Base Assistant

RAG-powered information retrieval:

Connect to your documentation
Provide accurate, sourced answers
Multi-language support
Continuous learning from interactions

Best Practices

Use specific bot types based on your use case: chatbots for conversations, agents for complex tasks, workflows for structured processes.

Monitor your Dify API usage and costs, especially when using commercial LLM providers like OpenAI or Anthropic.

Design clear prompts: Craft specific system prompts in Dify for your use case
Use RAG wisely: Connect relevant knowledge bases for accurate responses
Set appropriate timeouts: Balance responsiveness with session management
Test thoroughly: Validate bot behavior with various input scenarios
Monitor performance: Use Dify’s observability features to track quality
Handle errors gracefully: Configure meaningful unknown messages

Troubleshooting

Bot not responding

Verify DIFY_ENABLED=true in your environment
Check that the bot is enabled (enabled: true)
Ensure trigger conditions match the incoming message
Verify Dify API URL is accessible from Evolution API server
Check Dify API key is valid and has proper permissions
Review Dify application logs for errors

Slow response times

Check Dify application performance in dashboard
Verify LLM provider (OpenAI, etc.) is responding quickly
Consider using faster models for time-sensitive use cases
Optimize your prompts and workflows in Dify
Check network latency between Evolution API and Dify

Context not maintained

Increase expire time if sessions are timing out too quickly
Set keepOpen: true for long-running conversations
Verify conversation IDs are being tracked correctly
Check that Dify application has conversation memory enabled

API errors or rate limits

Check your Dify API key permissions
Verify you haven’t exceeded Dify rate limits
Monitor your LLM provider quota (OpenAI, etc.)
Review Dify logs for specific error messages

Advanced Configuration

Multiple Bots

You can configure multiple Dify bots with different triggers:

// Support bot
{
  triggerType: 'keyword',
  triggerOperator: 'equals',
  triggerValue: 'support',
  botType: 'agent'
}

// Sales bot
{
  triggerType: 'keyword',
  triggerOperator: 'startsWith',
  triggerValue: 'buy',
  botType: 'chatbot'
}

// General assistant (fallback)
{
  triggerType: 'all',
  botType: 'chatbot'
}

Self-Hosted Dify

For self-hosted Dify installations:

{
  "apiUrl": "https://dify.yourcompany.com/v1",
  "apiKey": "app-your-api-key"
}

OpenAI - Direct OpenAI integration
Flowise - Alternative LLM orchestration platform
Typebot - Structured chatbot flows
N8N - Workflow automation

Get Started

Core Concepts

WhatsApp Integration

Chatbot Integrations

Event Systems

Storage & Media

Deployment

Dify Integration

Dify Integration

What is Dify?

Enable Dify Integration

Configuration Settings

Create Default Settings

Settings Parameters

Dify Bot Types

Chatbot

Agent

Workflow

Text Generator

Create a Dify Bot

Request Parameters

Trigger Types

All Messages

Keyword Trigger

Advanced Trigger

Update Dify Bot

Delete Dify Bot

Fetch Dify Bots

Session Management

Change Session Status

Fetch Sessions

Conversation Context

Use Cases

Best Practices

Troubleshooting

Advanced Configuration

Multiple Bots

Self-Hosted Dify

Build docs developers (and LLMs) love

Get Started

Core Concepts

WhatsApp Integration

Chatbot Integrations

Event Systems

Storage & Media

Deployment

​Dify Integration

​What is Dify?

​Enable Dify Integration

​Configuration Settings

​Create Default Settings

​Settings Parameters

​Dify Bot Types

​Chatbot

​Agent

​Workflow

​Text Generator

​Create a Dify Bot

​Request Parameters

​Trigger Types

​All Messages

​Keyword Trigger

​Advanced Trigger

​Update Dify Bot

​Delete Dify Bot

​Fetch Dify Bots

​Session Management

​Change Session Status

​Fetch Sessions

​Conversation Context

​Use Cases

​Best Practices

​Troubleshooting

​Advanced Configuration

​Multiple Bots

​Self-Hosted Dify

​Related Integrations

Build docs developers (and LLMs) love

Dify Integration

What is Dify?

Enable Dify Integration

Configuration Settings

Create Default Settings

Settings Parameters

Dify Bot Types

Chatbot

Agent

Workflow

Text Generator

Create a Dify Bot

Request Parameters

Trigger Types

All Messages

Keyword Trigger

Advanced Trigger

Update Dify Bot

Delete Dify Bot

Fetch Dify Bots

Session Management

Change Session Status

Fetch Sessions

Conversation Context

Use Cases

Best Practices

Troubleshooting

Advanced Configuration

Multiple Bots

Self-Hosted Dify

Related Integrations