Yuanbao - Mibyan Docs

Connect Mibyan to Yuanbao, Tencent’s enterprise messaging platform. The adapter uses a WebSocket gateway for real-time message delivery and supports both direct (C2C) and group conversations.

Yuanbao is an enterprise messaging platform primarily used within Tencent and enterprise environments. It uses WebSocket for real-time communication, HMAC-based authentication, and supports rich media including images, files, and voice messages.

Prerequisites

A Yuanbao account with bot creation permissions
Yuanbao APP_ID and APP_SECRET (from platform admin)
Python packages: websockets and httpx, both core Mibyan dependencies

If these core dependencies are damaged, repair the selected environment:

mibyan pm repair

Setup

1. Create a Bot in Yuanbao

Download the Yuanbao app from https://yuanbao.tencent.com/
In the app, go to PAI → My Bot and create a new bot
After the bot is created, copy the APP_ID and APP_SECRET

2. Run the Setup Wizard

The easiest way to configure Yuanbao is through the interactive setup:

mibyan gateway setup

Select Yuanbao when prompted. The wizard will:

Ask for your APP_ID
Ask for your APP_SECRET
Save the configuration automatically

The WebSocket URL and API Domain have sensible defaults built in. You only need to provide APP_ID and APP_SECRET to get started.

3. Configure Environment Variables

After initial setup, verify these variables in ~/.mibyan/.env:

# Required
YUANBAO_APP_ID=your-app-id
YUANBAO_APP_SECRET=your-app-secret
YUANBAO_WS_URL=wss://api.yuanbao.example.com/ws
YUANBAO_API_DOMAIN=https://api.yuanbao.example.com

# Optional: bot account ID (normally obtained automatically from sign-token)
# YUANBAO_BOT_ID=your-bot-id

# Optional: internal routing environment (e.g. test/staging/production)
# YUANBAO_ROUTE_ENV=production

# Optional: home channel for cron/notifications (format: direct:<account> or group:<group_code>)
YUANBAO_HOME_CHANNEL=direct:bot_account_id
YUANBAO_HOME_CHANNEL_NAME="Bot Notifications"

# Optional: restrict access (legacy, see Access Control below for fine-grained policies)
YUANBAO_ALLOWED_USERS=user_account_1,user_account_2

4. Start the Gateway

mibyan gateway

The adapter will connect to the Yuanbao WebSocket gateway, authenticate using HMAC signatures, and begin processing messages.

Features

WebSocket gateway — real-time bidirectional communication
HMAC authentication — secure request signing with APP_ID/APP_SECRET
C2C messaging — direct user-to-bot conversations
Group messaging — conversations in group chats
Media support — images, files, and voice messages via COS (Cloud Object Storage)
Markdown formatting — messages are automatically chunked for Yuanbao’s size limits
Message deduplication — prevents duplicate processing of the same message
Heartbeat/keep-alive — maintains WebSocket connection stability
Typing indicators — shows “typing…” status while the agent processes
Automatic reconnection — handles WebSocket disconnections with exponential backoff
Group information queries — retrieve group details and member lists
Sticker/Emoji support — send TIMFaceElem stickers and emoji in conversations
WeChat forwarded chat-history support — when a user forwards a WeChat chat-history bundle into Yuanbao, the adapter decodes the forwarded records (sender nicknames, text, and multimedia entries, including nested forwards) and injects them into the conversation so the agent can read the full forwarded thread
Auto-sethome — first user to message the bot is automatically set as the home channel owner
Slow-response notification — sends a waiting message when the agent takes longer than expected

Configuration Options

Chat ID Formats

Yuanbao uses prefixed identifiers depending on conversation type:

Chat Type	Format	Example
Direct message (C2C)	`direct:<account>`	`direct:user123`
Group message	`group:<group_code>`	`group:grp456`

Media Uploads

The Yuanbao adapter automatically handles media uploads via COS (Tencent Cloud Object Storage):

Images: Supports JPEG, PNG, GIF, WebP
Files: Supports all common document types
Voice: Supports WAV, MP3, OGG

Media URLs are automatically validated and downloaded before upload to prevent SSRF attacks.

Home Channel

Use the /sethome command in any Yuanbao chat (DM or group) to designate it as the home channel. Scheduled tasks (cron jobs) deliver their results to this channel.

Auto-sethomeIf no home channel is configured, the first user to message the bot will be automatically set as the home channel owner. If the current home channel is a group chat, the first DM will upgrade it to a direct channel.

You can also set it manually in ~/.mibyan/.env:

YUANBAO_HOME_CHANNEL=direct:user_account_id
# or for a group:
# YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="My Bot Updates"

Example: Set Home Channel

Start a conversation with the bot in Yuanbao
Send the command: /sethome
The bot responds: “Home channel set to [chat_name] with ID [chat_id]. Cron jobs will deliver to this location.”
Future cron jobs and notifications will be sent to this channel

Example: Cron Job Delivery

Create a cron job:

/cron "0 9 * * *" Check server status

The scheduled output will be delivered to your Yuanbao home channel every day at 9 AM.

Usage Tips

Starting a Conversation

Send any message to the bot in Yuanbao:

hello

The bot responds in the same conversation thread.

Available Commands

All standard Mibyan commands work on Yuanbao:

Command	Description
`/new`	Start a fresh conversation
`/model [provider:model]`	Show or change the model
`/sethome`	Set this chat as the home channel
`/status`	Show session info
`/help`	Show available commands

