python-wechat-kf

微信客服 API 网页测试工具：监听用户消息、主动/被动发消息，消息存储到 PostgreSQL。

快速开始

1. 创建 PostgreSQL 数据库

createdb wechat_kf

2. 配置 .env

cp .env.example .env

编辑 .env 填入真实配置：

# --- 企业微信基础信息（必填）---
# 企业 ID，在企业微信管理后台 - 我的企业 页面底部查看
CORPID=ww9f866d5bf5175e77

# 应用 Secret，在企业微信管理后台 - 微信客服 - 开发配置 中获取
SECRET=your_secret_here

# 客服账号 ID，在企业微信管理后台 - 微信客服 - 客服账号 详情页查看
OPEN_KFID=wkxxxxxxxxxxxxx

# --- 回调配置（可选，仅接收实时消息时需要）---
# 自定义 3-32 位字符串，与后台配置的回调 Token 一致
CALLBACK_TOKEN=my_token_123

# 企业微信后台随机生成的 43 位 EncodingAESKey
CALLBACK_AES_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# --- 数据库配置 ---
# 格式: postgresql+asyncpg://用户名:密码@主机:端口/数据库名
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/wechat_kf

数据库连接字符串 格式：

postgresql+asyncpg://用户名:密码@主机地址:端口/数据库名

如果需要修改用户名、密码、主机或数据库名，直接改这个连接字符串即可。

3. 安装依赖并启动

pip install -r requirements.txt
python run.py

访问 http://localhost:8000 即可看到聊天界面。

---

CALLBACK_TOKEN 和 CALLBACK_AES_KEY 的使用

这两个参数用于 微信回调消息的加解密，只在需要接收实时消息推送时才需要配置。

配置流程

1. 登录 企业微信管理后台
2. 进入 微信客服 → 选中客服账号 → 开发配置
3. 在回调配置中：
   • Token：自定义填一个 3-32 位字符串（如 my_token_123），同时写入 .env 的 CALLBACK_TOKEN
   • EncodingAESKey：点击"随机生成"，得到一个 43 位字符串，填入 .env 的 CALLBACK_AES_KEY
   • 回调 URL：填写 https://你的域名/webhook（见下方本地测试方案）
4. 保存后微信会立刻发送 GET 请求到回调 URL 进行验证

如果不配回调

不配回调不影响以下功能：

• 点击页面的 "同步拉取" 按钮主动轮询获取消息
• 在页面中 发送消息 给客户

---

本地测试方案

回调模式要求 URL 必须是 公网 HTTPS。本地开发可以用以下工具：

ngrok（推荐）

# 安装 ngrok 并启动
ngrok http 8000

# 会得到一个公网 URL，例如 https://abc123.ngrok.io
# 在微信管理后台填入 https://abc123.ngrok.io/webhook 即可

其他方案

方案	说明
ngrok	免费，一行命令，推荐
frp	需要一台有公网 IP 的服务器
localhost.run	ssh -R 80:localhost:8000 localhost.run
部署到公网服务器	直接部署到有 HTTPS 的服务器

不配回调也能测试

即使没有公网地址，也可以：

1. 启动应用 → 打开页面 → 点击 "同步拉取" 获取历史消息
2. 在输入框输入内容 → 点击 "发送" 主动给客户发消息
3. 这是轮询模式，不需要公网、不需要回调配置