首頁>編程相關>Ai源碼
下載

? Docker 映像 | ? NPM包｜? FAQ

一個小小的微信機器人webhook，幫你抹平了很多自己開發的障礙，基於http 請求，與hooks微信不同，因為基於web api，所以優勢在於可以部署到arm架構等設備上

Features

Caution

專案目前基於web微信，本身就有被限制風險，另外大概兩天一掉線，除了正常功能修補，不接新的feature request。 windows 協定正在WIP，近期應該會跟大家見面！

功能web協議windows協議
目前可用性✅
程式碼分支main windows
Docker Tag latest windows
<發送訊息> ✅ 單條/ 多條/ 群發✅ 單條/ 多條/ 群發
發文字✅ ✅
發圖片✅ 本機圖片/ url圖片解析✅ 本機圖片/ url圖片解析
發視頻（mp4) ✅ 本地視頻/ url視頻解析
發文件✅ 本機檔案/ url檔案解析✅ 本機檔案/ url檔案解析
<接收訊息>
接收文字✅ ✅
接收語音✅
接收圖片✅
接收視訊✅
接收文件✅
接收公眾號推文鏈接✅
接收系統通知✅ 上線通知/ 掉線通知/ 異常通知
頭像獲取✅
快速回覆✅ ✅
<群管理>
<好友管理>
接收好友申請✅
透過好友申請✅
取得聯絡人列表
<其他功能>
非斷線自動登入✅
API 鑑權✅ ✅
n8n 無縫接入✅
支援docker部署✅ arm64 / amd64 ✅ amd64
日誌文件匯出✅ ✅

️特別說明：

以上提到的功能✅ 為已實現，受限於微信協定限制，不同協定支援功能也是不同的，並非所有功能都可以對接，例如：

  • 企業微信訊息的收發#142
  • 發送語音訊息/ 分享音樂/ 公眾號等在features 中未提到的功能

一分鐘Demo

1. 運行& 掃碼

npx wechatbot-webhook

除非掉線，預設記住上次登錄，換帳號請執行以下命令npx wechatbot-webhook -r

如遇安裝報錯，請確保自己的node版本>= 18.14.1 #227

2. 複製推文訊息api

從命令列複製推訊息api，例如http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]

3. 使用以下結構發送訊息

新開個終端試試以下curl，to、token 欄位值換成你要值

curl --location ' http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN] ' 
--header ' Content-Type: application/json ' 
--data ' { "to": "测试昵称", data: { "content": "Hello World!" }} '

?開發

Important

套件管理器遷移已至pnpm，安裝依賴請使用它，以支援一些不定時的臨時套件修補（patches）和加速依賴安裝

⛰️ 部署Deploy（建議）

1.使用docker 部署

拉取最新鏡像
 docker pull dannicool/docker-wechatbot-webhook
docker 部署
 # 启动容器并映射日志目录，日志按天维度生成，e.g: app.2024-01-01.log
docker run -d --name wxBotWebhook -p 3001:3001 
-v ~ /wxBot_logs:/app/log 
dannicool/docker-wechatbot-webhook
使用compose 部署(可選) 
wget -O docker-compose.yml https://cdn.jsdelivr.net/gh/danni-cool/wechatbot-webhook@main/docker-compose.yml && docker-compose down && docker-compose -p wx_bot_webhook up

2.登入

docker logs -f wxBotWebhook

找到二維碼登入位址，圖下url 部分，瀏覽器訪問，掃碼登入wx

https://localhost:3001/login?token=[YOUR_PERSONAL_TOKEN]

可選env 參數

Tips：需增加參數使用-e，多行用 隔開，例如-e RECVD_MSG_API="https://example.com/your/url"

功能變數備註
日誌等級LOG_LEVEL=info日誌級別，預設info，只影響當前日誌輸出，詳細輸出考慮使用debug。無論該值如何變化，日誌檔案總是記錄debug等級的日誌
收消息API RECVD_MSG_API=https://example.com/your/url如果想自己處理收到訊息的邏輯，例如根據訊息連動，填上你的處理邏輯url
收消息API 接受自己發的訊息ACCEPT_RECVD_MSG_MYSELF=false RECVD_MSG_API 是否接收來自自己發送的訊息（設定為true，即接收, 預設false）
自訂登入API token LOGIN_API_TOKEN=abcdefg123你也可以自訂一個自己的登入令牌，不配置的話，預設會產生一個
停用自動登入DISABLE_AUTO_LOGIN=true非微信踢下線帳號，可以依靠目前登入的session免登, 如果想每次都掃碼登陸，則增加該條配置

