Connecting Dify to WeCom Customer Service: A Plugin-Based Runner in Practice

Title

Connecting Dify to WeCom Customer Service: A Plugin-Based Runner in Practice

Meta Description

LangBot 4.11 simplifies connecting Dify to WeCom Customer Service into three configuration steps: install the Dify Agent Runner plugin, create an Agent-mode processor, and bind the message.received event route. This article, based on local hands-on testing, walks through the specific steps, verification methods, and boundary limitations such as multi-turn conversations.

Article Content

Connecting Dify's knowledge base and orchestration capabilities to WeCom Customer Service used to require building a complete pipeline, embedding Dify as a service provider into LangBot's pipeline. The cost of this approach was duplicated orchestration logic: the Dify canvas had one set of model, prompt, and session settings, while the LangBot pipeline needed another, and a single pipeline could only serve one bot. LangBot 4.11 upgrades processors to Agents and moves Runner installation to the plugin marketplace, compressing the entire integration process into three configuration steps. This article, based on hands-on testing with a local instance, walks through the specific steps and the boundaries to watch out for.

Architecture Changes in 4.11: Runner Becomes a Marketplace Plugin

In 4.11, Dify is no longer a built-in runner but an official plugin, langbot-team/DifyAgent, with runner id plugin:langbot-team/DifyAgent/default. The official documentation OFFICIAL_RUNNER_PLUGINS.md explicitly maps the old dify-service-api runner to this plugin and classifies it among the first batch of "traditional service API runners," while also noting that the old built-in runner code no longer provides a runtime fallback. This means that after migrating to the new version, any environment must install the plugin first, or the Dify connection will not work.

Another key mechanism is event routing. Adapters declare the events supported by the platform. The WeCom Customer Service adapter declares inbound events such as message.received, message.deleted, and wecomcs.enter_session, as well as outbound actions such as send_message, reply_message, get_message, and get_user_info. Routing matches by priority from highest to lowest, and once the first match is hit, only one response target is executed. This directly affects configuration: attaching a second route to the same message.received event will not cause Dify to be called twice; instead, it may produce unexpected behavior.

The difference between Runner and Pipeline: In LangBot's earlier architecture, a Pipeline was a complete processing chain orchestrated by the user, including model selection, prompts, and session management; a Runner was closer to the role of a "runner," responsible for driving a specific backend service (such as Dify, FastGPT, etc.). In 4.11, Runner is changed from built-in code to a plugin installable from the marketplace, meaning the core no longer presets any runtime logic for service APIs—all external integrations must be loaded as plugins. The benefit is a lighter core and independently updatable integrations; the cost is an extra explicit installation step during deployment, and the plugin runtime environment (container network, dependencies) must align with the core.

Priority matching mechanism of event routing: LangBot's event routing system allows multiple routing rules to be configured for the same event type (such as message.received), each with a priority. The system matches rules one by one from highest to lowest priority; once a rule's conditions are met, it executes the response target specified by that rule and stops further matching. Therefore, attaching a second route to the same event does not cause the processor to be called twice—it serves as a backup or lower-priority processing path; if the first route already matches, the second will never execute. This explains why, during migration, the old pipeline route should be replaced with the new Agent processor rather than adding a new route.

A Three-Step Practical Path to Integration

Step 1: Create a WeCom Customer Service Bot

Create a new bot on the Bots page and select "WeCom Customer Service" as the platform. You need to fill in the enterprise ID, secret, token, and message encryption/decryption key. The Webhook callback URL is optional, but real traffic requires a publicly accessible callback URL. The local demo instance retains example values, which must be replaced in actual deployment.

Step 2: Install the Dify Agent Plugin from the Marketplace

Go to the Marketplace, search for Dify, find "Dify Agent," and install it. The measured installation progress showed a package size of 169.8 KB, and after installation the card bears the marker aria-label="Dify Agent installed". The installation itself is quick, but note that the plugin runtime container must be on the same network as the LangBot core so that the Dify base URL can be resolved afterward.

Step 3: Create an Agent-Mode Processor and Fill in Connection Information

Create a new processor in Processors, select Agent as the mode, and choose Dify Agent as the runner. The processor configuration requires values from the Dify side: base URL, API key, timeout (measured value: 30), expiration (3600), and identity (sender). The base URL must be accessible from within the runtime container; the local demo uses the container alias dify, so the address is http://dify:5001/v1. The API key is also a demo value and must be replaced with your own Dify app's key in real deployment.

