Coze on WeChat: Bringing the Coze (button) bot to WeChat

General Introduction

Coze on WeChat is an open source project designed to help users seamlessly integrate AI bots from the Coze platform into WeChat. It is based on chatgpt-on-wechat and dify-on-wechat, and supports text chat, voice recognition and reply, plug-in functionality, as well as image and link sending. The project uses Gewechat's iPad protocol to log into WeChat, which is more stable than traditional itchat. Users need to create bots on the Coze platform, and through simple configuration, they can realize intelligent interaction on WeChat. The project provides a web-based management interface for easy adjustment of settings. As of March 2025, it is being followed by developers on GitHub and is suitable for individuals or teams to build intelligent assistants for WeChat.

COZE Configuration

Coze on WeChat Backend Configuration

Function List

• text chat: Private and group chats are supported, and the bot remembers the context of the conversation to provide coherent responses.
• voice interaction: Recognizes voice input within 20 seconds and supports voice response.
• Plug-in Support: Docking Coze plugin functionality to turn plugin cards into WeChat links.
• multimedia delivery: The ability to send images, links and other content to enhance the interactive experience.
• Web Management Interface: Adjust the robot parameters through the web page without modifying the code.
• knowledge base function: Upload files or web content and let the robot answer questions based on that data.

Using Help

Installation process

Using Coze on WeChat requires preparing the environment and completing the deployment. Below are the detailed steps:

1. Preparatory work

• Sign up for a Coze account: Visit the Coze website, register and log in. Click "Create Robot" to set up your robot.
• Getting the API key: On Coze's "Personal Access Token" page (link (on a website)) Generate the token and save it.
• mounting tool: Ensure that your computer or server has Git and Docker installed; Git for downloading code and Docker for running services.
• Select Deployment Method: Supports local running, server running and Docker deployment, just choose one.

2. Downloading the project

Enter it in a terminal or on the command line:

git clone https://github.com/JC0v0/Coze-on-Wechat
cd Coze-on-Wechat

This will download the project code and go into the directory.

3. Configuration environment

Local or server deployment

• Creating a Virtual Environment(Optional but recommended):
  • Use venv:

    python3 -m venv Coze-on-Wechat
    source Coze-on-Wechat/bin/activate # Windows with Coze-on-Wechat\Scripts\activate
    

  • Use conda:

    conda create -n Coze-on-Wechat python=3.12
    conda activate Coze-on-Wechat
    

• Installation of dependencies::

pip3 install -r requirements.txt

• Configure config.json::

cp config.json.example config.json

Open with a text editor config.json, fill in the key fields below:

{
"coze_api_base": "https://api.coze.cn",
"coze_api_key": "Your API key",
"coze_bot_id": "Your bot ID", // Get it from the Coze dev page URL
"channel_type": "gewechat", "model": "coze": "coze_bot_id", // From the Coze dev page URL.

"single_chat_prefix": ["bot", "@bot"], // Private chat trigger term
"group_chat_prefix": ["@bot"], // group chat trigger word
"group_name_white_list": ["ALL_GROUP"] // Groups that allow bot replies
}

Docker Deployment

• Pulling Gewechat Mirrors::

docker pull registry.cn-chengdu.aliyuncs.com/tu1h/wechotd:alpine
docker tag registry.cn-chengdu.aliyuncs.com/tu1h/wechotd:alpine gewe

• Creating a Data Catalog::

mkdir -p gewechat/data

• Copying configuration files::

cp config-template.json config.json

• Starting services::

docker-compose up -d

4. Activation and login

• local operation::

python3 app.py

• server operation::

nohup python3 app.py & tail -f nohup.out

• Web interface operation::

cd web
streamlit run Home.py

interviews http://localhost:8501The configuration is done at the web page.

• Docker Deployment: View logs after startup:

docker logs -f coze-on-wechat

• Log in to WeChat: A QR code link will be displayed in the log, open the link and scan with WeChat to log in.

5. Testing functions

After logging in, send a message to the bot test. Example:

• Private chat: Type "bot hello" or "@bot hello".
• Group Chat: Type "@bot Today's Weather" in the whitelisted group.

Functional operation flow

text chat

• private chat: Send a message directly to the bot, such as "bot check weather", and it will reply.
• group chat: Add question triggers with "@bot" in allowed groups, e.g. "@bot what time does it rain tomorrow".

voice interaction

• send a voice: Record your voice in 20 seconds and send it to the robot, which will recognize it and reply.
• receive a voice: If you enable voice response (you need to set the tone ID in Coze), the robot will answer with your voice.
• Configuring Voice: in config.json Set in:

"speech_recognition": true,
"text_to_voice": "coze", "coze_voice_id": "Tone ID" // retrieved from Coze documentation
"coze_voice_id": "Tone ID" // retrieved from Coze document

Plug-in Support

• Add plug-ins (e.g., news queries) for bots in the Coze platform.
• Send a command in WeChat (e.g. "check news") and the robot will return the WeChat link.
• Example: Send "check the weather" and the weather link will be returned.

multimedia delivery

• The robot can send pictures or links. For example, ask "Show me a picture of a cat" and it will send a picture.

Web Management Interface

• After launching the web interface, access the http://服务器IP:8501The
• Modify parameters such as trigger words, group whitelist, etc. on the interface without editing the file.

caveat

• stability: Gewechat's iPad protocol is more stable, but it is recommended to test it with a small number to avoid the risk of the main number.
• Dependency Coze: The functionality relies on the Coze platform to ensure that the API key is valid.
• network requirement: Server deployment requires the opening of corresponding ports (e.g., 2531, 2532, 9919).

application scenario

1. Personal Assistant
   Ask questions, get information or perform tasks such as checking the weather or taking notes on WeChat at any time.
2. Group Chat Management
   Robots automatically answer frequently asked questions in the group, reducing the administrator's burden, suitable for interest groups or work groups.
3. Learning Tools
   After uploading learning materials, the robot can answer relevant questions and facilitate students' review.

QA

1. Do I need additional configuration for voice response?
   Yes, you need to set the tone ID on the Coze platform and set the tone ID in the config.json Enable the voice option.
2. Does it support sending pictures?
   support, the robot can return images or links based on the Coze configuration.
3. What is the difference between Docker deployment and local deployment?
   Docker is more suitable for one-click server deployment and simple management; local deployment is suitable for development and debugging.