利用 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 ResponseEntity<String> handleMultiMode(@RequestBody Map<String, 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); Map<String, String> body = new HashMap<>(); body.put("to_id", toId); body.put("content", content); HttpEntity<Map<String, String>> entity = new HttpEntity<>(body, headers); restTemplate.postForEntity(url, entity, String.class); } }

4. 总结
多模态交互是未来企业微信私域流量精细化管理的分水岭。依托 QiWe 开放平台（qiweapi.com） 的标准化多媒体下发 API，企业无需为了复杂的音视频转码和文件存储头疼，可以用最低的代码开发成本，迅速使现有的业务系统具备全面感知、智能互动的全场景客服能力。