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