上周新來的小陳工位挪到我旁邊開口第一句就是哥咱這微信API能發(fā)啥消息啊文檔我翻了半天還是沒整明白。我當(dāng)時正改一個bug隨口回了句自己看文檔去但看他一臉懵的樣子想起我三年前剛接這塊也是一樣——8種消息類型散在文檔各處誰配合誰、什么場景用什么沒人串一下是真摸不著頭腦。那天下班我沒急著走把 Eyun開發(fā)文檔 翻了一遍整理出一份能直接對照著寫的清單給他。今天順手整理成文章給同樣卡在選型階段的朋友省點時間。一、8種消息類型逐一過一遍1. 文本消息sendText最常用沒有之一。發(fā)通知、做自動回復(fù)、推系統(tǒng)告警80%的場景都是它。參數(shù)要點wxId發(fā)送方實例、toId接收方、content文本內(nèi)容就這三個核心字段。踩坑點文本長度有上限超過會被截斷。我之前給客戶推一段長報錯日志結(jié)果只收到一半排查半天才知道是超長了。長內(nèi)容建議拆條發(fā)或者干脆改用文件消息。2. 圖片消息sendImage發(fā)截圖、發(fā)報表圖、發(fā)驗證碼凡是圖都用它。參數(shù)要點先調(diào)上傳接口拿mediaId也有文檔叫 fileId再拿這個 id 調(diào) sendImage。兩步走別想著一步到位。踩坑點第一次接我直接把圖片 base64 塞進發(fā)送接口報錯報得我懷疑人生。后來才看清要先上傳。圖片格式支持 jpg/png體積別太大不然上傳慢還容易被風(fēng)控盯上。3. 語音消息sendVoice發(fā)語音提醒適合開車場景或者長內(nèi)容不想讓用戶盯著字看的。參數(shù)要點跟圖片類似先上傳拿mediaId。格式必須是 AMR其他格式不行。踩坑點我用錄音接口出來的不是 AMR調(diào)接口一直失敗最后用 ffmpeg 轉(zhuǎn)了一道才通。格式這關(guān)卡了我小半天文檔里其實寫了我當(dāng)時沒細(xì)看。4. 視頻消息sendVideo發(fā)短視頻通知比如監(jiān)控告警配個現(xiàn)場畫面、產(chǎn)品演示片段。參數(shù)要點先上傳視頻拿mediaId再調(diào) sendVideo。視頻時長和體積都有建議范圍文檔里有標(biāo)。踩坑點視頻太長會被拒我傳過 50MB 的視頻直接超限。后來壓縮到 10MB 以內(nèi)才穩(wěn)。短視頻通知嘛別整大片又慢又占帶寬。5. 文件消息sendFile發(fā) PDF、Excel、Word 報表辦公場景的命根子。參數(shù)要點同樣是先上傳拿mediaId再調(diào) sendFile。支持常見文檔格式。踩坑點這個我推薦辦公場景優(yōu)先用它別用圖片消息發(fā)報表截圖——截圖看不清數(shù)字還得讓客戶放大。我做過一個月報表推送從截圖改成文件客戶反饋直接好評。6. 名片消息sendCard發(fā)聯(lián)系人名片A 推 B 給 C 的場景。參數(shù)要點參數(shù)里帶的就是被推薦人的wxId和昵稱。踩坑點被推薦的人必須是你好友不然發(fā)出去點不開。我踩過這個坑名片發(fā)出去了客戶點了沒反應(yīng)查了半天才知道那人早刪了我。7. 鏈接消息sendLink發(fā)圖文鏈接卡片標(biāo)題摘要縮略圖鏈接營銷推送的主力。參數(shù)要點標(biāo)題、描述、縮略圖URL、跳轉(zhuǎn)URL幾個字段填齊。踩坑點縮略圖建議用小圖加載快。我之前用 2MB 的大圖當(dāng)縮略圖卡片加載慢吞吞的用戶以為卡了直接劃走。這塊的具體字段說明建議在 Eyun平臺 看最新版本參數(shù)偶爾會微調(diào)。8. 小程序消息sendMiniProgram發(fā)小程序卡片電商導(dǎo)購、小程序商城場景的標(biāo)配。參數(shù)要點小程序的 appId、頁面路徑、標(biāo)題、縮略圖。踩坑點小程序必須和當(dāng)前微信號有授權(quán)關(guān)系否則發(fā)不出去。這個我沒踩過但群里有人問過提前說一句避坑。二、5個典型使用場景光知道有8種消息不夠得知道什么場景用什么。我把做過的項目歸了5類1. 通知推送系統(tǒng)狀態(tài)變了推給用戶知道。文本就夠復(fù)雜場景配圖片。比如訂單發(fā)貨通知用 sendText配個物流單號截圖用 sendImage。我做的工單系統(tǒng)告警就是純文本簡單粗暴但好用。2. 客服回復(fù)用戶問啥答啥。90% 用 sendText遇到要發(fā)資料就上 sendFile。客服場景文本響應(yīng)最快別為了花哨用圖片用戶等的是答案不是圖。3. 報表發(fā)送定時給管理層推數(shù)據(jù)。Excel 用 sendFile數(shù)據(jù)圖表用 sendImage。我現(xiàn)在做的日報系統(tǒng)就是這兩個輪著用早上8點自動推到管理群。4. 營銷推送活動推廣。sendLink 出場率最高圖文卡片點擊率高。但別濫用頻率控制前面提過我吃過被舉報拉黑的虧。5. 電商導(dǎo)購商品推薦。sendMiniProgram 引導(dǎo)到小程序下單閉環(huán)最順。也有用 sendLink 跳 H5 的看業(yè)務(wù)形態(tài)能走小程序就別走 H5體驗差一截。三、8種消息類型速查表我整理了張速查表開發(fā)的時候貼墻上對照著看類型接口名必填參數(shù)適用場景文本sendTextwxId/toId/content通知、自動回復(fù)圖片sendImagewxId/toId/mediaId截圖、報表圖語音sendVoicewxId/toId/mediaId(AMR)語音提醒視頻sendVideowxId/toId/mediaId短視頻通知文件sendFilewxId/toId/mediaIdPDF/Excel報表名片sendCardwxId/toId/cardWxId聯(lián)系人推薦鏈接sendLinkwxId/toId/url/title營銷推送小程序sendMiniProgramwxId/toId/appId/path電商導(dǎo)購這張表是我做完幾個項目復(fù)盤出來的新人按這個選型能少走彎路。參數(shù)細(xì)節(jié)偶爾有更新建議接之前對照 Eyun開發(fā)文檔 確認(rèn)下別照老記憶寫。四、一個統(tǒng)一發(fā)送方法8種消息接口名不一樣但參數(shù)結(jié)構(gòu)大同小異。我項目里用一個統(tǒng)一方法收口傳msgType切換類型維護起來輕松不少import requests BASE_URL https://api.eyunz.com # 以文檔實際地址為準(zhǔn) def send_message(wx_id, to_id, msg_type, content): 統(tǒng)一發(fā)送各類消息 msg_type: text/image/voice/video/file/card/link/miniapp content: 文本為字符串其余為mediaId或字典 api_map { text: sendText, image: sendImage, voice: sendVoice, video: sendVideo, file: sendFile, card: sendCard, link: sendLink, miniapp: sendMiniProgram } api api_map.get(msg_type) if not api: raise ValueError(f不支持的消息類型: {msg_type}) payload {wxId: wx_id, toId: to_id, msgType: msg_type, content: content} resp requests.post(f{BASE_URL}/{api}, jsonpayload, timeout10) data resp.json() if data.get(code) ! 0: raise RuntimeError(f發(fā)送失敗: {data}) return data[data]實際用的時候文本傳字符串圖片/語音/視頻/文件傳前面上傳拿到的 mediaId名片傳 cardWxId鏈接和小程序傳對應(yīng)字典。一個入口管八種類型加日志、限流、重試都好加不用滿項目找調(diào)用點。最后8種消息看著多理清楚也就那么回事文本是地基圖片和文件是辦公場景的左膀右臂語音視頻是補充名片鏈接小程序是特定場景的利器。先把文本和文件跑通再按需擴展別一上來8種全試一遍浪費時間還容易亂。選型這步看似不起眼但方向?qū)α撕竺媸∫话牍Ψ颉?shù)細(xì)節(jié)和最新字段建議以 Eyun平臺 文檔為準(zhǔn)我這里整理的是主干細(xì)節(jié)偶爾會更新。選對消息類型你的微信應(yīng)用就成了一半剩下的是把業(yè)務(wù)邏輯接順。