Sending Files

To send a file to the bot, simply attach it directly in the Yuanbao chat. The bot will automatically download and process the file attachment. You can also include a message with the attachment:

Please analyze this document

Receiving Files

When you ask the bot to create or export a file, it sends the file directly to your Yuanbao chat.

Troubleshooting

Bot is online but not responding to messages

Cause: Authentication failed during WebSocket handshake. Fix:

Verify APP_ID and APP_SECRET are correct
Check that the WebSocket URL is accessible
Ensure the bot account has proper permissions
Review gateway logs: tail -f ~/.mibyan/logs/gateway.log

”Connection refused” error

Cause: WebSocket URL is unreachable or incorrect. Fix:

Verify the WebSocket URL format (should start with wss://)
Check network connectivity to the Yuanbao API domain
Confirm firewall allows WebSocket connections
Test URL with: curl -I https://[YUANBAO_API_DOMAIN]

Media uploads fail

Cause: COS credentials are invalid or media server is unreachable. Fix:

Verify API_DOMAIN is correct
Check that media upload permissions are enabled for your bot
Ensure the media file is accessible and not corrupted
Check COS bucket configuration with platform admin

Messages not delivered to home channel

Cause: Home channel ID format is incorrect or cron job hasn’t triggered. Fix:

Verify YUANBAO_HOME_CHANNEL is in correct format
Test with /sethome command to auto-detect correct format
Check cron job schedule with /status
Verify bot has send permissions in the target chat

Frequent disconnections

Cause: WebSocket connection is unstable or network is unreliable. Fix:

Check gateway logs for error patterns
Increase heartbeat timeout in connection settings
Ensure stable network connection to Yuanbao API
Consider enabling verbose logging: mibyan gateway run -vv

Access Control

Yuanbao supports fine-grained access control for both DM and group conversations:

# DM policy: open (default) | allowlist | disabled
YUANBAO_DM_POLICY=open
# Comma-separated user IDs allowed to DM the bot (only used when DM_POLICY=allowlist)
YUANBAO_DM_ALLOW_FROM=user_id_1,user_id_2

# Group policy: open (default) | allowlist | disabled
YUANBAO_GROUP_POLICY=open
# Comma-separated group codes allowed (only used when GROUP_POLICY=allowlist)
YUANBAO_GROUP_ALLOW_FROM=group_code_1,group_code_2

These can also be set in config.yaml:

platforms:
  yuanbao:
    extra:
      dm_policy: allowlist
      dm_allow_from: "user1,user2"
      group_policy: open
      group_allow_from: ""

Advanced Configuration

Message Chunking

Yuanbao has a maximum message size. Mibyan automatically chunks large responses with Markdown-aware splitting (respects code fences, tables, and paragraph boundaries).

Connection Parameters

The following connection parameters are built into the adapter with sensible defaults:

Parameter	Default Value	Description
WebSocket connect timeout	15 seconds	Time to wait for WS handshake
Heartbeat interval	30 seconds	Ping frequency to keep connection alive
Max reconnect attempts	100	Maximum number of reconnection tries
Reconnect backoff	1s → 60s (exponential)	Wait time between reconnect attempts
Reply heartbeat interval	2 seconds	RUNNING status send frequency
Send timeout	30 seconds	Timeout for outbound WS messages

These values are currently not configurable via environment variables. They are optimized for typical Yuanbao deployments.

Verbose Logging

Enable debug logging to troubleshoot connection issues:

mibyan gateway run -vv

Integration with Other Features

Cron Jobs

Schedule tasks that run on Yuanbao:

/cron "0 */4 * * *" Report system health

Results are delivered to your home channel.

Background Tasks

Run long operations without blocking the conversation:

/bg Analyze all files in the archive

Cross-Platform Messages

Send a message from CLI to Yuanbao:

mibyan chat -q "Send 'Hello from CLI' to yuanbao:group:group_code"

​Prerequisites

​Setup

​1. Create a Bot in Yuanbao

​2. Run the Setup Wizard

​3. Configure Environment Variables

​4. Start the Gateway

​Features

​Configuration Options

​Chat ID Formats

​Media Uploads

​Home Channel

​Example: Set Home Channel

​Example: Cron Job Delivery

​Usage Tips

​Starting a Conversation

​Available Commands

​Sending Files

​Receiving Files

​Troubleshooting

​Bot is online but not responding to messages

​”Connection refused” error

​Media uploads fail

​Messages not delivered to home channel

​Frequent disconnections

​Access Control

​Advanced Configuration

​Message Chunking

​Connection Parameters

​Verbose Logging

​Integration with Other Features

​Cron Jobs

​Background Tasks

​Cross-Platform Messages

​Related Documentation

Prerequisites

Setup

1. Create a Bot in Yuanbao

2. Run the Setup Wizard

3. Configure Environment Variables

4. Start the Gateway

Features

Configuration Options

Chat ID Formats

Media Uploads

Home Channel

Example: Set Home Channel

Example: Cron Job Delivery

Usage Tips

Starting a Conversation

Available Commands

Sending Files

Receiving Files

Troubleshooting

Bot is online but not responding to messages

”Connection refused” error

Media uploads fail

Messages not delivered to home channel

Frequent disconnections

Access Control

Advanced Configuration

Message Chunking

Connection Parameters

Verbose Logging

Integration with Other Features

Cron Jobs

Background Tasks

Cross-Platform Messages

Related Documentation