Base URL and container networking: Dify's base URL is the entry point for the LangBot plugin runtime to access the Dify API. In self-hosted deployments, the LangBot core and Dify usually run on the same Docker network, so a container alias (such as http://dify:5001/v1) can be used instead of a public address. If the plugin runs in a separate container, you must ensure that container is on the same network as the Dify container; otherwise, even a correctly formatted URL will not resolve. In addition, Dify's API version path is typically /v1, which must match the deployed Dify version.

API key and identity field: A Dify app's API key is generated on the "Access API" page in the Dify console, and each app has its own. The "identity (sender)" field in the LangBot processor determines the user identifier passed to Dify, affecting session isolation and usage statistics on the Dify side; it is usually filled with the sender ID or a fixed value, depending on business needs. The timeout and expiration parameters control the timeout for a single request and the expiration time of the session context (in seconds), respectively. The measured values of 30 and 3600 can serve as a starting point, but timeouts should be increased appropriately in high-latency scenarios.

Step 4: Bind the Event Route

Go to the bot details page and find the event routing settings. The default first route is "Message received: message.received." Change its processor from the old "WeCom Customer Service Pipeline" to the newly created dify-wecomcs-agent, then reload. The route check's return value directly confirms the match; the measured response was "Route matched | Target processor | Agent · dify-wecomcs-agent | Matched rule | Route 1."

Step 5: Verify the Chain with Event Debugging

Go to event debugging on the Agent details page and send a test question: "Do you support private deployment?" The debugging page explicitly indicates that platform tools use Mock: the Agent actually calls tools, but platform actions such as replies and sends are simulated and no real messages are sent. Therefore, passing debugging only proves that the configuration is in effect and that the round trip between the Agent and Dify works; it does not prove final delivery on the WeCom side.

Verification and Key Boundaries

The most direct way to verify whether the chain is truly connected is to check the Dify endpoint logs. In the test, the local Dify-compatible endpoint received a POST /v1/chat-messages request, and the query in the request body was exactly the sentence sent during debugging, with response_mode set to streaming. On your own deployment, you can check this request in the same way.

Multi-turn conversation continuity was not confirmed in this test. The session was triggered three times, and each time the conversation_id was an empty string. The author infers that the runner plugin reads the external session ID from the context state, which is empty on the first call; subsequent calls would only carry it after the plugin writes Dify's returned conversation_id back to the state. The official documentation recommends that external runners store this ID in plugin storage or context runtime state rather than relying on LangBot's internal session structure. This still needs further confirmation.

Persistence mechanism of conversation_id: Dify's chat API maintains multi-turn context through the conversation_id field. On the first call, the field is empty, and Dify creates a new session and returns a new conversation_id in the response; subsequent calls must pass this ID back to continue the same session. In LangBot's plugin architecture, external runners must manage the storage of this ID themselves—the official recommendation is to save it in plugin storage or context runtime state rather than relying on LangBot's internal session structure. In this test, all three calls were empty, indicating that the plugin had not yet written Dify's returned ID back to the state, or that it was not read after being written back. To verify multi-turn continuity, you can observe in the Dify logs whether the second request carries a non-empty conversation_id, or check whether the corresponding key exists in plugin storage.

Applicable Scenarios and List of Limitations

This approach suits teams that already maintain knowledge bases and prompts in Dify and want to connect them to WeCom Customer Service, especially those who do not want to duplicate a set of model and session configurations in a pipeline. After integration, the Dify app canvas is the single orchestration entry point; adjusting prompts or switching models does not require synchronized changes on the LangBot side.

Limitations to note include: the demo environment is not a real Dify deployment, and the base URL and API key must be replaced; no real WeCom customer messages enter the system—real traffic depends on complete WeCom credentials and a public callback URL, and the adapter and platform support scope should be checked against the support matrix first; platform actions in debugging are simulated; multi-turn continuity is unverified; only one response target is allowed per event, and the old pipeline should not remain attached to that event; Runner is a plugin, the old built-in runner has no runtime fallback, and each environment must install the plugin separately.

If you do not want to maintain an instance yourself, the official hosted option space.langbot.app is available, but the steps in this article apply only to self-hosted deployments. For migration configuration mapping, refer to pipeline-migration-config-map.zh-CN.md in the repository, which maps the Dify provider in the old pipeline to the corresponding plugin and configuration items.