dify

Official Drupal integration for the Dify AI platform. Index your Drupal content into a Dify knowledge base, embed AI-powered chatbot widgets, and augment your search results with intelligent responses, all with credentials kept server-side.

Architecture

The base module provides shared services (API client, markdown rendering, SSE streaming proxy). You enable only the submodules you need:

Submodule Purpose Extra dependencies dify_search_api Search API backend → Dify knowledge base composer require drupal/search_api:^1.40 league/html-to-markdown:^5.1 dify_widget_vanilla Custom chatbot widget (block) composer require league/commonmark:^2.8 dify_widget_official Official Dify embed widget (block) — dify_augmented_search AI answers alongside search results (block) composer require league/commonmark:^2.8

Key Features

Security first

• All API calls go through a server-side proxy — tokens never reach the browser.
• Credentials stored in Drupal State (database-only, never exported with configuration).
• CSRF protection on all POST proxy routes.
• SSL verification on all outgoing requests.

Content indexing (dify_search_api)

• Search API backend that pushes Drupal content to a Dify knowledge base.
• Three chunking modes: automatic, custom, and hierarchical (parent/child).
• Per-field priority weights for fine-grained relevance control.
• Contextual Field mode: one segment per field, tracked in a dedicated mapping table.
• File extraction: extract content from PDF, DOCX, and other file fields via a Dify Workflow.
• Automatic metadata with source URL for attribution in chatbot answers.

Vanilla chatbot widget (dify_widget_vanilla)

• Placed as a Drupal block — all settings in the block configuration form.
• Real-time streaming responses (Server-Sent Events via native curl).
• Conversation history persisted in localStorage across page loads.
• Feedback system: thumbs up/down on bot messages, sent to the Dify API.
• Suggested questions displayed after each bot response.
• Overridable avatars: bot and user avatars defined in Twig — themes can override with images, SVGs, or any markup.
• 20 configurable CSS color variables for full theming control.
• Markdown rendering (dark and light themes).
• Resizable, minimizable floating window.
• RGAA / WCAG accessible: skip link, ARIA attributes, keyboard navigation, screen reader support.

Official Dify widget (dify_widget_official)

• Drops Dify's own embed.min.js chatbot onto your site.
• Placed as a Drupal block — base URL and token in block settings.
• Zero custom code — uses Dify's hosted widget as-is.

Augmented search (dify_augmented_search)

• Block that detects search queries and shows AI-generated answers from a Dify Workflow alongside normal search results.
• Uses the Workflow API (/workflows/run) — not the Chat API.
• Streaming responses with markdown rendering.
• Configurable colors and theming.

Requirements

• Drupal 10 or 11
• PHP 8.1+
• A running Dify instance (cloud or self-hosted)

Composer pulls in library dependencies automatically.

Installation

composer require drupal/dify
drush en dify
drush en dify_search_api dify_widget_vanilla  # enable what you need

Configuration

Base module

Go to Configuration → Search and metadata → Dify (/admin/config/search/dify) to enter your Dify knowledge base credentials (used by dify_search_api).

Chatbot widgets

Both widgets are placed via Structure → Block Layout. Each block has its own base URL and API token fields. No global configuration form — everything lives in the block.

Search API indexing

1. Go to Configuration → Search and metadata → Search API.
2. Create a server with the Dify backend.
3. Create an index, add fields, and configure field priorities.
4. Index your content — it is pushed to the Dify knowledge base automatically.

Augmented search

Place the Dify Augmented Search block on your search results page. Configure the Dify Workflow base URL and token in the block settings. The block detects search queries automatically.

Deploying credentials

All credentials are stored in Drupal's State system. Each submodule README documents the exact drush state:set commands for automated deployments and CI/CD pipelines.

Documentation

Each submodule has its own README with detailed configuration, deployment, and troubleshooting instructions:

• modules/dify_search_api/README.md
• modules/dify_widget_vanilla/README.md
• modules/dify_widget_official/README.md
• modules/dify_augmented_search/README.md

⚠️ Upgrading from 1.x

There is no automated upgrade path from 1.x to 2.x. You must uninstall the module and reinstall it:

drush pm:uninstall dify
composer require 'drupal/dify:^2.0'
composer require (see extra dependency)
drush en dify

Re-enter your credentials and reconfigure each submodule after reinstalling.

Official Dify integration — Authorized by LangGenius, Inc. with written permission to use Dify name, branding, and assets for this Drupal module.