柚子快报邀请码778899分享：飞书自定义机器人消息接入指南
操作流程
第一步
邀请自定义机器人入群：进入你的目标群组，打开会话设置，找到群机器人，并点击添加机器人，选择自定义机器人加入群聊。
为机器人输入一个合适的名字和描述，也可以为机器人设置一个合适的头像，然后点击下一步。
第二部：配置 webhook
获取该机器人的 webhook 地址，格式如下：
https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx
第三步：调用webhook发送消息
用任意方式向该 webhook 发起 HTTP POST 请求，即可向这个自定义机器人所在的群聊发送消息。
注意
你需要一定的服务端开发基础，通过服务端请求方式调用webhook地址。 以curl指令为例，请求示例如下：
curl -X POST -H "Content-Type: application/json" \
-d '{"msg_type":"text","content":{"text":"request example"}}' \
https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx
请将上述代码中 https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx 更换为真实webhook的地址。 若测试出错，请先检查复制的指令是否和测试指令结构一致。
如请求成功，返回体为：
{
"code": 0,
"msg": "success",
"data": {},
"Extra": null,//冗余字段，用于兼容存量历史逻辑，不建议使用
"StatusCode": 0,//冗余字段，用于兼容存量历史逻辑，不建议使用
"StatusMessage": "success"//冗余字段，用于兼容存量历史逻辑，不建议使用
}
如请求体格式错误，返回体如下。请检查：
请求体内容格式是否与各消息类型的示例代码一致请求体大小不能超过20k
{
"code": 9499,
"msg": "Bad Request",
"data": {}
}
添加安全设置
如果未妥善保管webhook地址，可能存在webhook地址泄露后，被恶意开发者调用，发送垃圾信息的风险，我们强烈建议对其进行安全设置。安全设置目前提供了 3 种方式，可根据需求选择一种及以上方式进行配置。
方式一：自定义关键词
最多设置 10 个关键词。设定后，只有包含至少一个关键词的消息才会被发送。如，将自定义关键词设为“应用报警”和“项目更新”后，自定义机器人发送的消息至少包含其中一个词，才会被发送到群聊。
发送请求后，若自定义关键词校验失败，将返回以下信息：
// 关键词校验失败
{
"code": 19024,
"msg": "Key Words Not Found"
}
方式二：IP 白名单
最多设置 10 个 IP 地址或地址段。设定后，只处理来自所设 IP 地址范围的请求。支持段输入，如 123.12.1.* 或 123.1.1.1/24
// IP校验失败
{
"code": 19022,
"msg": "Ip Not Allowed"
}
方式三：签名校验
设定后，发送的请求是需要签名验证来保障来源可信。 签名的算法：把 timestamp + “\n” + 密钥 当做签名字符串，使用 HmacSHA256 算法计算签名，再进行 Base64 编码。
timestamp为距当前时间不超过 1 小时(3600)的时间戳，时间单位s，如：1599360473密钥自动生成，可直接从界面上复制
Java示例代码如下：
package sign;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import org.apache.commons.codec.binary.Base64;
public class SignDemo {
public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException {
String secret = "demo";
int timestamp = 100;
System.out.printf("sign: %s", GenSign(secret, timestamp));
}
private static String GenSign(String secret, int timestamp) throws NoSuchAlgorithmException, InvalidKeyException {
//把timestamp+"\n"+密钥当做签名字符串
String stringToSign = timestamp + "\n" + secret;
//使用HmacSHA256算法计算签名
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(stringToSign.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] signData = mac.doFinal(new byte[]{});
return new String(Base64.encodeBase64(signData));
}
}
获得签名后，在发送请求时需加上 timestamp 和 sign （即获得的签名）字段。发送文本消息的请求例如下：
// 开启签名验证后发送文本消息
{
"timestamp": "1599360473",
"sign": "xxxxxxxxxxxxxxxxxxxxx",
"msg_type": "text",
"content": {
"text": "request example"
}
}
发送请求后，若签名校验失败，请排查以下原因：
时间戳距发送时已超过 1 小时，签名已过期；服务器时间与标准时间有比较大的偏差，导致签名过期。请注意检查、校准你的服务器时间；签名不匹配，校验不通过。将返回以下信息：
// 签名校验失败
{
"code": 19021,
"msg": "sign match fail or timestamp is not within one hour from current time"
}
发送消息
自定义机器人添加完成后，就能向其 webhook 地址发送 POST 请求，从而在群聊中推送消息了。支持推送的消息格式有文本、富文本、图片消息和群名片等。 在消息体中，参数msg_type和对应的消息类型的映射关系如下：
参数(msg_type)消息类型参考文档text文本文本消息格式说明post富文本富文本消息格式说明image图片上传图片share_chat分享群名片–interactive消息卡片消息卡片消息
文本消息
请求的消息体示例：
{
"msg_type": "text",
"content": {
"text": "新更新提醒"
}
}
富文本消息
请求的消息体示例：
{
"msg_type": "post",
"content": {
"post": {
"zh_cn": {
"title": "项目更新通知",
"content": [
[{
"tag": "text",
"text": "项目有更新: "
},
{
"tag": "a",
"text": "请查看",
"href": "http://www.example.com/"
},
{
"tag": "at",
"user_id": "ou_18eac8********17ad4f02e8bbbb"
}
]
]
}
}
}
}
发送群名片
请求的消息体示例：
{
"msg_type":"image",
"content":{
"image_key": "img_ecffc3b9-8f14-400f-a014-05eca1a4310g"
}
}
image_key的获取方法，可参考上传图片说明文档。
发送卡片消息
消息卡片可由按钮、图片等多种组件类型搭建而成。关于消息卡片的设计规范、格式等信息，请详见开放平台文档-消息卡片。
自定义机器人发送的消息卡片，只支持通过按钮、文字链方式跳转url，不支持点击后回调信息到服务端的 回传交互在消息卡片中如果要@提到某用户，请注意：自定义机器人仅支持通过open_id（什么是open_id?）的方式实现，暂不支持email、user_id等其他方式。
请求的消息体示例：
注意：发送消息卡片时，需要将消息体的content字符串替换为card结构体
{
"msg_type": "interactive",
"card": {
"elements": [{
"tag": "div",
"text": {
"content": "**西湖**，位于浙江省杭州市西湖区龙井路1号，杭州市区西部，景区总面积49平方千米，汇水面积为21.22平方千米，湖面面积为6.38平方千米。",
"tag": "lark_md"
}
}, {
"actions": [{
"tag": "button",
"text": {
"content": "更多景点介绍 :玫瑰:",
"tag": "lark_md"
},
"url": "https://www.example.com",
"type": "default",
"value": {}
}],
"tag": "action"
}],
"header": {
"title": {
"content": "今日旅游推荐",
"tag": "plain_text"
}
}
}
}
如何实现@指定人、@所有人
可以在机器人发送的普通文本消息（text）、富文本消息（post）、消息卡片（interactive）中，使用at标签实现@人效果。具体请求示意如下
在普通文本消息 (text) 中@人、@所有人:
at标签说明:
// at 指定用户
// at 所有人
请求体示意：
{
"msg_type": "text",
"content": {
"text": "
}
}
(2) 在富文本消息 (post) 中@人、@所有人:
at标签说明:
// at 指定用户
{
"tag": "at",
"user_id": "ou_xxxxxxx",//取值必须使用ou_xxxxx格式的 open_id 来at指定人
"user_name": "tom"
}
// at 所有人
{
"tag": "at",
"user_id": "all",//取值使用"all"来at所有人
"user_name": "所有人"
}
请求体示意：
{
"msg_type": "post",
"content": {
"zh_cn": {
"title": "我是一个标题",
"content": [
[{
"tag": "text",
"text": "第一行 :"
},
{
"tag": "at",
"user_id": "ou_xxxxxx",
"user_name": "tom"
}
],
[{
"tag": "text",
"text": "第二行:"
},
{
"tag": "at",
"user_id": "all",
"user_name": "所有人"
}
]
]
}
}
}
(3) 在消息卡片 (interactive) 中@人、@所有人:
可以使用消息卡片Markdown内容中的at人标签，标签示意：
// at 指定用户
// at 所有人
请求体中的 card 内容示意：
{
"msg_type": "interactive",
"card": {
"elements": [{
"tag": "div",
"text": {
"content": "at所有人
"tag": "lark_md"
}
}]
}
}
以上消息内容可支持 markdown 格式的语法
飞书 Java 代码示例
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
import javax.annotation.Resource;
import java.text.SimpleDateFormat;
import java.util.HashMap;
import java.util.Map;
/**
* 飞书消息提醒
*/
@Component
public class FeiShuUtils {
@Resource
private RestTemplate restTemplate;
// 发送文本消息
public void sendTextMessage() {
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
Map
text.put("msg_type", "text");
Map
// content.put("text", "项目告警通知：" + sdf.format(new Date()));
content.put("text", "项目告警通知
text.put("content", content);
String url = "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxx-xxxxx";
String response = restTemplate.postForObject(url, text, String.class);
System.out.println(response);
}
// 发送富文本消息
public void sendRichTextMessage() {
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
String str = "{\n" +
" \"msg_type\": \"post\",\n" +
" \"content\": {\n" +
" \"post\": {\n" +
" \"zh_cn\": {\n" +
" \"title\": \"项目更新通知\",\n" +
" \"content\": [\n" +
" [\n" +
" {\n" +
" \"tag\": \"text\",\n" +
" \"text\": \"项目有更新: \"\n" +
" },\n" +
" {\n" +
" \"tag\": \"a\",\n" +
" \"text\": \"请查看\",\n" +
" \"href\": \"http://www.baidu.com/\"\n" +
" },\n" +
" {\n" +
" \"tag\": \"at\",\n" +
" \"user_id\": \"all\",\n" +
" \"user_name\": \"所有人\"\n" +
" }\n" +
" ]\n" +
" ]\n" +
" }\n" +
" }\n" +
" }\n" +
"}";
HttpHeaders headers = new HttpHeaders();
// 设置请求头编码格式防止乱码
headers.add("Content-Type", "application/json; charset=UTF-8");
HttpEntity
String url = "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxx-xxxxx";
String response = restTemplate.postForObject(url, requestEntity, String.class);
System.out.println(response);
}
// 发送图片消息
public void sendImage() {
String str = "{\n" +
" \"msg_type\":\"image\",\n" +
" \"content\":{\n" +
" \"image_key\": \"img_ecffc3b9-8f14-400f-a014-05eca1a4310g\"\n" +
" }\n" +
"} ";
String url = "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxx-xxxxx";
String response = restTemplate.postForObject(url, str, String.class);
System.out.println(response);
}
// 发送卡片消息
public void sendCard() {
String str = "{\n" +
" \"msg_type\": \"interactive\",\n" +
" \"card\": {\n" +
" \"config\": {\n" +
" \"wide_screen_mode\": true\n" +
" },\n" +
" \"elements\": [\n" +
" {\n" +
" \"tag\": \"markdown\",\n" +
" \"content\": \"这里是卡片文本，支持使用markdown标签设置文本格式。例如：\\n*斜体* 、**粗体**、~~删除线~~、[文字链接](https://www.feishu.cn)、
" },\n" +
" {\n" +
" \"alt\": {\n" +
" \"content\": \"\",\n" +
" \"tag\": \"plain_text\"\n" +
" },\n" +
" \"img_key\": \"img_v2_041b28e3-5680-48c2-9af2-497ace79333g\",\n" +
" \"tag\": \"img\"\n" +
" },\n" +
" {\n" +
" \"tag\": \"action\",\n" +
" \"actions\": [\n" +
" {\n" +
" \"tag\": \"button\",\n" +
" \"text\": {\n" +
" \"tag\": \"plain_text\",\n" +
" \"content\": \"这是跳转按钮\"\n" +
" },\n" +
" \"type\": \"primary\",\n" +
" \"url\": \"https://feishu.cn\"\n" +
" }\n" +
" ]\n" +
" }\n" +
" ],\n" +
" \"header\": {\n" +
" \"template\": \"blue\",\n" +
" \"title\": {\n" +
" \"content\": \"这里是卡片标题\",\n" +
" \"tag\": \"plain_text\"\n" +
" }\n" +
" }\n" +
" }\n" +
"}";
HttpHeaders headers = new HttpHeaders();
// 设置请求头编码格式防止乱码
headers.add("Content-Type", "application/json; charset=UTF-8");
HttpEntity
String url = "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxx-xxxxx";
String response = restTemplate.postForObject(url, requestEntity, String.class);
System.out.println(response);
}
}
发送结果
柚子快报邀请码778899分享：飞书自定义机器人消息接入指南
相关文章
您阅读本篇文章共花了：
发表评论