API

1. 推訊息API

v2版本介面增加了群發功能，v1 版本介面請移步legacy-api

  • Url：http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]
  • Methods: POST
  • ContentType: application/json
  • Body: 格式請見下面表格

payload結構

發文字或文件外鏈, 外鏈會解析成圖片或文件

參數說明資料類型預設值可否為空可選參數
to訊息接收方，傳入String預設是發給暱稱（群名同理）, 傳入Object結構支援發給備註過的人，例如： {alias: '备注名'} ，群組不支援備註名String Object - N -
isRoom是否發給群組訊息，這個參數決定了找人的時候找的是群組還是人，因為暱稱其實和群組名稱相同在技術處理上Boolean false Y true false
data訊息體結構,見下方payload.data Object Array false N true false

payload.data結構

參數說明資料類型預設值可否為空可選參數
type訊息類型, 欄位留空解析為純文字String text - Y text fileUrl
content訊息內容，如果希望發多個Url並解析，type 指定為fileUrl 同時，content 填入url 以英文逗號分隔String - N -

例子（curl）

發單一訊息
curl --location ' http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN] ' 
--header ' Content-Type: application/json ' 
--data ' {
    "to": "testUser",
    "data": { "content": "你好" }
} '
發檔url 同時支援修改成目標檔名

有些情況下，直接發送url 檔案名稱可能不是我們想要的，給url 拼接query 參數$alias可用於指定發送給目標的檔案名稱（注意：別名不做檔案轉換） 

curl --location ' http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN] ' 
--header ' Content-Type: application/json ' 
--data ' {
    "to": "testUser",
    "data": { 
      "type": "fileUrl" , 
      "content": "https://download.samplelib.com/jpeg/sample-clouds-400x300.jpg?$alias=cloud.jpg" 
    }
} '
發給群組訊息
curl --location ' http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN] ' 
--header ' Content-Type: application/json ' 
--data ' {
    "to": "testGroup",
    "isRoom": true,
    "data": { "type": "fileUrl" , "content": "https://download.samplelib.com/jpeg/sample-clouds-400x300.jpg" },
} '
同一對像多條訊息(群消息同理) 
curl --location ' http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN] ' 
--header ' Content-Type: application/json ' 
--data ' {
    "to": "testUser",
    "data": [
        {
            "type": "text",
            "content": "你好"
        },
        {
            "type": "fileUrl",
            "content": "https://samplelib.com/lib/preview/mp3/sample-3s.mp3"
        }
    ]
} '
群發訊息
curl --location ' http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN] ' 
--header ' Content-Type: application/json ' 
--data ' [
    {
        "to": "testUser1",
        "data": {
            "content": "你好"
        }
    },
    {
        "to": "testUser2",
        "data": [
          {
            "content": "你好"
          },
          {
            "content": "近况如何？"
          }
        ]
    }
] '

傳回值response結構

  • success : 訊息傳送成功與否，群組傳送訊息即使部份傳送成功也會回傳true
  • message : 出錯時提示的訊息
    • 訊息發送成功: Message sent successfully
    • 參數校驗不通過: Some params is not valid, sending task is suspend...
    • 訊息都發送失敗: All Messages [number] sent failed...
    • 部發送成功: Part of the message sent successfully...
  • task : 發送任務詳細信息
    • task.successCount : 發送成功條數
    • task.totalCount : 總訊息條數
    • task.failedCount : 傳送失敗條數
    • task.reject : 因為參數校驗不通過的參數和error 提示
    • task.sentFailed : 因為發送失敗和error 提示
    • task.notFound : 因為未找到使用者或群組和error 提示

確保訊息單次發送一致性，某一條參數校驗失敗會終止所有訊息發送任務

{
    "success" : true ,
    "message" : " " ,
    "task" : {
        "successCount" : 0 ,
        "totalCount" : 0 ,
        "failedCount" : 0 ,
        "reject" : [],
        "sentFailed" : [],
        "notFound" : []
    }
}

讀文件發送

