Skip to main content

IM Channel Integration Guide

IM Channel Integration allows you to connect Wegent agents to instant messaging platforms, enabling users to interact with AI agents directly within their familiar chat tools.

πŸ“‹ Table of Contents​

🎯 Overview​

What is IM Channel Integration?​

IM Channel Integration connects Wegent agents to instant messaging platforms, allowing users to chat with AI agents directly in their preferred messaging apps without accessing the Wegent web interface.

Core Benefits​

BenefitDescription
Familiar EnvironmentUse AI agents in the chat tools you already use daily
Real-time ResponsesGet streaming AI responses through platform cards or message updates
Multi-turn ConversationsMaintain context across multiple messages
Team CollaborationShare AI capabilities with your entire organization

Supported Platforms​

PlatformStatusFeatures
DingTalkβœ… AvailableStream mode, AI Card streaming, multi-turn conversations
Telegramβœ… AvailablePrivate chat, command flow, Chat/Task modes, streaming message updates
Discordβœ… AvailablePrivate chat, command flow, Chat/Task modes
Weibo DMβœ… AvailablePrivate chat, WebSocket connection, streaming message accumulation, Wework local task continuation
Feishu/LarkπŸ”œ PlannedComing soon
WeChat WorkπŸ”œ PlannedComing soon

πŸ— Architecture​

Message Flow​

The following diagram illustrates how messages flow through the IM integration system:

Key Components​

ComponentPurpose
Channel ManagerManages lifecycle of all IM channel connections
Channel ProviderPlatform-specific connection handler (DingTalk, Telegram, Discord, etc.)
Message HandlerProcesses incoming messages and routes to agents
Response EmitterSends AI responses back to IM platform (sync or streaming)

πŸ’¬ Using IM Channels​

Basic Conversation​

Simply send messages to the bot in your IM platform as you would in any chat:

User: What can you help me with?
Bot: I'm an AI assistant powered by Wegent. I can help you with...

Multi-turn Conversations​

The bot maintains conversation context within the same chat session:

User: I'm working on a React project
Bot: Great! I'd be happy to help with your React project...

User: How do I optimize performance?
Bot: For your React project, here are some performance optimization tips...

Starting a New Conversation​

To clear context and start fresh, use the /new command:

User: /new
Bot: Started a new conversation. How can I help you?

Streaming Responses​

When platform streaming is enabled, you'll see responses appear in real time:

  1. Bot shows "Thinking..." indicator
  2. Response text streams in progressively
  3. Final response is displayed with formatting

DingTalk uses AI Card updates for streaming content. Telegram uses message updates to show streaming content and reasoning summaries.

Weibo DM uses one stable message for streaming accumulation: the backend creates a stable Weibo messageId, then later content chunks and completion events update the same DM message. Runtime status events, such as "analyzing the issue", provide progress context, so the Weibo channel does not add an extra "thinking" placeholder.

Private Chat Task Mode​

In IM channels that support private chats, use commands to choose chat or task mode:

CommandDescription
/newCreate a Chat, create a Task, or continue a recent Task
/chatSwitch to Chat mode
/taskSwitch to Task mode and select a recent task
/switchSelect a different current task
/bindBind the current private chat to a task
/statusView current private chat status
/cancelCancel the current selection flow

Weibo DM Task mode only supports local runtime tasks bound from Wework. First click Continue in private chat from the Wework local task, choose the Weibo private chat, and then continue sending messages in Weibo. If you use /task or /switch directly in Weibo without a bound local task, Wegent prompts you to return to Wework and choose a target private chat.

βš™οΈ Management Features​

Channel Status Monitoring​

View channel health in the admin panel:

StatusIndicatorDescription
Connected🟒 GreenChannel is active and receiving messages
DisconnectedπŸ”΄ RedChannel is offline or experiencing errors
Disabledβšͺ GrayChannel is manually disabled

Channel Operations​

OperationDescription
Enable/DisableToggle channel without deleting configuration
RestartReconnect to IM platform (useful after network issues)
EditModify channel settings (leave secret empty to keep existing)
DeleteRemove channel configuration

Updating Configuration​

When editing a channel:

  • Sensitive fields (Client Secret) are masked with ***
  • Leave sensitive fields empty to keep existing values
  • Enter new values to update credentials

Weibo DM Configuration​

When creating a Weibo DM channel:

  1. In Admin Panel β†’ IM Channels, choose Weibo.
  2. DM Weibo Longxia Assistant to get the App ID and App Secret.
  3. Enter the App ID and App Secret in Wegent.
  4. Usually leave the WebSocket endpoint and token endpoint empty so Wegent uses the default Weibo Open IM endpoints; override them only for a proxy or test environment.
  5. Select the default Agent and enable the channel.

When editing, leave App Secret empty to keep the existing value.

Monitoring Metrics​

Available metrics for each channel:

  • Uptime: How long the channel has been connected
  • Last Error: Most recent error message (if any)
  • Connection Time: When the channel was last connected

πŸ‘₯ User Mapping Mechanism​

Automatic User Creation​

When an IM platform user interacts with the bot for the first time:

  1. System attempts to find existing Wegent user
  2. If not found, automatically creates a new user account
  3. User is linked to their IM platform identity

Default user creation:

  • Username: IM platform user ID
  • Email: {user_id}@im-platform.com
  • Auth Source: Corresponding IM platform name

Enterprise User Mapping​

For organizations with existing user directories (ERP, LDAP), custom user mappers can be configured:

Contact your system administrator to configure enterprise user mapping.

πŸ”— Platform Integration Guides​

The following platforms have detailed integration configuration guides:

PlatformLink
DingTalkDingTalk Integration Guide

❓ Troubleshooting​

Connection Issues​

Channel shows "Disconnected"​

Possible causes:

  1. Invalid Client ID or Client Secret
  2. Network connectivity issues
  3. IM platform API service disruption

Solutions:

  1. Verify credentials in the open platform
  2. Check network connectivity from Wegent server
  3. Try restarting the channel
  4. Check IM platform service status

Messages not being received​

Possible causes:

  1. Required message receiving or streaming capability is not enabled in the IM platform
  2. Robot permissions not configured
  3. Channel not enabled in Wegent

Solutions:

  1. Verify message receiving or streaming is enabled in IM app settings
  2. Check all required permissions are granted
  3. Ensure channel is enabled (toggle is on)

Response Issues​

Bot not responding​

Possible causes:

  1. Default Agent not configured
  2. Agent has no model assigned
  3. Rate limiting

Solutions:

  1. Verify a default Agent is selected for the channel
  2. Ensure the Agent has a working model configuration
  3. Check for rate limit errors in channel status

Slow or incomplete responses​

Possible causes:

  1. Platform streaming or message update issues
  2. Network latency
  3. Large response content

Solutions:

  1. Try disabling platform streaming temporarily
  2. Check network connectivity
  3. The system will fall back to sync mode if streaming fails

User Issues​

User not recognized​

Possible causes:

  1. User mapping configuration issues
  2. IM platform user info not accessible

Solutions:

  1. Check user permissions in IM app
  2. Verify user mapping configuration
  3. Contact administrator for enterprise user mapping

πŸ”— Related Resources​

Documentation​

External Resources​

πŸ’¬ Get Help​

Need assistance?

  • πŸ“– Check FAQ
  • πŸ› Submit GitHub Issue
  • πŸ’¬ Join community discussions

Connect your AI agents to IM platforms and empower your team! πŸš€