機器人簡單介紹
飛書群中的自定義機器人是通過webhook的形式將你要發送的消息即時發送到群聊中
在群聊中添加機器人
進入群聊，打開群設置，找到群機器人，並點擊添加機器人。選擇Custom Bot（自定義機器人）加入群聊。
第一步：添加該機器人進群，設置機器人頭像、名稱和描述，然后點擊下一步。
第二步：配置webhook，可根據需求選擇一種及以上安全設置的方式，也可不選，復制並保存此頁面的參數，最后點擊完成。
注意：一個群總共最多可添加 15 個機器人，可以只添加15個Custom Bot（自定義機器人）。
使用機器人發送消息
請保管好 webhook 地址。 不要公布在 Github、博客等可公開查閱的網站上。地址泄露后可能被惡意調用發送垃圾信息
最基本的發送消息
# Python 3.9
import json
import requests
# 你復制的webhook地址
url = "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx"
payload_message = {
"msg_type": "text",
"content": {
"text": "你要發送的消息"
}
}
headers = {
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=json.dumps(payload_message))
print(response.text)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
帶有安全設置的發送消息
方式一、自定義關鍵詞
最多可以設置10個關鍵詞，消息中至少包含其中1個關鍵詞才可以發送成功。
例如：添加了一個自定義關鍵詞：生日提醒
則這個機器人所發送的消息，必須包含 生日提醒 這個詞，才能發送成功。
# Python 3.9
import json
import requests
# 自定義關鍵詞key_word
key_word = "你設置的關鍵詞"
# 你復制的webhook地址
url = "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx"
payload_message = {
"msg_type": "text",
"content": {
"text": key_word + "你要發送的消息"
}
}
headers = {
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=json.dumps(payload_message))
print(response.text)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
方式二、IP 白名單
最多設置 10 個 IP 地址或地址段。設定后，只有來自IP地址范圍內的請求才會被正常處理。支持兩種設置方式：IP、IP段，暫不支持IPv6地址白名單，格式如下:
格式 說明
123.12.123.123 開發者的出口公網地址（非局域網地址）
123.12.1.* 或 123.1.1.1/24 用CIDR表示法表示的一個網段
方式三、簽名校驗
！！！注意：飛書的簽名校驗與其他的群機器人（釘釘、企業微信等）簽名校驗不同！！！
簽名的算法
首先獲取到的原始參數
參數 說明
timestamp 當前時間戳，單位是秒，與請求調用時間誤差不超過1小時
secret 密鑰，機器人安全設置頁面，簽名校驗一欄下面顯示的字符串
將原始參數通過計算獲得最終的簽名
使用 HmacSHA256 算法計算簽名，再進行 Base64 編碼，得到最終的簽名
待簽名的字符串（msg）：""（空串）
簽名所需的密鑰（key）：timestamp + “\n” + secret
哈希算法（digestmod）：sha256
簽名計算代碼示例（Python）
# Python 3.9
import base64
import hmac
import time
from hashlib import sha256
timestamp = str(round(time.time()))
secret = "你的密鑰"
key = f'{timestamp}\n{secret}'
key_enc = key.encode('utf-8')
msg = ""
msg_enc = msg.encode('utf-8')
hmac_code = hmac.new(key_enc, msg_enc, digestmod=sha256).digest()
sign = base64.b64encode(hmac_code).decode('utf-8')
print(timestamp)
print(sign)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Python 2.7
import base64
import hmac
import time
from hashlib import sha256
timestamp = long(round(time.time()))
secret = "你的密鑰"
key = '{}\n{}'.format(timestamp, secret)
key_enc = bytes(key).encode('utf-8')
msg = ""
msg_enc = bytes(msg).encode('utf-8')
hmac_code = hmac.new(key_enc, msg_enc, digestmod=sha256).digest()
sign = base64.b64encode(hmac_code).decode('utf-8')
print(timestamp)
print(sign)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
簽名計算代碼示例（Go）
func GenSign(secret string, timestamp int64) (string, error) {
stringToSign := fmt.Sprintf("%v", timestamp) + "\n" + secret
var data []byte
h := hmac.New(sha256.New, []byte(stringToSign))
_, err := h.Write(data)
if err != nil {
return "", err
}
signature := base64.StdEncoding.EncodeToString(h.Sum(nil))
return signature, nil
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
帶簽名校驗的實現
# Python 3.9
import base64
import hmac
import json
import time
from hashlib import sha256
import requests
timestamp = str(round(time.time()))
secret = "你的密鑰"
key = f'{timestamp}\n{secret}'
key_enc = key.encode('utf-8')
msg = ""
msg_enc = msg.encode('utf-8')
hmac_code = hmac.new(key_enc, msg_enc, digestmod=sha256).digest()
sign = base64.b64encode(hmac_code).decode('utf-8')
print(timestamp)
print(sign)
# 你復制的webhook地址
url = "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx"
payload_message = {
"timestamp": timestamp,
"sign": sign,
"msg_type": "text",
"content": {
"text": "你要發送的消息"
}
}
headers = {
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=json.dumps(payload_message))
print(response.text)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
帶簽名校驗和自定義關鍵詞的實現
# Python 3.9
import base64
import hmac
import json
import time
from hashlib import sha256
import requests
timestamp = str(round(time.time()))
secret = "你的密鑰"
key = f'{timestamp}\n{secret}'
key_enc = key.encode('utf-8')
msg = ""
msg_enc = msg.encode('utf-8')
hmac_code = hmac.new(key_enc, msg_enc, digestmod=sha256).digest()
sign = base64.b64encode(hmac_code).decode('utf-8')
print(timestamp)
print(sign)
# 自定義關鍵詞key_word
key_word = "你設置的關鍵詞"
# 你復制的webhook地址
url = "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx"
payload_message = {
"timestamp": timestamp,
"sign": sign,
"msg_type": "text",
"content": {
"text": key_word + "你要發送的消息"
}
}
headers = {
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=json.dumps(payload_message))
print(response.text)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
可發送的消息類型
自定義機器人添加完成后，就能向其 webhook 地址發送 POST 請求，從而在群聊中推送消息了。支持推送的消息格式有文本、富文本、圖片消息，也可以分享群名片等。
參數msg_type代表消息類型，可傳入：text（文本）/ post（富文本）/ image（圖片）/ share_chat（分享群名片）/ interactive（消息卡片）。具體使用方法可查看下文的官方文檔。
請求發送后的返回信息匯總
消息發送成功：{“Extra”:null,“StatusCode”:0,“StatusMessage”:“success”}
webhook地址無效：{“code”:19001,“msg”:“param invalid: incoming webhook access token invalid”}
關鍵詞校驗失敗：{“code”:19024,“msg”:“Key Words Not Found”}
IP校驗失敗：{“code”:19022,“msg”:“Ip Not Allowed”}
簽名校驗失敗：{“code”:19021,“msg”:“sign match fail or timestamp is not within one hour from current time”}
機器人的常見問題
自定義機器人的 webhook地址有 V1、V2 版本，如何兼容？
答：請參考幫助文檔如何在群聊中使用機器人的附錄部分“舊版 webhook (自定義機器人) 使用說明”。同時，推薦使用V2版本的自定義機器人。
使用 webhook 的自定義機器人是否可以@單個成員、或者@所有人？
答：V2版本的自定義機器人，支持@單個成員、或者@所有人。
配置使用 webhook 的自定義機器人時，參數text是否有長度要求？
答：建議 JSON 的長度不超過 30k，序列化后的 pb 不超過 100k，圖片最好小於 10MB。
擴展應用場景
服務器監測報警
天氣情況、生日提醒和新聞資訊等的推送
個人開發應用的用戶反饋
輕量級的埋點統計
官方文檔
飛書機器人文檔：https://www.feishu.cn/hc/zh-CN/articles/360024984973-%E6%9C%BA%E5%99%A8%E4%BA%BA-%E5%A6%82%E4%BD%95%E5%9C%A8%E7%BE%A4%E8%81%8A%E4%B8%AD%E4%BD%BF%E7%94%A8%E6%9C%BA%E5%99%A8%E4%BA%BA-#source=section