讀文件暫時只支援單一發送

  • Url：http://localhost:3001/webhook/msg?token=[YOUR_PERSONAL_TOKEN]
  • Methods: POST
  • ContentType: multipart/form-data
  • FormData: 格式請見下面表格
payload結構
參數說明資料類型預設值可否為空可選值
to訊息接收方，傳入String預設是發給暱稱（群名同理）, 傳入Json String 結構支援發給備註過的人，例如：--form 'to="{alias: "小號"}" '，群組名稱不支援備註名稱String - N -
isRoom是否發送的群組訊息，formData純文字只能使用String類型， 1代表是， 0代表否， String 0 Y 1 0
content文件，本地文件一次只能發一個，多個文件手動呼叫多次Binary - N -
Curl 
curl --location --request POST ' http://localhost:3001/webhook/msg?token=[YOUR_PERSONAL_TOKEN] ' 
--form ' to=testGroup ' 
--form content=@ " $HOME /demo.jpg " 
--form ' isRoom=1 '

傳回值response結構

{
  "success" : true ,
  "message" : " Message sent successfully "
}

2. 收消息API

payload結構

  • Methods: POST
  • ContentType: multipart/form-data
  • Form格式如下
formData說明資料類型可選值範例
type
功能類型
  • ✅ 文字(text)
  • ✅ 連結卡(urlLink)
  • ✅ 圖片(file)
  • ✅ 影片(file)
  • ✅ 附件(file)
  • ✅ 語音(file)
  • ✅ 加入好友邀請(friendship)
其他類型
  • 未實現的訊息類型(unknown)
系統類型
  • ✅ 登入(system_event_login)
  • ✅ 登出(system_event_logout)
  • ✅ 異常報錯(system_event_error)
  • ✅ 快速回覆後訊息推播狀態通知(system_event_push_notify)
 String text file urlLink friendship unknown system_event_login system_event_logout system_event_error system_event_push_notify -
content傳輸的內容, 文字或傳輸的文件共用這個字段，結構映射請看範例String Binary範例
source訊息的相關發送方資料, JSON String String範例
isMentioned該消息是@我的消息#38 String 1 0 -
isMsgFromSelf是否是來自自己的訊息#159 String 1 0 -

服務端處理formData 一般需要對應的處理程序，假設你已經完成這一步，你會得到以下request 

  {
    "type" : " text " ,
    "content" : "你好" ,
    "source" : " { " room " : "" , " to " :{ " _events " :{}, " _eventsCount " :0, " id " : " @f387910fa45 " , " payload " :{ " alias " : "" , " avatar " : " /cgi-bin/mmwebwx-bin/webwxgeticon?seq=1302335654&username=@f38bfd1e0567910fa45&skey=@crypaafc30 " , " friend " :false, " gender " :1, " id " : " @f38bfd1e10fa45 " , " name " : " ch. " , " phone " :[], " star " :false, " type " :1}}, " from " :{ " _events " :{}, " _eventsCount " :0, " id " : " @6b5111dcc269b6901fbb58 " , " payload " :{ " address " : "" , " alias " : "" , " avatar " : " /cgi-bin/mmwebwx-bin/webwxgeticon?seq=123234564&username=@6b5dbb58&skey=@crypt_ec356afc30 " , " city " : " Mars " , " friend " :false, " gender " :1, " id " : " @6b5dbd3facb58 " , " name " : " Daniel " , " phone " :[], " province " : " Earth " , " signature " : "" , " star " :false, " weixin " : "" , " type " :1}}} " ,
    "isMentioned" : " 0 " ,
    "isMsgFromSelf" : " 0 " ,
    "isSystemEvent" : " 0 " // 考虑废弃，请使用type类型判断系统消息
  }

