KocoroWeCom Integration Guide
Use WeCom's “intelligent bot” API mode to connect a Kocoro agent to WeCom, so your team can talk to your agent directly in one-on-one or group chats. The whole process takes about 3 minutes.
Before you start
- A WeCom “super admin” account, or a sub-admin account with “Management Tools” permission.
- Kocoro installed and initialized, with at least one agent created.
- A Mac that stays running to host the persistent connection (no public IP or domain required).
- 1
Open the WeCom “Intelligent Bot” admin page
Sign in to the WeCom admin console with an admin account, then in the left sidebar go to “Security & Management” → “Management Tools”, and click the “Intelligent Bot” card under the “AI Zone” category on the right.
- Requires a WeCom “super admin” account, or a sub-admin with “Management Tools” permission.
- Admin console: https://work.weixin.qq.com/wework_admin/
Figure 1: Find the “Intelligent Bot” entry under “Security & Management → Management Tools”. - 2
Choose “Create manually”
On the “Intelligent Bot” page, click the “Create bot” button. In the “What kind of bot do you need” dialog that appears, choose “Create manually” in the lower-left corner.
- Don't use the “AI auto-generate” option in the dialog — otherwise the configuration fields needed for API mode won't appear later.
Figure 2: Click “Create manually” in the lower-left of the create-bot dialog. - 3
Switch to “Create in API mode”
On the “Create Intelligent Bot” configuration page, scroll the right-hand settings panel to the very bottom, and just above the “Save / Cancel” buttons, click the “Create in API mode” link.
- In API mode, Kocoro takes over response generation, so page settings like “Plugins,” “Workflows,” and “Welcome message” can be left blank.
Figure 3: Scroll the right-hand settings panel to the bottom and click “Create in API mode”. - 4
Choose the persistent connection and copy the Bot ID and Secret
In the “API Configuration” area, set “Connection method” to “Use persistent connection” (no domain or public IP needed). Then copy the auto-generated “Bot ID” below, and click “Get” next to “Secret” to generate the key and copy it.
- Store the Secret safely — once you close the page you can't view it again, only regenerate it.
- Remember to set the bot's “Visible scope” at the top of the page and click “Save,” otherwise members can't chat with the bot in WeCom.
Figure 4: Choose “Use persistent connection,” then copy the “Bot ID” and the “Secret” after clicking Get. - 5
Add the WeCom bot in Kocoro
Open Kocoro, go to “Capabilities → Integrations,” find the “WeCom” connector, and click “+ Add bot.” In the dialog, paste what you copied in the previous step into “Bot ID” and “Bot Secret,” pick the “Agent” that should respond to messages, optionally give it a recognizable “Display name,” and finally click “Register bot” to finish.
- Once registered, the bot connects to Kocoro over the persistent connection immediately — send the bot a message in WeCom and the chosen agent will reply.
- You can click “Refresh” on the “Integrations” page anytime to check connection status, or click the trash icon to remove the bot.
Figure 5: Enter the Bot ID and Secret on Kocoro's “Integrations” page to complete bot registration.
Done! Next steps
After registration, members within the visible scope can message the bot in WeCom, and the chosen agent handles the replies. To have the bot respond in group chats, open a WeCom group, click “···” in the top-right → “Group bots,” and add the bot to the group.
- Change the visible scope, responding agent, or display name: go back to Kocoro's “Integrations” page to adjust.
- Secret leaked or lost: regenerate the Secret in the bot's “API Configuration” area in the WeCom admin console, then update it in Kocoro.
- Bot not responding: make sure Kocoro is running on your Mac and not asleep, and click “Refresh” on the “Integrations” page to check connection status.