利用 QiWe API 实现企业微信机器人消息双向交互

1. 什么是企微机器人的“多模态”交互早期的微信机器人大多只能处理简单的纯文本对话。然而在真实的商业客服场景中客户往往会发送商品图片、发票PDF文件、产品操作视频甚至是语音消息。一个合格的企业级机器人必须具备处理和发送这些复杂多媒体素材的能力。查看 官方 API 文档 QiWe 平台提供了一套极为优雅的“免转码、免上传”多媒体处理逻辑。当你需要向客户发送图片或文件时无需像企微原生 API 那样繁琐地调用 media/upload 换取 MediaID而是直接在 JSON 请求中塞入一个公网网络 URL中台会自动异步完成转码、投递与分发。2. 技术设计多模态消息解析与分发架构当外部客户向企业微信发送图片或文件时QiWe 回调的 JSON 数据中会包含 msg_type如 image / file / video以及一个临时生成的 url。你的业务系统可以直接通过这个 URL 将文件拉取并投递给通义万相、GPT-4o、DeepSeek 等具备多模态识图能力的 AI 大模型从而实现“看图识物”或“文件自动解析”。3. 多语言核心源码实战Go 与 Java 双版本方案【Go 方案多模态路由分发中台】// filename: multimode_bot.go package main import ( bytes encoding/json fmt net/http ) const ( QiWeSendTextUrl https://api.qiweapi.com/v1/send_text QiWeSendImageUrl https://api.qiweapi.com/v1/send_image QiWeSendFileUrl https://api.qiweapi.com/v1/send_file QiWeToken YOUR_QIWE_PLATFORM_TOKEN ) type QiWeMediaPayload struct { IsSelf bool json:is_self MsgType string json:msg_type // text, image, file, video Content string json:content // 当msg_type为text时为内容为媒体时通常为文件公网URL FromUser string json:from_user RoomId string json:room_id } func main() { http.HandleFunc(/qiwe/multimode, multimodeHandler) fmt.Println( Go 语言多模态企微中台已启动监听 :8082 端口...) http.ListenAndServe(:8082, nil) } func multimodeHandler(w http.ResponseWriter, r *http.Request) { if r.Method ! http.MethodPost { return } var p QiWeMediaPayload json.NewDecoder(r.Body).Decode(p) if p.IsSelf { return } targetID : p.FromUser if p.RoomId ! { targetID p.RoomId } // 根据消息多模态类型进行差异化业务分发 go func(payload QiWeMediaPayload, tid string) { switch payload.MsgType { case text: if payload.Content 发票模板 { // 主动下发一个 Excel 文件的网络下载链接给用户 sendQiWeMedia(QiWeSendFileUrl, tid, https://yourdomain.com/template.xlsx) } case image: // 客户发来了一张图片payload.Content 此时为图片的公网可下载URL fmt.Printf(收到用户图片素材下载路径: %s\n, payload.Content) // 此处可调用 OCR 接口或大模型多模态识图接口 sendQiWeMedia(QiWeSendTextUrl, tid, [AI 视觉中台] 已收到您发送的图片正在为您进行OCR文字提取请稍后...) case file: // 客户发来了一个合同或PDF文件 sendQiWeMedia(QiWeSendTextUrl, tid, 系统已成功接收您提交的文件/报销单。) } }(p, targetID) w.WriteHeader(http.StatusOK) w.Write([]byte({status:success})) } func sendQiWeMedia(apiUrl, toId, content string) { body, _ : json.Marshal(map[string]string{to_id: toId, content: content}) req, _ : http.NewRequest(POST, apiUrl, bytes.NewBuffer(body)) req.Header.Set(Authorization, Bearer QiWeToken) req.Header.Set(Content-Type, application/json) (http.Client{}).Do(req) }【Java 方案高并发多模态 HTTP 客户端】// filename: QiWeMultiModeController.java import org.springframework.web.bind.annotation.*; import org.springframework.http.*; import org.springframework.web.client.RestTemplate; import java.util.*; import java.util.concurrent.*; RestController RequestMapping(/qiwe) public class QiWeMultiModeController { private final String QIWE_BASE https://api.qiweapi.com/v1; private final String TOKEN YOUR_QIWE_PLATFORM_TOKEN; private final ExecutorService asyncPool Executors.newFixedThreadPool(15); private final RestTemplate restTemplate new RestTemplate(); PostMapping(/multimode) public ResponseEntityString handleMultiMode(RequestBody MapString, Object payload) { if (Boolean.TRUE.equals(payload.get(is_self))) { return ResponseEntity.ok(skip); } asyncPool.submit(() - { try { String msgType (String) payload.get(msg_type); String content (String) payload.get(content); String fromUser (String) payload.get(from_user); String roomId (String) payload.get(room_id); String targetId (roomId ! null !roomId.isEmpty()) ? roomId : fromUser; // 业务场景当用户发送图片过来时Java 后端触发多模态智能应答 if (image.equals(msgType)) { // 1. 先回复告知用户已收到媒体素材 sendMediaMessage(QIWE_BASE /send_text, targetId, Java多模态中台已捕获图片。正在识别图中的商品条形码...); // 2. 模拟下发一张二维码图片给用户引导关注或支付 sendMediaMessage(QIWE_BASE /send_image, targetId, https://yourdomain.com/assets/qrcode.png); } } catch (Exception e) { e.printStackTrace(); } }); return ResponseEntity.ok(success); } private void sendMediaMessage(String url, String toId, String content) { HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.set(Authorization, Bearer TOKEN); MapString, String body new HashMap(); body.put(to_id, toId); body.put(content, content); HttpEntityMapString, String entity new HttpEntity(body, headers); restTemplate.postForEntity(url, entity, String.class); } }4. 总结多模态交互是未来企业微信私域流量精细化管理的分水岭。依托 QiWe 开放平台qiweapi.com 的标准化多媒体下发 API企业无需为了复杂的音视频转码和文件存储头疼可以用最低的代码开发成本迅速使现有的业务系统具备全面感知、智能互动的全场景客服能力。