微信API發(fā)消息接口實(shí)戰(zhàn)：私聊、群聊與媒體格式詳解)
上周有個(gè)做運(yùn)維的朋友跑來找我問能不能讓服務(wù)器定時(shí)往員工的企業(yè)微信里推日?qǐng)?bào)往部門群發(fā)告警圖片甚至給客戶群群發(fā)帶附件的資料。聊下來發(fā)現(xiàn)他最困惑的點(diǎn)不是“接口長(zhǎng)什么樣”而是企業(yè)微信發(fā)消息這回事其實(shí)被拆成了好幾條完全不同的通道給成員個(gè)人發(fā)私聊消息、按部門或標(biāo)簽做廣播、往群里發(fā)機(jī)器人消息、給外部客戶群群發(fā)各自對(duì)應(yīng)的接口和權(quán)限都不一樣。這篇就圍繞“企業(yè)微信 API 發(fā)消息接口”這個(gè)主題把私聊、群聊、多種媒體格式以及我在真實(shí)項(xiàng)目里調(diào)通的完整流程、踩過的坑一次說清楚。這文章適合誰看只要你的工作里需要寫代碼調(diào)用企業(yè)微信接口不管是做自動(dòng)化告警、報(bào)表推送、內(nèi)部通知系統(tǒng)還是做客戶運(yùn)營(yíng)消息觸達(dá)都能從中找到可以直接抄走的思路和代碼。下面所有內(nèi)容都基于我在真實(shí)項(xiàng)目中反復(fù)驗(yàn)證過的方案不同基礎(chǔ)的人照著搭都能跑通。1. 先理清楚企業(yè)微信消息接口到底有哪幾類玩法很多人一聽“企業(yè)微信API發(fā)消息”下意識(shí)以為就是一個(gè)接口把消息發(fā)出去就行。實(shí)際沒那么簡(jiǎn)單。企業(yè)微信把“發(fā)消息”分成了好幾條不同的通道每條通道的權(quán)限模型、調(diào)用方式、能發(fā)什么格式都不一樣。如果不先搞清楚這些代碼寫了一半才發(fā)現(xiàn)權(quán)限不對(duì)、格式不支持返工成本非常高。1.1 “私聊”不只是點(diǎn)對(duì)點(diǎn)自建應(yīng)用消息通道在標(biāo)題里說到的“私聊”在企業(yè)微信API里最典型的實(shí)現(xiàn)路徑是自建應(yīng)用消息。你在企業(yè)微信管理后臺(tái)創(chuàng)建了一個(gè)自建應(yīng)用然后通過這個(gè)應(yīng)用給指定成員發(fā)消息。這里的“私聊”不是指兩個(gè)員工之間互相聊天而是指系統(tǒng)通過應(yīng)用給某個(gè)員工發(fā)一對(duì)一的對(duì)話消息。這個(gè)通道能干的事情非常多。比如我做過的一個(gè)模擬項(xiàng)目X每天定時(shí)推送前一天的運(yùn)營(yíng)數(shù)據(jù)給各業(yè)務(wù)負(fù)責(zé)人用的就是這種通道。它的核心特點(diǎn)是按userid精確指定接收人一個(gè)接口調(diào)用可以傳多個(gè)userid用|分隔也支持按部門IDpartyid和標(biāo)簽IDtagid批量發(fā)送這種就帶了“群發(fā)/廣播”的味道消息類型齊全文本、圖片、語音、視頻、文件、圖文卡片都能發(fā)消息出現(xiàn)在企業(yè)微信的“工作臺(tái)-應(yīng)用”會(huì)話里本質(zhì)上就是一次真實(shí)的企業(yè)微信對(duì)話我后來總結(jié)了一個(gè)經(jīng)驗(yàn)如果你的業(yè)務(wù)場(chǎng)景是“系統(tǒng)主動(dòng)找人”就選自建應(yīng)用消息通道如果是“人主動(dòng)找系統(tǒng)聊天”那就要再配置消息接收回調(diào)做一套對(duì)話機(jī)器人。但那是另一個(gè)項(xiàng)目了這里先不展開。1.2 “群聊”的幾種實(shí)現(xiàn)路徑群機(jī)器人、部門群發(fā)與客戶群群發(fā)標(biāo)題里的“群聊”是一個(gè)容易混淆的點(diǎn)因?yàn)橹辽儆腥龡l路都叫“群聊”。我實(shí)際測(cè)試下來三條路的適用場(chǎng)景差異很大這里直接給結(jié)論路徑一群機(jī)器人webhook在企業(yè)微信任意一個(gè)群里可以添加一個(gè)“群機(jī)器人”。添加之后會(huì)生成一個(gè)webhook地址代碼里往這個(gè)地址POST一段JSON就能把消息推到那個(gè)具體群里。這個(gè)方案最輕量不需要申請(qǐng)接口權(quán)限不用配可信域名是個(gè)人開發(fā)者最快能體驗(yàn)“發(fā)群消息”的方式。路徑二給部門/標(biāo)簽發(fā)廣播自建應(yīng)用消息除了指定單人也可以指定toparty或totag。比如給“研發(fā)部”整個(gè)部門發(fā)通知給“全體成員”標(biāo)簽發(fā)公告。這種方式在企業(yè)內(nèi)部用得最多適合做全員通知、部門公告。路徑三客戶群群發(fā)這是運(yùn)營(yíng)向的場(chǎng)景通過“客戶聯(lián)系”相關(guān)接口給外部客戶的微信群做群發(fā)。這個(gè)接口的權(quán)限模型更嚴(yán)需要單獨(dú)配置客戶聯(lián)系Secret而且要提前創(chuàng)建群發(fā)任務(wù)。如果你只是做內(nèi)部自動(dòng)化通知基本用不上這條路。我在文末會(huì)提一下什么時(shí)候才需要考慮它。1.3 為什么標(biāo)題強(qiáng)調(diào)“多種媒體格式”“多種媒體格式”是企業(yè)微信消息接口相比其他聊天軟件接口最實(shí)用的一點(diǎn)。你不只能發(fā)純文字還能把圖片、語音、視頻、普通文件、圖文卡片都發(fā)到成員會(huì)話或群里。這帶來一個(gè)直接的業(yè)務(wù)價(jià)值告警系統(tǒng)不僅報(bào)一句“服務(wù)器負(fù)載高了”還能附帶一張監(jiān)控截圖報(bào)表系統(tǒng)不止發(fā)一串?dāng)?shù)字還能推送一個(gè)圖文卡片點(diǎn)進(jìn)去就是完整看板運(yùn)營(yíng)系統(tǒng)給客戶群發(fā)資料PDF文件直接推送。可以說媒體格式的豐富程度決定了這個(gè)接口能承載多少真實(shí)業(yè)務(wù)場(chǎng)景。但每種媒體格式都有自己的限制比如圖片不能超過2MB、視頻不能超過10MB、文件不能超過20MB而且要先用“臨時(shí)素材上傳接口”拿到一個(gè)media_id才能發(fā)送。這些細(xì)節(jié)我在第3部分專門展開講。2. 接入前必須搞懂的幾個(gè)關(guān)鍵概念調(diào)用企業(yè)微信API之前如果不先把幾個(gè)核心概念理清楚后面會(huì)出現(xiàn)無數(shù)個(gè)“明明代碼沒問題但就是報(bào)錯(cuò)”的詭異情況。這一節(jié)是我在各項(xiàng)目里總結(jié)的最容易出問題的幾個(gè)概念優(yōu)先級(jí)極高。2.1 CorpID、AgentId、Secret 三者關(guān)系第一次接觸企業(yè)微信API的人十個(gè)里有九個(gè)會(huì)被這三個(gè)ID搞暈。我用一句話幫你記住它們的關(guān)系CorpID企業(yè)ID整個(gè)企業(yè)的唯一身份標(biāo)識(shí)相當(dāng)于企業(yè)的“身份證號(hào)”一個(gè)企業(yè)只有一個(gè)。AgentId應(yīng)用ID你在企業(yè)微信里創(chuàng)建的每一個(gè)自建應(yīng)用都有一個(gè)獨(dú)立的AgentId。一個(gè)企業(yè)可以建很多個(gè)應(yīng)用每個(gè)應(yīng)用各管一攤事。Secret應(yīng)用密鑰每個(gè)應(yīng)用獨(dú)立的密碼調(diào)用接口時(shí)用它和CorpID換令牌。Secret一定要保密泄露相當(dāng)于別人能用你的應(yīng)用亂發(fā)消息。為什么要分成三個(gè)因?yàn)檫@樣權(quán)限才能拆得細(xì)。比如人力資源部用A應(yīng)用、運(yùn)維部用B應(yīng)用兩邊Secret不同發(fā)的消息互不干擾出了事也能追責(zé)到具體應(yīng)用。實(shí)際項(xiàng)目里建議一個(gè)業(yè)務(wù)線用一個(gè)應(yīng)用別把所有功能塞進(jìn)一個(gè)應(yīng)用里。2.2 access_token唯一通行證怎么拿、怎么用、怎么緩存調(diào)用企業(yè)微信所有消息接口之前都要先拿到access_token。它相當(dāng)于你的“臨時(shí)通行證”有效期默認(rèn)7200秒2小時(shí)。獲取方式很簡(jiǎn)單拿著corpid和corpsecret調(diào)一個(gè)GET接口import requests corp_id ww1234567890abcdef secret 你的自建應(yīng)用Secret url https://qyapi.weixin.qq.com/cgi-bin/gettoken params { corpid: corp_id, corpsecret: secret, } resp requests.get(url, paramsparams) data resp.json() if data[errcode] 0: access_token data[access_token] expires_in data[expires_in] # 通常是7200秒 print(token獲取成功:, access_token) else: print(獲取失敗:, data)這里有一個(gè)極其重要的工程經(jīng)驗(yàn)token必須緩存不能每次請(qǐng)求都重新獲取。官方接口雖然沒寫死但實(shí)際有限流策略頻繁獲取token很容易觸發(fā)頻率限制。我項(xiàng)目的做法是把token存到內(nèi)存或Redis里過期時(shí)間設(shè)置為expires_in - 200秒提前刷新避免臨界點(diǎn)失效調(diào)用消息接口前先從緩存取取不到再重新獲取import time import requests class TokenManager: def __init__(self, corp_id, secret): self.corp_id corp_id self.secret secret self.token None self.expire_at 0 def get_token(self): if self.token and time.time() self.expire_at: return self.token url https://qyapi.weixin.qq.com/cgi-bin/gettoken params {corpid: self.corp_id, corpsecret: self.secret} data requests.get(url, paramsparams).json() if data[errcode] 0: self.token data[access_token] self.expire_at time.time() data[expires_in] - 200 return self.token raise Exception(token獲取失敗: str(data))這套封裝看起來不復(fù)雜但能解決實(shí)際項(xiàng)目里90%的token管理問題。2.3 權(quán)限、可信域名、IP白名單與可見范圍就算CorpID、Secret、AgentId全對(duì)了消息也不一定發(fā)得出去。這就是我最常遇到的問題權(quán)限配置不到位。企業(yè)微信對(duì)API調(diào)用是有“環(huán)境”約束的一般要檢查三個(gè)點(diǎn)1. 應(yīng)用的可見范圍自建應(yīng)用默認(rèn)只能給“可見范圍內(nèi)”的成員發(fā)消息。如果某些員工不在應(yīng)用可見范圍里你用接口給他們的userid發(fā)消息接口可能會(huì)返回成功但對(duì)方根本收不到。這個(gè)非?？右?yàn)椴皇菆?bào)錯(cuò)而是沉默失敗。2. 可信IP企業(yè)微信支持配置“企業(yè)可信IP”如果你的服務(wù)器公網(wǎng)IP不在白名單里調(diào)用一些敏感接口會(huì)直接返回60020之類的錯(cuò)誤碼。所以接到60020別懷疑代碼先去管理后臺(tái)把服務(wù)器公網(wǎng)IP加進(jìn)去。3. 回調(diào)域名如果你需要接收用戶發(fā)給應(yīng)用的消息那就要配置“接收消息”的回調(diào)URL并且要校驗(yàn)簽名、解密消息體。這一塊比較復(fù)雜不是發(fā)消息的必要條件但很多人在做私聊機(jī)器人時(shí)繞不開。3. 消息類型與媒體格式字段細(xì)節(jié)和避坑點(diǎn)這一節(jié)是全文的硬核部分。我直接按消息類型拆開講每一種都給出請(qǐng)求結(jié)構(gòu)里的核心字段以及我在實(shí)際調(diào)用中遇到過的坑。3.1 文本消息最簡(jiǎn)單但最容易忽略的細(xì)節(jié)發(fā)送文本消息是最基礎(chǔ)的但也別小看它。接口地址是message/send用POST請(qǐng)求JSON體大概是這樣的send_url fhttps://qyapi.weixin.qq.com/cgi-bin/message/send?access_token{access_token} text_payload { touser: zhangsan|lisi, toparty: 2, totag: 3, msgtype: text, agentid: 1000002, text: { content: 這是一條來自接口的測(cè)試消息 }, safe: 0 } resp requests.post(send_url, jsontext_payload) print(resp.json())有幾個(gè)細(xì)節(jié)值得注意touser、toparty、totag可以單獨(dú)用也可以組合用多個(gè)值用|分隔。但注意不能三個(gè)字段都為空不然不知道發(fā)給誰。safe字段是“保密消息”開關(guān)設(shè)為1表示消息不可被轉(zhuǎn)發(fā)適合發(fā)合同、薪資等敏感內(nèi)容。文本內(nèi)容長(zhǎng)度有限制正常業(yè)務(wù)一般夠用但要注意別把超長(zhǎng)日志直接塞進(jìn)去我遇到過因?yàn)橄⑦^長(zhǎng)被接口拒絕的情況。agentid是你的自建應(yīng)用ID發(fā)消息時(shí)一定要帶否則接口不知道該以哪個(gè)應(yīng)用的身份發(fā)送。3.2 圖片、語音、視頻、文件臨時(shí)素材與media_id機(jī)制這是“多種媒體格式”的核心。企業(yè)微信不允許你直接傳一個(gè)URL或者文件內(nèi)容來發(fā)消息而是要求你先把文件上傳到企業(yè)微信服務(wù)器拿到一個(gè)media_id然后用這個(gè)media_id去發(fā)消息?？梢岳斫鉃橄却嬉粋€(gè)臨時(shí)網(wǎng)盤再引用網(wǎng)盤里文件的ID。臨時(shí)素材上傳接口upload_url fhttps://qyapi.weixin.qq.com/cgi-bin/media/upload?access_token{access_token}typeimage with open(screenshot.png, rb) as f: files {media: f} resp requests.post(upload_url, filesfiles) media_id resp.json().get(media_id) print(media_id:, media_id)上傳時(shí)注意type參數(shù)要與消息類型一致一共有image、voice、video、file四種。上傳成功后發(fā)消息時(shí)這樣構(gòu)造image_payload { touser: zhangsan, msgtype: image, agentid: 1000002, image: { media_id: media_id }, safe: 0 }針對(duì)不同類型我整理了一張限制表都是我實(shí)測(cè)驗(yàn)證過的直接抄就行媒體類型上傳type值最大大小支持格式發(fā)送時(shí)字段圖片image2MBjpg、png、bmp等image.media_id語音voice2MBamrvoice.media_id視頻video10MBmp4video.media_id普通文件file20MB任意file.media_id關(guān)于這張表有幾個(gè)實(shí)戰(zhàn)經(jīng)驗(yàn)值得重點(diǎn)說圖片雖然叫圖片但不要以為jpg就一定行如果你發(fā)的是截圖之類超大尺寸的PNG很容易超過2MB。我以前做告警推送時(shí)監(jiān)控系統(tǒng)生成的截圖動(dòng)不動(dòng)就3MB后來統(tǒng)一在本地壓縮一遍再上傳才解決問題。語音格式支持amr不是mp3。微信體系里的語音基本都是amr如果你手里是mp3要先轉(zhuǎn)碼。臨時(shí)素材默認(rèn)有效期是3天但消息接口發(fā)送完基本就不用管它了因?yàn)橄⒁呀?jīng)真實(shí)抵達(dá)客戶端。如果你只上傳不發(fā)送注意過幾天media_id就失效了。上傳素材的接口本身就是單獨(dú)的頻率限制批量推送時(shí)必須控制并發(fā)否則會(huì)觸發(fā)限流。官方推薦頻繁發(fā)送的文件可以用“永久素材”接口臨時(shí)素材適合一次性推送場(chǎng)景。多數(shù)場(chǎng)景下臨時(shí)素材夠用。3.3 圖文news不用上傳素材也能發(fā)卡片消息圖文消息news是我個(gè)人覺得最實(shí)用的消息類型。它不需要上傳素材直接在請(qǐng)求體里寫一個(gè)articles數(shù)組就能生成一條像公眾號(hào)推送一樣的卡片消息?？ㄆ嫌袠?biāo)題、描述、封面圖、鏈接點(diǎn)一下就能跳轉(zhuǎn)。用來做運(yùn)營(yíng)通知、報(bào)表推送非常合適。news_payload { touser: zhangsan, msgtype: news, agentid: 1000002, news: { articles: [ { title: 7月數(shù)據(jù)報(bào)表已生成, description: 點(diǎn)擊查看完整報(bào)表, url: https://example.com/report, picurl: https://example.com/pic.jpg } ] } }字段里有兩個(gè)容易踩坑的點(diǎn)picurl必須是公網(wǎng)可訪問的圖片地址。我之前一偷懶填了個(gè)內(nèi)網(wǎng)地址結(jié)果消息發(fā)出去了但卡片圖片在手機(jī)上永遠(yuǎn)加載不出來。排查半天才發(fā)現(xiàn)是圖片地址的問題。articles數(shù)組最多支持8個(gè)元素但建議一個(gè)卡片就主打一個(gè)核心信息別塞太多條手機(jī)端用戶體驗(yàn)會(huì)好很多。3.4 群機(jī)器人webhook支持的媒體格式群機(jī)器人是“群聊”場(chǎng)景里最輕量的實(shí)現(xiàn)方式。webhook地址長(zhǎng)這樣https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx你可以直接在代碼里POST一個(gè)JSON往指定群里發(fā)消息。舉個(gè)例子發(fā)一條markdown格式的群消息webhook_url https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyxxxxxxxx markdown_payload { msgtype: markdown, markdown: { content: ## 服務(wù)上線提醒 \n 版本由 **v1.2.0** 更新至 **v1.3.0** } } resp requests.post(webhook_url, jsonmarkdown_payload) print(resp.json())群機(jī)器人支持的格式也不少文本text、markdown、圖片image、圖文news、文件file、語音voice等。注意幾點(diǎn)群機(jī)器人發(fā)圖片/文件也需要先傳素材拿media_id但要走webhook/upload_media這個(gè)接口不是上面提的media/upload。很多人第一次做把兩個(gè)接口混用就會(huì)報(bào)media_id無效。群里添加機(jī)器人時(shí)有一個(gè)“安全設(shè)置”如果你勾選了“關(guān)鍵詞”限制那消息內(nèi)容必須包含指定關(guān)鍵詞否則調(diào)用會(huì)報(bào)錯(cuò)。這個(gè)坑特別隱蔽報(bào)錯(cuò)信息也不直觀我第一次遇到時(shí)查了半天才發(fā)現(xiàn)是關(guān)鍵詞沒寫。webhook方式不需要access_token只需要webhook地址本身。所以任何人拿了這個(gè)地址都能往群里發(fā)消息地址泄露等于是把群聊的發(fā)言權(quán)交了出去要注意保護(hù)。4. 完整實(shí)操從配置應(yīng)用到發(fā)出一條群聊圖片前面講了不少原理這一節(jié)帶大家完整走一遍流程。我按“最可能遇到的真實(shí)場(chǎng)景”來串先是私聊文本然后私聊圖片最后往群里發(fā)markdown消息。4.1 前置準(zhǔn)備你需要先在企業(yè)微信管理后臺(tái)完成這些操作注冊(cè)企業(yè)微信獲得CorpID企業(yè)ID。在“應(yīng)用管理-自建”里創(chuàng)建一個(gè)自建應(yīng)用拿到AgentId和Secret。在“管理后臺(tái)-我的企業(yè)-可信信息”里配置你的服務(wù)器公網(wǎng)IP為企業(yè)可信IP。如果要體驗(yàn)群聊任意創(chuàng)建一個(gè)內(nèi)部群在群設(shè)置里添加“群機(jī)器人”復(fù)制webhook地址。準(zhǔn)備一個(gè)小型測(cè)試文件比如一張小于2MB的圖片test.png。這些步驟都是后臺(tái)點(diǎn)點(diǎn)點(diǎn)不涉及代碼但一定要做對(duì)。尤其是第3步很多人都忽略了。4.2 獲取并緩存access_token代碼直接復(fù)用第2部分寫的TokenManager類。如果你用Flask或FastAPI寫服務(wù)可以在應(yīng)用啟動(dòng)時(shí)初始化一個(gè)全局的TokenManager實(shí)例token_mgr TokenManager(corp_idww1234567890abcdef, secret你自己的應(yīng)用Secret) # 在發(fā)送函數(shù)里獲取token token token_mgr.get_token()這里再補(bǔ)一個(gè)細(xì)節(jié)如果你的服務(wù)是多進(jìn)程或多實(shí)例部署用內(nèi)存緩存會(huì)導(dǎo)致每個(gè)進(jìn)程各自維護(hù)一個(gè)token有一半請(qǐng)求的token可能是過期的。生產(chǎn)環(huán)境建議把token放Rediskey名帶上corpid和secret的哈希值實(shí)現(xiàn)全局共享。4.3 發(fā)送純文本私聊消息現(xiàn)在開始第一發(fā)。假設(shè)你要給userid為zhangsan的員工發(fā)一條純文本消息send_url fhttps://qyapi.weixin.qq.com/cgi-bin/message/send?access_token{token} payload { touser: zhangsan, msgtype: text, agentid: 1000002, text: { content: 你好你的工單已處理完成。 } } resp requests.post(send_url, jsonpayload) data resp.json() print(data)如果返回結(jié)果errcode為0說明消息已成功進(jìn)入發(fā)送隊(duì)列。注意接口返回成功不代表對(duì)方已經(jīng)“已讀”也不代表網(wǎng)絡(luò)送達(dá)但正常情況下幾秒內(nèi)就會(huì)在客戶端出現(xiàn)。這里有個(gè)小技巧接口返回后如果你能獲取到消息的msgid可以在后續(xù)做更多追蹤。不過這個(gè)接口的返回里通常不包含msgid別強(qiáng)求。4.4 上傳臨時(shí)素材并發(fā)圖片消息下面來個(gè)更復(fù)雜的發(fā)一張圖片。先上傳素材再發(fā)消息# 第一步上傳臨時(shí)素材 upload_url fhttps://qyapi.weixin.qq.com/cgi-bin/media/upload?access_token{token}typeimage with open(test.png, rb) as f: resp requests.post(upload_url, files{media: f}) data resp.json() if data[errcode] ! 0: print(上傳失敗:, data) exit(1) media_id data[media_id] print(拿到media_id:, media_id) # 第二步發(fā)送圖片消息 send_url fhttps://qyapi.weixin.qq.com/cgi-bin/message/send?access_token{token} image_payload { touser: zhangsan, msgtype: image, agentid: 1000002, image: { media_id: media_id } } resp requests.post(send_url, jsonimage_payload) print(resp.json())我在實(shí)際開發(fā)時(shí)會(huì)把“上傳素材”封裝成一個(gè)通用函數(shù)內(nèi)部處理文件大小超限、格式校驗(yàn)、失敗重試等邏輯。因?yàn)樵谂客扑偷膱?chǎng)景里可能一次要發(fā)幾十張圖如果每個(gè)環(huán)節(jié)都手寫代碼會(huì)非常臃腫。封裝之后的調(diào)用長(zhǎng)這樣def send_image(token, to_user, media_id, agent_id): payload { touser: to_user, msgtype: image, agentid: agent_id, image: {media_id: media_id} } return requests.post( fhttps://qyapi.weixin.qq.com/cgi-bin/message/send?access_token{token}, jsonpayload ).json()4.5 通過群機(jī)器人往群聊發(fā)markdown消息最后展示怎么往群里發(fā)消息。這里不通過access_token而是直接調(diào)webhookwebhook_url https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyxxxxx payload { msgtype: markdown, markdown: { content: ## 監(jiān)控告警 \n 線上服務(wù)異常率超過5%請(qǐng)及時(shí)處理。\n 時(shí)間點(diǎn)2026-03-20 10:30:00 } } resp requests.post(webhook_url, jsonpayload) print(resp.json())如果群里給機(jī)器人配置了“關(guān)鍵詞”markdown內(nèi)容里必須包含那個(gè)關(guān)鍵詞。比如你配置的關(guān)鍵詞是“告警”上面這條消息里最好明確帶“告警”兩個(gè)字否則返回如下錯(cuò)誤{errcode:93000,errmsg:invalid webhook url, please check the webhook info}這個(gè)報(bào)錯(cuò)非常迷惑看起來像是webhook地址無效實(shí)際是安全設(shè)置攔截。我第一次做的時(shí)候被它坑了整整一下午。5. 高頻踩坑記錄與排錯(cuò)參考把我在項(xiàng)目里遇到過的所有問題匯總成一張表你收藏這份以后調(diào)接口遇到報(bào)錯(cuò)直接對(duì)號(hào)入座。5.1 返回碼快速排查表返回碼含義常見原因處理建議0成功無無需處理40001access_token無效token過期、緩存被清、重新獲取導(dǎo)致舊token失效重新獲取token用新token重試40003userid不合法用戶不在通訊錄、不是應(yīng)用的可見范圍檢查userid大小寫、同步通訊錄、擴(kuò)大應(yīng)用可見范圍40013corpid不合法配置的corpid寫錯(cuò)了去管理后臺(tái)核對(duì)40014access_token不合法token錯(cuò)誤或已被覆蓋重新獲取token41030media_id無效素材類型不匹配、素材過期、用錯(cuò)上傳接口重新上傳素材檢查type參數(shù)45009接口調(diào)用超過頻率限制并發(fā)過高、循環(huán)調(diào)用、token重復(fù)獲取加本地隊(duì)列控制調(diào)用頻率批量消息分批發(fā)送60011無權(quán)限訪問應(yīng)用沒有通訊錄權(quán)限、Secret不對(duì)應(yīng)檢查應(yīng)用權(quán)限設(shè)置確認(rèn)Secret與AgentId匹配60020訪問來源IP不在白名單服務(wù)器公網(wǎng)IP未加入可信IP去管理后臺(tái)配置可信IP93000群機(jī)器人消息被攔截webhook地址不對(duì)、安全設(shè)置關(guān)鍵詞不匹配檢查webhook地址核對(duì)關(guān)鍵詞規(guī)則5.2 幾個(gè)典型問題實(shí)錄除了返回碼我在項(xiàng)目里實(shí)際踩過的幾個(gè)場(chǎng)景也值得單獨(dú)說。場(chǎng)景一接口返回成功但員工就是收不到消息這是最讓我頭疼的問題。代碼檢查了很多遍返回碼始終是0但員工的企業(yè)微信里就是沒有新消息。排查到最后發(fā)現(xiàn)這個(gè)應(yīng)用在企業(yè)微信后臺(tái)里從來沒被員工“使用”過而且可見范圍也跟員工無關(guān)。說白了你在后臺(tái)把應(yīng)用可見范圍設(shè)成了“研發(fā)部”但給一個(gè)“市場(chǎng)部”的人發(fā)消息接口可能不會(huì)直接報(bào)錯(cuò)而是默默丟棄。所以收到0也別高興太早先確認(rèn)接收人是否在可見范圍里。場(chǎng)景二給部門發(fā)廣播返回60011我當(dāng)時(shí)想給某個(gè)部門發(fā)通知toparty填的是部門ID但一直返回60011提示沒有權(quán)限。原因是應(yīng)用可見范圍只勾選了“全體成員”里的某幾個(gè)部門沒有單獨(dú)把這個(gè)部門勾進(jìn)去。有些你以為是后臺(tái)配置的問題其實(shí)是“可見范圍”和“通訊錄權(quán)限”兩個(gè)概念混在一起要同時(shí)滿足。場(chǎng)景三群機(jī)器人發(fā)圖片報(bào)media_id無效前面提過群機(jī)器人上傳素材的接口是/webhook/upload_media但是很多人包括我容易下意識(shí)直接用/media/upload。這兩個(gè)接口返回的media_id格式都差不多但互相不通用。所以如果你確認(rèn)token沒有過期、圖片也沒超2MB但報(bào)media_id無效趕緊看看是不是用的上傳接口不對(duì)。場(chǎng)景四文本消息內(nèi)容里帶中文或特殊符號(hào)出現(xiàn)亂碼這個(gè)問題主要出現(xiàn)在一些老舊的HTTP客戶端上設(shè)置請(qǐng)求頭的時(shí)候沒指定UTF-8編碼。企業(yè)微信接口是標(biāo)準(zhǔn)的UTF-8所以Content-Type一定要寫成application/json; charsetutf-8。requests庫默認(rèn)會(huì)處理好但如果自己用其他語言寫SDK就要注意。最后分享幾點(diǎn)我的個(gè)人體會(huì)接口文檔寫得很全但是“能跑通”和“在生產(chǎn)環(huán)境中穩(wěn)定跑”之間還隔著大量細(xì)節(jié)。我在做了好幾個(gè)類似項(xiàng)目之后最大的感受是一定要在項(xiàng)目初期設(shè)計(jì)一個(gè)統(tǒng)一的消息服務(wù)層把token緩存、素材上傳、消息發(fā)送、重試邏輯全部封裝好不要讓業(yè)務(wù)代碼直接裸調(diào)接口。這樣后面接更多消息類型時(shí)只改服務(wù)層就夠了不用動(dòng)上層業(yè)務(wù)。另外不管你用py、Java還是Go先做小范圍灰度。我的習(xí)慣是先把代碼寫一個(gè)命令行腳本手動(dòng)發(fā)給自己和測(cè)試號(hào)逐項(xiàng)驗(yàn)證文本、圖片、文件和群機(jī)器人消息類型全部跑通再接入業(yè)務(wù)系統(tǒng)。別一上來就做批量推送否則限流、權(quán)限、media_id過期這些問題混在一起你會(huì)被搞得懷疑人生。企業(yè)微信消息接口的價(jià)值不在于“能發(fā)消息”這個(gè)動(dòng)作而在于它可以被程序化地整合進(jìn)你的運(yùn)維系統(tǒng)、報(bào)表系統(tǒng)、客戶運(yùn)營(yíng)系統(tǒng)成為整個(gè)自動(dòng)化工作流里最接近人的一環(huán)。先把私聊文本跑通再逐步加上圖片、視頻、群機(jī)器人你會(huì)發(fā)現(xiàn)這套API能做的事情遠(yuǎn)比想象中要多得多。 企業(yè)微信API發(fā)消息接口實(shí)戰(zhàn)：私聊、群聊與媒體格式詳解
上周有個(gè)做運(yùn)維的朋友跑來找我問能不能讓服務(wù)器定時(shí)往員工的企業(yè)微信里推日?qǐng)?bào)往部門群發(fā)告警圖片甚至給客戶群群發(fā)帶附件的資料。聊下來發(fā)現(xiàn)他最困惑的點(diǎn)不是“接口長(zhǎng)什么樣”而是企業(yè)微信發(fā)消息這回事其實(shí)被拆成了好幾條完全不同的通道給成員個(gè)人發(fā)私聊消息、按部門或標(biāo)簽做廣播、往群里發(fā)機(jī)器人消息、給外部客戶群群發(fā)各自對(duì)應(yīng)的接口和權(quán)限都不一樣。這篇就圍繞“企業(yè)微信 API 發(fā)消息接口”這個(gè)主題把私聊、群聊、多種媒體格式以及我在真實(shí)項(xiàng)目里調(diào)通的完整流程、踩過的坑一次說清楚。這文章適合誰看只要你的工作里需要寫代碼調(diào)用企業(yè)微信接口不管是做自動(dòng)化告警、報(bào)表推送、內(nèi)部通知系統(tǒng)還是做客戶運(yùn)營(yíng)消息觸達(dá)都能從中找到可以直接抄走的思路和代碼。下面所有內(nèi)容都基于我在真實(shí)項(xiàng)目中反復(fù)驗(yàn)證過的方案不同基礎(chǔ)的人照著搭都能跑通。1. 先理清楚企業(yè)微信消息接口到底有哪幾類玩法很多人一聽“企業(yè)微信API發(fā)消息”下意識(shí)以為就是一個(gè)接口把消息發(fā)出去就行。實(shí)際沒那么簡(jiǎn)單。企業(yè)微信把“發(fā)消息”分成了好幾條不同的通道每條通道的權(quán)限模型、調(diào)用方式、能發(fā)什么格式都不一樣。如果不先搞清楚這些代碼寫了一半才發(fā)現(xiàn)權(quán)限不對(duì)、格式不支持返工成本非常高。1.1 “私聊”不只是點(diǎn)對(duì)點(diǎn)自建應(yīng)用消息通道在標(biāo)題里說到的“私聊”在企業(yè)微信API里最典型的實(shí)現(xiàn)路徑是自建應(yīng)用消息。你在企業(yè)微信管理后臺(tái)創(chuàng)建了一個(gè)自建應(yīng)用然后通過這個(gè)應(yīng)用給指定成員發(fā)消息。這里的“私聊”不是指兩個(gè)員工之間互相聊天而是指系統(tǒng)通過應(yīng)用給某個(gè)員工發(fā)一對(duì)一的對(duì)話消息。這個(gè)通道能干的事情非常多。比如我做過的一個(gè)模擬項(xiàng)目X每天定時(shí)推送前一天的運(yùn)營(yíng)數(shù)據(jù)給各業(yè)務(wù)負(fù)責(zé)人用的就是這種通道。它的核心特點(diǎn)是按userid精確指定接收人一個(gè)接口調(diào)用可以傳多個(gè)userid用|分隔也支持按部門IDpartyid和標(biāo)簽IDtagid批量發(fā)送這種就帶了“群發(fā)/廣播”的味道消息類型齊全文本、圖片、語音、視頻、文件、圖文卡片都能發(fā)消息出現(xiàn)在企業(yè)微信的“工作臺(tái)-應(yīng)用”會(huì)話里本質(zhì)上就是一次真實(shí)的企業(yè)微信對(duì)話我后來總結(jié)了一個(gè)經(jīng)驗(yàn)如果你的業(yè)務(wù)場(chǎng)景是“系統(tǒng)主動(dòng)找人”就選自建應(yīng)用消息通道如果是“人主動(dòng)找系統(tǒng)聊天”那就要再配置消息接收回調(diào)做一套對(duì)話機(jī)器人。但那是另一個(gè)項(xiàng)目了這里先不展開。1.2 “群聊”的幾種實(shí)現(xiàn)路徑群機(jī)器人、部門群發(fā)與客戶群群發(fā)標(biāo)題里的“群聊”是一個(gè)容易混淆的點(diǎn)因?yàn)橹辽儆腥龡l路都叫“群聊”。我實(shí)際測(cè)試下來三條路的適用場(chǎng)景差異很大這里直接給結(jié)論路徑一群機(jī)器人webhook在企業(yè)微信任意一個(gè)群里可以添加一個(gè)“群機(jī)器人”。添加之后會(huì)生成一個(gè)webhook地址代碼里往這個(gè)地址POST一段JSON就能把消息推到那個(gè)具體群里。這個(gè)方案最輕量不需要申請(qǐng)接口權(quán)限不用配可信域名是個(gè)人開發(fā)者最快能體驗(yàn)“發(fā)群消息”的方式。路徑二給部門/標(biāo)簽發(fā)廣播自建應(yīng)用消息除了指定單人也可以指定toparty或totag。比如給“研發(fā)部”整個(gè)部門發(fā)通知給“全體成員”標(biāo)簽發(fā)公告。這種方式在企業(yè)內(nèi)部用得最多適合做全員通知、部門公告。路徑三客戶群群發(fā)這是運(yùn)營(yíng)向的場(chǎng)景通過“客戶聯(lián)系”相關(guān)接口給外部客戶的微信群做群發(fā)。這個(gè)接口的權(quán)限模型更嚴(yán)需要單獨(dú)配置客戶聯(lián)系Secret而且要提前創(chuàng)建群發(fā)任務(wù)。如果你只是做內(nèi)部自動(dòng)化通知基本用不上這條路。我在文末會(huì)提一下什么時(shí)候才需要考慮它。1.3 為什么標(biāo)題強(qiáng)調(diào)“多種媒體格式”“多種媒體格式”是企業(yè)微信消息接口相比其他聊天軟件接口最實(shí)用的一點(diǎn)。你不只能發(fā)純文字還能把圖片、語音、視頻、普通文件、圖文卡片都發(fā)到成員會(huì)話或群里。這帶來一個(gè)直接的業(yè)務(wù)價(jià)值告警系統(tǒng)不僅報(bào)一句“服務(wù)器負(fù)載高了”還能附帶一張監(jiān)控截圖報(bào)表系統(tǒng)不止發(fā)一串?dāng)?shù)字還能推送一個(gè)圖文卡片點(diǎn)進(jìn)去就是完整看板運(yùn)營(yíng)系統(tǒng)給客戶群發(fā)資料PDF文件直接推送。可以說媒體格式的豐富程度決定了這個(gè)接口能承載多少真實(shí)業(yè)務(wù)場(chǎng)景。但每種媒體格式都有自己的限制比如圖片不能超過2MB、視頻不能超過10MB、文件不能超過20MB而且要先用“臨時(shí)素材上傳接口”拿到一個(gè)media_id才能發(fā)送。這些細(xì)節(jié)我在第3部分專門展開講。2. 接入前必須搞懂的幾個(gè)關(guān)鍵概念調(diào)用企業(yè)微信API之前如果不先把幾個(gè)核心概念理清楚后面會(huì)出現(xiàn)無數(shù)個(gè)“明明代碼沒問題但就是報(bào)錯(cuò)”的詭異情況。這一節(jié)是我在各項(xiàng)目里總結(jié)的最容易出問題的幾個(gè)概念優(yōu)先級(jí)極高。2.1 CorpID、AgentId、Secret 三者關(guān)系第一次接觸企業(yè)微信API的人十個(gè)里有九個(gè)會(huì)被這三個(gè)ID搞暈。我用一句話幫你記住它們的關(guān)系CorpID企業(yè)ID整個(gè)企業(yè)的唯一身份標(biāo)識(shí)相當(dāng)于企業(yè)的“身份證號(hào)”一個(gè)企業(yè)只有一個(gè)。AgentId應(yīng)用ID你在企業(yè)微信里創(chuàng)建的每一個(gè)自建應(yīng)用都有一個(gè)獨(dú)立的AgentId。一個(gè)企業(yè)可以建很多個(gè)應(yīng)用每個(gè)應(yīng)用各管一攤事。Secret應(yīng)用密鑰每個(gè)應(yīng)用獨(dú)立的密碼調(diào)用接口時(shí)用它和CorpID換令牌。Secret一定要保密泄露相當(dāng)于別人能用你的應(yīng)用亂發(fā)消息。為什么要分成三個(gè)因?yàn)檫@樣權(quán)限才能拆得細(xì)。比如人力資源部用A應(yīng)用、運(yùn)維部用B應(yīng)用兩邊Secret不同發(fā)的消息互不干擾出了事也能追責(zé)到具體應(yīng)用。實(shí)際項(xiàng)目里建議一個(gè)業(yè)務(wù)線用一個(gè)應(yīng)用別把所有功能塞進(jìn)一個(gè)應(yīng)用里。2.2 access_token唯一通行證怎么拿、怎么用、怎么緩存調(diào)用企業(yè)微信所有消息接口之前都要先拿到access_token。它相當(dāng)于你的“臨時(shí)通行證”有效期默認(rèn)7200秒2小時(shí)。獲取方式很簡(jiǎn)單拿著corpid和corpsecret調(diào)一個(gè)GET接口import requests corp_id ww1234567890abcdef secret 你的自建應(yīng)用Secret url https://qyapi.weixin.qq.com/cgi-bin/gettoken params { corpid: corp_id, corpsecret: secret, } resp requests.get(url, paramsparams) data resp.json() if data[errcode] 0: access_token data[access_token] expires_in data[expires_in] # 通常是7200秒 print(token獲取成功:, access_token) else: print(獲取失敗:, data)這里有一個(gè)極其重要的工程經(jīng)驗(yàn)token必須緩存不能每次請(qǐng)求都重新獲取。官方接口雖然沒寫死但實(shí)際有限流策略頻繁獲取token很容易觸發(fā)頻率限制。我項(xiàng)目的做法是把token存到內(nèi)存或Redis里過期時(shí)間設(shè)置為expires_in - 200秒提前刷新避免臨界點(diǎn)失效調(diào)用消息接口前先從緩存取取不到再重新獲取import time import requests class TokenManager: def __init__(self, corp_id, secret): self.corp_id corp_id self.secret secret self.token None self.expire_at 0 def get_token(self): if self.token and time.time() self.expire_at: return self.token url https://qyapi.weixin.qq.com/cgi-bin/gettoken params {corpid: self.corp_id, corpsecret: self.secret} data requests.get(url, paramsparams).json() if data[errcode] 0: self.token data[access_token] self.expire_at time.time() data[expires_in] - 200 return self.token raise Exception(token獲取失敗: str(data))這套封裝看起來不復(fù)雜但能解決實(shí)際項(xiàng)目里90%的token管理問題。2.3 權(quán)限、可信域名、IP白名單與可見范圍就算CorpID、Secret、AgentId全對(duì)了消息也不一定發(fā)得出去。這就是我最常遇到的問題權(quán)限配置不到位。企業(yè)微信對(duì)API調(diào)用是有“環(huán)境”約束的一般要檢查三個(gè)點(diǎn)1. 應(yīng)用的可見范圍自建應(yīng)用默認(rèn)只能給“可見范圍內(nèi)”的成員發(fā)消息。如果某些員工不在應(yīng)用可見范圍里你用接口給他們的userid發(fā)消息接口可能會(huì)返回成功但對(duì)方根本收不到。這個(gè)非?？右?yàn)椴皇菆?bào)錯(cuò)而是沉默失敗。2. 可信IP企業(yè)微信支持配置“企業(yè)可信IP”如果你的服務(wù)器公網(wǎng)IP不在白名單里調(diào)用一些敏感接口會(huì)直接返回60020之類的錯(cuò)誤碼。所以接到60020別懷疑代碼先去管理后臺(tái)把服務(wù)器公網(wǎng)IP加進(jìn)去。3. 回調(diào)域名如果你需要接收用戶發(fā)給應(yīng)用的消息那就要配置“接收消息”的回調(diào)URL并且要校驗(yàn)簽名、解密消息體。這一塊比較復(fù)雜不是發(fā)消息的必要條件但很多人在做私聊機(jī)器人時(shí)繞不開。3. 消息類型與媒體格式字段細(xì)節(jié)和避坑點(diǎn)這一節(jié)是全文的硬核部分。我直接按消息類型拆開講每一種都給出請(qǐng)求結(jié)構(gòu)里的核心字段以及我在實(shí)際調(diào)用中遇到過的坑。3.1 文本消息最簡(jiǎn)單但最容易忽略的細(xì)節(jié)發(fā)送文本消息是最基礎(chǔ)的但也別小看它。接口地址是message/send用POST請(qǐng)求JSON體大概是這樣的send_url fhttps://qyapi.weixin.qq.com/cgi-bin/message/send?access_token{access_token} text_payload { touser: zhangsan|lisi, toparty: 2, totag: 3, msgtype: text, agentid: 1000002, text: { content: 這是一條來自接口的測(cè)試消息 }, safe: 0 } resp requests.post(send_url, jsontext_payload) print(resp.json())有幾個(gè)細(xì)節(jié)值得注意touser、toparty、totag可以單獨(dú)用也可以組合用多個(gè)值用|分隔。但注意不能三個(gè)字段都為空不然不知道發(fā)給誰。safe字段是“保密消息”開關(guān)設(shè)為1表示消息不可被轉(zhuǎn)發(fā)適合發(fā)合同、薪資等敏感內(nèi)容。文本內(nèi)容長(zhǎng)度有限制正常業(yè)務(wù)一般夠用但要注意別把超長(zhǎng)日志直接塞進(jìn)去我遇到過因?yàn)橄⑦^長(zhǎng)被接口拒絕的情況。agentid是你的自建應(yīng)用ID發(fā)消息時(shí)一定要帶否則接口不知道該以哪個(gè)應(yīng)用的身份發(fā)送。3.2 圖片、語音、視頻、文件臨時(shí)素材與media_id機(jī)制這是“多種媒體格式”的核心。企業(yè)微信不允許你直接傳一個(gè)URL或者文件內(nèi)容來發(fā)消息而是要求你先把文件上傳到企業(yè)微信服務(wù)器拿到一個(gè)media_id然后用這個(gè)media_id去發(fā)消息?？梢岳斫鉃橄却嬉粋€(gè)臨時(shí)網(wǎng)盤再引用網(wǎng)盤里文件的ID。臨時(shí)素材上傳接口upload_url fhttps://qyapi.weixin.qq.com/cgi-bin/media/upload?access_token{access_token}typeimage with open(screenshot.png, rb) as f: files {media: f} resp requests.post(upload_url, filesfiles) media_id resp.json().get(media_id) print(media_id:, media_id)上傳時(shí)注意type參數(shù)要與消息類型一致一共有image、voice、video、file四種。上傳成功后發(fā)消息時(shí)這樣構(gòu)造image_payload { touser: zhangsan, msgtype: image, agentid: 1000002, image: { media_id: media_id }, safe: 0 }針對(duì)不同類型我整理了一張限制表都是我實(shí)測(cè)驗(yàn)證過的直接抄就行媒體類型上傳type值最大大小支持格式發(fā)送時(shí)字段圖片image2MBjpg、png、bmp等image.media_id語音voice2MBamrvoice.media_id視頻video10MBmp4video.media_id普通文件file20MB任意file.media_id關(guān)于這張表有幾個(gè)實(shí)戰(zhàn)經(jīng)驗(yàn)值得重點(diǎn)說圖片雖然叫圖片但不要以為jpg就一定行如果你發(fā)的是截圖之類超大尺寸的PNG很容易超過2MB。我以前做告警推送時(shí)監(jiān)控系統(tǒng)生成的截圖動(dòng)不動(dòng)就3MB后來統(tǒng)一在本地壓縮一遍再上傳才解決問題。語音格式支持amr不是mp3。微信體系里的語音基本都是amr如果你手里是mp3要先轉(zhuǎn)碼。臨時(shí)素材默認(rèn)有效期是3天但消息接口發(fā)送完基本就不用管它了因?yàn)橄⒁呀?jīng)真實(shí)抵達(dá)客戶端。如果你只上傳不發(fā)送注意過幾天media_id就失效了。上傳素材的接口本身就是單獨(dú)的頻率限制批量推送時(shí)必須控制并發(fā)否則會(huì)觸發(fā)限流。官方推薦頻繁發(fā)送的文件可以用“永久素材”接口臨時(shí)素材適合一次性推送場(chǎng)景。多數(shù)場(chǎng)景下臨時(shí)素材夠用。3.3 圖文news不用上傳素材也能發(fā)卡片消息圖文消息news是我個(gè)人覺得最實(shí)用的消息類型。它不需要上傳素材直接在請(qǐng)求體里寫一個(gè)articles數(shù)組就能生成一條像公眾號(hào)推送一樣的卡片消息?？ㄆ嫌袠?biāo)題、描述、封面圖、鏈接點(diǎn)一下就能跳轉(zhuǎn)。用來做運(yùn)營(yíng)通知、報(bào)表推送非常合適。news_payload { touser: zhangsan, msgtype: news, agentid: 1000002, news: { articles: [ { title: 7月數(shù)據(jù)報(bào)表已生成, description: 點(diǎn)擊查看完整報(bào)表, url: https://example.com/report, picurl: https://example.com/pic.jpg } ] } }字段里有兩個(gè)容易踩坑的點(diǎn)picurl必須是公網(wǎng)可訪問的圖片地址。我之前一偷懶填了個(gè)內(nèi)網(wǎng)地址結(jié)果消息發(fā)出去了但卡片圖片在手機(jī)上永遠(yuǎn)加載不出來。排查半天才發(fā)現(xiàn)是圖片地址的問題。articles數(shù)組最多支持8個(gè)元素但建議一個(gè)卡片就主打一個(gè)核心信息別塞太多條手機(jī)端用戶體驗(yàn)會(huì)好很多。3.4 群機(jī)器人webhook支持的媒體格式群機(jī)器人是“群聊”場(chǎng)景里最輕量的實(shí)現(xiàn)方式。webhook地址長(zhǎng)這樣https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx你可以直接在代碼里POST一個(gè)JSON往指定群里發(fā)消息。舉個(gè)例子發(fā)一條markdown格式的群消息webhook_url https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyxxxxxxxx markdown_payload { msgtype: markdown, markdown: { content: ## 服務(wù)上線提醒 \n 版本由 **v1.2.0** 更新至 **v1.3.0** } } resp requests.post(webhook_url, jsonmarkdown_payload) print(resp.json())群機(jī)器人支持的格式也不少文本text、markdown、圖片image、圖文news、文件file、語音voice等。注意幾點(diǎn)群機(jī)器人發(fā)圖片/文件也需要先傳素材拿media_id但要走webhook/upload_media這個(gè)接口不是上面提的media/upload。很多人第一次做把兩個(gè)接口混用就會(huì)報(bào)media_id無效。群里添加機(jī)器人時(shí)有一個(gè)“安全設(shè)置”如果你勾選了“關(guān)鍵詞”限制那消息內(nèi)容必須包含指定關(guān)鍵詞否則調(diào)用會(huì)報(bào)錯(cuò)。這個(gè)坑特別隱蔽報(bào)錯(cuò)信息也不直觀我第一次遇到時(shí)查了半天才發(fā)現(xiàn)是關(guān)鍵詞沒寫。webhook方式不需要access_token只需要webhook地址本身。所以任何人拿了這個(gè)地址都能往群里發(fā)消息地址泄露等于是把群聊的發(fā)言權(quán)交了出去要注意保護(hù)。4. 完整實(shí)操從配置應(yīng)用到發(fā)出一條群聊圖片前面講了不少原理這一節(jié)帶大家完整走一遍流程。我按“最可能遇到的真實(shí)場(chǎng)景”來串先是私聊文本然后私聊圖片最后往群里發(fā)markdown消息。4.1 前置準(zhǔn)備你需要先在企業(yè)微信管理后臺(tái)完成這些操作注冊(cè)企業(yè)微信獲得CorpID企業(yè)ID。在“應(yīng)用管理-自建”里創(chuàng)建一個(gè)自建應(yīng)用拿到AgentId和Secret。在“管理后臺(tái)-我的企業(yè)-可信信息”里配置你的服務(wù)器公網(wǎng)IP為企業(yè)可信IP。如果要體驗(yàn)群聊任意創(chuàng)建一個(gè)內(nèi)部群在群設(shè)置里添加“群機(jī)器人”復(fù)制webhook地址。準(zhǔn)備一個(gè)小型測(cè)試文件比如一張小于2MB的圖片test.png。這些步驟都是后臺(tái)點(diǎn)點(diǎn)點(diǎn)不涉及代碼但一定要做對(duì)。尤其是第3步很多人都忽略了。4.2 獲取并緩存access_token代碼直接復(fù)用第2部分寫的TokenManager類。如果你用Flask或FastAPI寫服務(wù)可以在應(yīng)用啟動(dòng)時(shí)初始化一個(gè)全局的TokenManager實(shí)例token_mgr TokenManager(corp_idww1234567890abcdef, secret你自己的應(yīng)用Secret) # 在發(fā)送函數(shù)里獲取token token token_mgr.get_token()這里再補(bǔ)一個(gè)細(xì)節(jié)如果你的服務(wù)是多進(jìn)程或多實(shí)例部署用內(nèi)存緩存會(huì)導(dǎo)致每個(gè)進(jìn)程各自維護(hù)一個(gè)token有一半請(qǐng)求的token可能是過期的。生產(chǎn)環(huán)境建議把token放Rediskey名帶上corpid和secret的哈希值實(shí)現(xiàn)全局共享。4.3 發(fā)送純文本私聊消息現(xiàn)在開始第一發(fā)。假設(shè)你要給userid為zhangsan的員工發(fā)一條純文本消息send_url fhttps://qyapi.weixin.qq.com/cgi-bin/message/send?access_token{token} payload { touser: zhangsan, msgtype: text, agentid: 1000002, text: { content: 你好你的工單已處理完成。 } } resp requests.post(send_url, jsonpayload) data resp.json() print(data)如果返回結(jié)果errcode為0說明消息已成功進(jìn)入發(fā)送隊(duì)列。注意接口返回成功不代表對(duì)方已經(jīng)“已讀”也不代表網(wǎng)絡(luò)送達(dá)但正常情況下幾秒內(nèi)就會(huì)在客戶端出現(xiàn)。這里有個(gè)小技巧接口返回后如果你能獲取到消息的msgid可以在后續(xù)做更多追蹤。不過這個(gè)接口的返回里通常不包含msgid別強(qiáng)求。4.4 上傳臨時(shí)素材并發(fā)圖片消息下面來個(gè)更復(fù)雜的發(fā)一張圖片。先上傳素材再發(fā)消息# 第一步上傳臨時(shí)素材 upload_url fhttps://qyapi.weixin.qq.com/cgi-bin/media/upload?access_token{token}typeimage with open(test.png, rb) as f: resp requests.post(upload_url, files{media: f}) data resp.json() if data[errcode] ! 0: print(上傳失敗:, data) exit(1) media_id data[media_id] print(拿到media_id:, media_id) # 第二步發(fā)送圖片消息 send_url fhttps://qyapi.weixin.qq.com/cgi-bin/message/send?access_token{token} image_payload { touser: zhangsan, msgtype: image, agentid: 1000002, image: { media_id: media_id } } resp requests.post(send_url, jsonimage_payload) print(resp.json())我在實(shí)際開發(fā)時(shí)會(huì)把“上傳素材”封裝成一個(gè)通用函數(shù)內(nèi)部處理文件大小超限、格式校驗(yàn)、失敗重試等邏輯。因?yàn)樵谂客扑偷膱?chǎng)景里可能一次要發(fā)幾十張圖如果每個(gè)環(huán)節(jié)都手寫代碼會(huì)非常臃腫。封裝之后的調(diào)用長(zhǎng)這樣def send_image(token, to_user, media_id, agent_id): payload { touser: to_user, msgtype: image, agentid: agent_id, image: {media_id: media_id} } return requests.post( fhttps://qyapi.weixin.qq.com/cgi-bin/message/send?access_token{token}, jsonpayload ).json()4.5 通過群機(jī)器人往群聊發(fā)markdown消息最后展示怎么往群里發(fā)消息。這里不通過access_token而是直接調(diào)webhookwebhook_url https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyxxxxx payload { msgtype: markdown, markdown: { content: ## 監(jiān)控告警 \n 線上服務(wù)異常率超過5%請(qǐng)及時(shí)處理。\n 時(shí)間點(diǎn)2026-03-20 10:30:00 } } resp requests.post(webhook_url, jsonpayload) print(resp.json())如果群里給機(jī)器人配置了“關(guān)鍵詞”markdown內(nèi)容里必須包含那個(gè)關(guān)鍵詞。比如你配置的關(guān)鍵詞是“告警”上面這條消息里最好明確帶“告警”兩個(gè)字否則返回如下錯(cuò)誤{errcode:93000,errmsg:invalid webhook url, please check the webhook info}這個(gè)報(bào)錯(cuò)非常迷惑看起來像是webhook地址無效實(shí)際是安全設(shè)置攔截。我第一次做的時(shí)候被它坑了整整一下午。5. 高頻踩坑記錄與排錯(cuò)參考把我在項(xiàng)目里遇到過的所有問題匯總成一張表你收藏這份以后調(diào)接口遇到報(bào)錯(cuò)直接對(duì)號(hào)入座。5.1 返回碼快速排查表返回碼含義常見原因處理建議0成功無無需處理40001access_token無效token過期、緩存被清、重新獲取導(dǎo)致舊token失效重新獲取token用新token重試40003userid不合法用戶不在通訊錄、不是應(yīng)用的可見范圍檢查userid大小寫、同步通訊錄、擴(kuò)大應(yīng)用可見范圍40013corpid不合法配置的corpid寫錯(cuò)了去管理后臺(tái)核對(duì)40014access_token不合法token錯(cuò)誤或已被覆蓋重新獲取token41030media_id無效素材類型不匹配、素材過期、用錯(cuò)上傳接口重新上傳素材檢查type參數(shù)45009接口調(diào)用超過頻率限制并發(fā)過高、循環(huán)調(diào)用、token重復(fù)獲取加本地隊(duì)列控制調(diào)用頻率批量消息分批發(fā)送60011無權(quán)限訪問應(yīng)用沒有通訊錄權(quán)限、Secret不對(duì)應(yīng)檢查應(yīng)用權(quán)限設(shè)置確認(rèn)Secret與AgentId匹配60020訪問來源IP不在白名單服務(wù)器公網(wǎng)IP未加入可信IP去管理后臺(tái)配置可信IP93000群機(jī)器人消息被攔截webhook地址不對(duì)、安全設(shè)置關(guān)鍵詞不匹配檢查webhook地址核對(duì)關(guān)鍵詞規(guī)則5.2 幾個(gè)典型問題實(shí)錄除了返回碼我在項(xiàng)目里實(shí)際踩過的幾個(gè)場(chǎng)景也值得單獨(dú)說。場(chǎng)景一接口返回成功但員工就是收不到消息這是最讓我頭疼的問題。代碼檢查了很多遍返回碼始終是0但員工的企業(yè)微信里就是沒有新消息。排查到最后發(fā)現(xiàn)這個(gè)應(yīng)用在企業(yè)微信后臺(tái)里從來沒被員工“使用”過而且可見范圍也跟員工無關(guān)。說白了你在后臺(tái)把應(yīng)用可見范圍設(shè)成了“研發(fā)部”但給一個(gè)“市場(chǎng)部”的人發(fā)消息接口可能不會(huì)直接報(bào)錯(cuò)而是默默丟棄。所以收到0也別高興太早先確認(rèn)接收人是否在可見范圍里。場(chǎng)景二給部門發(fā)廣播返回60011我當(dāng)時(shí)想給某個(gè)部門發(fā)通知toparty填的是部門ID但一直返回60011提示沒有權(quán)限。原因是應(yīng)用可見范圍只勾選了“全體成員”里的某幾個(gè)部門沒有單獨(dú)把這個(gè)部門勾進(jìn)去。有些你以為是后臺(tái)配置的問題其實(shí)是“可見范圍”和“通訊錄權(quán)限”兩個(gè)概念混在一起要同時(shí)滿足。場(chǎng)景三群機(jī)器人發(fā)圖片報(bào)media_id無效前面提過群機(jī)器人上傳素材的接口是/webhook/upload_media但是很多人包括我容易下意識(shí)直接用/media/upload。這兩個(gè)接口返回的media_id格式都差不多但互相不通用。所以如果你確認(rèn)token沒有過期、圖片也沒超2MB但報(bào)media_id無效趕緊看看是不是用的上傳接口不對(duì)。場(chǎng)景四文本消息內(nèi)容里帶中文或特殊符號(hào)出現(xiàn)亂碼這個(gè)問題主要出現(xiàn)在一些老舊的HTTP客戶端上設(shè)置請(qǐng)求頭的時(shí)候沒指定UTF-8編碼。企業(yè)微信接口是標(biāo)準(zhǔn)的UTF-8所以Content-Type一定要寫成application/json; charsetutf-8。requests庫默認(rèn)會(huì)處理好但如果自己用其他語言寫SDK就要注意。最后分享幾點(diǎn)我的個(gè)人體會(huì)接口文檔寫得很全但是“能跑通”和“在生產(chǎn)環(huán)境中穩(wěn)定跑”之間還隔著大量細(xì)節(jié)。我在做了好幾個(gè)類似項(xiàng)目之后最大的感受是一定要在項(xiàng)目初期設(shè)計(jì)一個(gè)統(tǒng)一的消息服務(wù)層把token緩存、素材上傳、消息發(fā)送、重試邏輯全部封裝好不要讓業(yè)務(wù)代碼直接裸調(diào)接口。這樣后面接更多消息類型時(shí)只改服務(wù)層就夠了不用動(dòng)上層業(yè)務(wù)。另外不管你用py、Java還是Go先做小范圍灰度。我的習(xí)慣是先把代碼寫一個(gè)命令行腳本手動(dòng)發(fā)給自己和測(cè)試號(hào)逐項(xiàng)驗(yàn)證文本、圖片、文件和群機(jī)器人消息類型全部跑通再接入業(yè)務(wù)系統(tǒng)。別一上來就做批量推送否則限流、權(quán)限、media_id過期這些問題混在一起你會(huì)被搞得懷疑人生。企業(yè)微信消息接口的價(jià)值不在于“能發(fā)消息”這個(gè)動(dòng)作而在于它可以被程序化地整合進(jìn)你的運(yùn)維系統(tǒng)、報(bào)表系統(tǒng)、客戶運(yùn)營(yíng)系統(tǒng)成為整個(gè)自動(dòng)化工作流里最接近人的一環(huán)。先把私聊文本跑通再逐步加上圖片、視頻、群機(jī)器人你會(huì)發(fā)現(xiàn)這套API能做的事情遠(yuǎn)比想象中要多得多。