收消息api curl範例(直接導入postman調試） 

 curl --location 'https://your.recvdapi.com' 
--form 'type="file"' 
--form 'content=@"/Users/Downloads/13482835.jpeg"' 
--form 'source="{\"room\":\"\",\"to\":{\"_events\":{},\"_eventsCount\":0,\"id\":\"@f387910fa45\",\"payload\":{\"alias\":\"\",\"avatar\":\"/cgi-bin/mmwebwx-bin/webwxgeticon?seq=1302335654&username=@f38bfd1e0567910fa45&skey=@crypaafc30\",\"friend\":false,\"gender\":1,\"id\":\"@f38bfd1e10fa45\",\"name\":\"ch.\",\"phone\":[],\"star\":false,\"type\":1}},\"from\":{\"_events\":{},\"_eventsCount\":0,\"id\":\"@6b5111dcc269b6901fbb58\",\"payload\":{\"address\":\"\",\"alias\":\"\",\"avatar\":\"/cgi-bin/mmwebwx-bin/webwxgeticon?seq=123234564&username=@6b5dbb58&skey=@crypt_ec356afc30\",\"city\":\"Mars\",\"friend\":false,\"gender\":1,\"id\":\"@6b5dbd3facb58\",\"name\":\"Daniel\",\"phone\":[],\"province\":\"Earth\",\"signature\":\"\",\"star\":false,\"weixin\":\"\",\"type\":1}}}"' 
--form 'isMentioned="0"'

傳回值response結構（可選）

若期望用RECVD_MSG_API收訊息後立即回覆(快速回覆)，請按下列結構回傳回傳值，無回傳值則不會回覆訊息

  • ContentType: json
參數說明資料類型預設值可否為空可選參數
success該條請求成功與否，返回false 或無該字段，不會處理回复，有一些特殊消息也透過這個字段控制，比如加好友邀請，返回true則會通過好友請求Boolean - Y true false
data如果需要回覆訊息的話，需要定義data字段Object Object Array - Y

response.data結構

參數說明資料類型預設值可否為空可選參數
type訊息類型，此欄位不填預設當文字類型傳輸String text Y text fileUrl
content訊息內容，如果希望發多個Url並解析，type 指定為fileUrl 同時，content 填入url 以英文逗號分隔String - N -

如果回覆單一訊息

 {
    "success" : true ,
    "data" : {
      "type" : " text " ,
      "content" : " hello world！ "
    }
  }

組合回覆多則訊息

 {
    "success" : true ,
    "data" : [
      {
        "type" : " text " ,
        "content" : " hello world！ "
      },
      {
        "type" : " fileUrl " ,
        "content" : " https://samplelib.com/lib/preview/mp3/sample-3s.mp3 "
      }
    ]
  }

3. 其他API

token 設定說明

除了在docker 啟動時配置token，在預設缺省token 的情況，會預設產生一個寫入.env檔中

3.1 取得登入二維碼接口

  • 位址： /login
  • methods : GET
  • query : token
  • status : 200
  • example : http://localhost:3001/login?token=[YOUR_PERSONAL_TOKEN]
登入成功

返回json 包含當前用戶

{ "success" : true , "message" : " Contact<TestUser>is already login " }
登入失敗

展示微信登入掃碼頁面

3.2 健康檢測接口

可以主動輪詢該接口，檢查服務是否正常運行

  • 地址： /healthz
  • methods : GET
  • query : token
  • status : 200
  • example : http://localhost:3001/healthz?token=[YOUR_PERSONAL_TOKEN]

微信已登入, 返回純文healthy ，否則返回unHealthy

3.3 取得靜態資源接口

從2.8.0 版本開始，可以透過本介面存取頭像等靜態資源，具體見recvd_api 資料結構範例的avatar 字段

注意所有上報recvd_api 的靜態資源地址不會默認帶上token, 需要自己拼接，否則會返回401 錯誤, 請確保自己微信已登錄，需要通過登錄態去獲取資源

  • 位址： /resouces

  • methods : GET

  • query :

    • token: 登入token
    • media: encode過的相對路徑，如/avatar/1234567890.jpg encode為avatar%2F1234567890.jpg

  • status : 200 404 401

  • example ：http://localhost:3001/resouces?media=%2Fcgi-bin%2Fmmwebwx-bin%2Fwebwxgetheadimg%3Fseq%3D83460%26username%3D%40%4086815a%26skey

status: 200

成功取得資源, 返回靜態資源文件

status: 404

獲取資源失敗

status: 401未攜帶登入token 
{ "success" : false , "message" : " Unauthorized: Access is denied due to invalid credentials. " }
status: 401微信登入態已過期
{
   "success" : false , "message" : " you must login first "
}

? Star History

Contributors

Thanks to all our contributors!

⏫ 更新日誌

更新內容請參考CHANGELOG

展開
附加信息
相關應用
爲您推薦
相關資訊 全部