飞书机器人发送消息完全指南：从curl命令到自动化脚本

摘要

本文详细介绍如何使用飞书机器人通过Webhook发送消息，涵盖自定义机器人创建、cURL命令调用、多种消息格式实现以及Shell脚本自动化实践。适合需要实现服务器监控、自动化通知的运维人员和开发者。

1 飞书机器人类型与选择

飞书提供两种类型的机器人：应用机器人和自定义机器人，两者在使用场景和能力上有显著差异。

应用机器人功能全面，需要企业在飞书开放平台创建应用并开启机器人能力，支持发送消息、接收并回复消息（需订阅事件）、管理群组以及调用飞书丰富的开放接口，但需要发版并经过企业管理员审核。它适合深度集成企业业务系统的场景。

自定义机器人配置简单，通过在群聊中直接添加”自定义机器人”生成，主要能力是向所在群组单向推送消息，无法交互或获取群信息，无需审核即可使用。它非常适合临时或简单的群消息推送需求。

对于大多数通过脚本发送通知的场景，自定义机器人因其简单的Webhook调用方式而更为常用。它核心的功能就是一个Webhook地址，允许你通过向该地址发送HTTP POST请求来推送消息到群聊。

2 创建与配置自定义机器人

进入目标飞书群组，点击右上角的群设置（...）。
选择「群机器人」->「添加机器人」->「自定义机器人」。
为机器人设置名称和描述（可选），然后点击添加。
添加成功后，系统会提供一个 Webhook URL，格式通常为 https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx 。请妥善保存此URL。

3 使用cURL命令发送消息

获取Webhook URL后，即可使用 curl 命令发送消息。基本命令结构如下：

curl -X POST \
  "https://open.feishu.cn/open-apis/bot/v2/hook/你的Webhook地址" \
  -H "Content-Type: application/json" \
  -d '{
        "msg_type": "text",
        "content": {
          "text": "这是一条来自cURL的测试消息"
        }
      }'

如果请求成功，你会收到类似 {"StatusCode":0,"StatusMessage":"success"} 的响应，并且消息会出现在群聊中。

4 消息类型与格式详解

飞书自定义机器人支持多种消息类型，以下是常见格式的示例。

4.1 文本消息 (text)

最基本的消息类型，支持纯文本。可以使用 <at> 标签来@群成员或所有人。

curl -X POST \
  "https://open.feishu.cn/open-apis/bot/v2/hook/你的Webhook地址" \
  -H "Content-Type: application/json" \
  -d '{
        "msg_type": "text",
        "content": {
          "text": "服务器状态告警\n时间：2023-10-26 10:00:00\n内容：CPU使用率超过90% <at user_id=\"all\">所有人</at>"
        }
      }'

4.2 富文本消息 (post)

富文本消息 (post) 支持更复杂的排版，可以在一条消息中组合文本、链接、@提及等元素，通常用于需要良好排版的通知。

curl -X POST \
  "https://open.feishu.cn/open-apis/bot/v2/hook/你的Webhook地址" \
  -H "Content-Type: application/json" \
  -d '{
        "msg_type": "post",
        "content": {
          "post": {
            "zh_cn": {
              "title": "每日报表",
              "content": [
                [
                  {"tag": "text", "text": "今日活跃用户: "},
                  {"tag": "text", "text": "1,250", "style": "bold"}
                ],
                [
                  {"tag": "text", "text": "关键指标: "},
                  {"tag": "a", "text": "查看详情", "href": "http://example.com/dashboard"}
                ],
                [
                  {"tag": "at", "user_id": "all", "user_name": "所有人"}
                ]
              ]
            }
          }
        }
      }'

4.3 消息卡片 (interactive)

消息卡片 (interactive) 是功能最丰富的消息形式，支持图片、按钮、分栏等交互元素（尽管自定义机器人的按钮通常仅支持跳转链接）。可以使用飞书提供的[消息卡片搭建工具]进行可视化设计。

curl -X POST \
  "https://open.feishu.cn/open-apis/bot/v2/hook/你的Webhook地址" \
  -H "Content-Type: application/json" \
  -d '{
        "msg_type": "interactive",
        "card": {
          "elements": [
            {
              "tag": "div",
              "text": {
                "content": "**任务执行结果**\n时间: 2023-10-26 10:00:00\n状态: <font color=\"green\">成功</font>\n详情: 数据备份任务已完成。",
                "tag": "lark_md"
              }
            },
            {
              "tag": "action",
              "actions": [
                {
                  "tag": "button",
                  "text": {"tag": "plain_text", "content": "查看日志"},
                  "type": "primary",
                  "url": "http://example.com/logs"
                }
              ]
            }
          ],
          "header": {
            "title": {"tag": "plain_text", "content": "系统通知"}
          }
        }
      }'

5 安全设置指南

为了保护Webhook URL，防止被恶意调用发送垃圾信息，飞书提供了三种安全设置，建议至少配置一种。

自定义关键词：最多设置10个关键词。只有消息内容中包含至少一个已设置的关键词时，消息才会被发送。例如，设置关键词”监控”，那么消息中必须包含”监控”一词。
IP白名单：最多设置10个IP地址或地址段。只有来自这些IP的请求才会被处理。
签名校验：系统提供一个密钥。发送请求时，需要根据时间戳和密钥生成签名，并将签名和时间戳一同放入请求体中。服务器会验证签名是否有效且时间戳与当前时间相差不超过1小时。

启用签名校验后，请求体格式如下：

{
  "timestamp": "1599360473",
  "sign": "计算得到的签名",
  "msg_type": "text",
  "content": {
    "text": "这是一条带签名验证的消息"
  }
}

签名 (sign) 的生成方法（Python示例）如下：

import hashlib
import base64
import hmac
import time

def gen_sign(secret):
    timestamp = int(time.time())
    string_to_sign = f'{timestamp}\n{secret}'
    hmac_code = hmac.new(string_to_sign.encode('utf-8'), digestmod=hashlib.sha256).digest()
    sign = base64.b64encode(hmac_code).decode('utf-8')
    return timestamp, sign

# 使用从飞书机器人安全设置页面获取的SECRET
timestamp, sign = gen_sign("你的SECRET")

6 Shell脚本实战案例

下面是一个综合性的Shell脚本示例，用于发送服务器磁盘使用率告警，并包含安全设置（签名校验）和简单的错误处理。

#!/bin/bash

# 飞书机器人配置
FEISHU_WEBHOOK="https://open.feishu.cn/open-apis/bot/v2/hook/你的Webhook地址"
SECRET="你的签名密钥"  # 如果在安全设置中启用了签名校验则需要

# 生成签名 (如果启用了签名校验)
gen_feishu_sign() {
    local timestamp=$(date +%s)
    local string_to_sign="${timestamp}\n${SECRET}"
    local sign=$(echo -en "$string_to_sign" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)
    echo "$timestamp $sign"
}

# 发送飞书消息函数
send_feishu_alert() {
    local message="$1"
    local message_type="${2:-text}"  # 默认为文本消息

    # 判断是否需要生成签名
    if [[ -n "$SECRET" ]]; then
        read -r timestamp sign <<< "$(gen_feishu_sign)"
        local extra_data="\"timestamp\": \"$timestamp\", \"sign\": \"$sign\","
    else
        local extra_data=""
    fi

    # 构建JSON数据
    local json_data
    case $message_type in
        "text")
            json_data="{\"msg_type\": \"text\", \"content\": {\"text\": \"$message\"}}"
            ;;
        "post")
            json_data="{\"msg_type\": \"post\", \"content\": {\"post\": {\"zh_cn\": {\"title\": \"系统告警\", \"content\": [[{\"tag\": \"text\", \"text\": \"$message\"}]]}}}}"
            ;;
        *)
            json_data="{\"msg_type\": \"text\", \"content\": {\"text\": \"$message\"}}"
            ;;
    esac

    # 如果有签名信息，插入到JSON中
    if [[ -n "$extra_data" ]]; then
        json_data=$(echo "$json_data" | sed "s/{\"/{\"$extra_data\"/")
    fi

    # 发送请求
    response=$(curl -s -w "%{http_code}" -X POST \
        "$FEISHU_WEBHOOK" \
        -H "Content-Type: application/json" \
        -d "$json_data")

    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | head -n -1)

    if [ "$http_code" -eq 200 ]; then
        echo "消息发送成功"
        return 0
    else
        echo "消息发送失败, HTTP代码: $http_code, 响应: $body"
        return 1
    fi
}

# 检查磁盘使用率并发送告警
check_disk_usage() {
    local threshold=90  # 设置阈值百分比
    local usage=$(df / | awk 'NR==2 {print $5}' | sed 's/%//')

    if [ "$usage" -gt "$threshold" ]; then
        local hostname=$(hostname)
        local current_time=$(date "+%Y-%m-%d %H:%M:%S")
        
        local message="🚨 磁盘空间告警 🚨
服务器: $hostname
时间: $current_time
根分区使用率: ${usage}%
状态: ⚠️ 超过阈值 ${threshold}%
建议: 请及时清理磁盘空间 <at user_id=\"all\">所有人</at>"

        echo "检测到磁盘使用率过高，发送告警..."
        send_feishu_alert "$message"
    else
        echo "磁盘使用率正常: ${usage}%"
    fi
}

# 主程序
main() {
    echo "开始检查系统状态..."
    check_disk_usage
    # 可以添加其他检查函数，如内存、CPU等
}

# 执行主程序
main

7 常见问题与调试

返回错误码 19024 (Key Words Not Found)
- 原因：机器人的安全设置中启用了”自定义关键词”，但发送的消息中不包含任何已设置的关键词。
- 解决：在消息内容中加入你设置的关键词，或者修改/关闭自定义关键词设置。
返回错误码 19022 (Ip Not Allowed)
- 原因：启用了IP白名单，但发送请求的服务器IP不在白名单中。
- 解决：将发送请求的服务器IP添加到机器人的IP白名单中。
返回错误码 19021 (sign match fail…)
- 原因：签名校验失败。可能因为时间戳过期（与当前时间相差超过1小时）、服务器时间不准确，或签名计算错误。
- 解决：检查服务器时间是否准确，并确认签名算法是否正确。
消息格式错误或显示异常
- 原因：JSON格式不正确，或特定的消息类型结构有误。
- 解决：使用在线JSON验证工具检查JSON格式。仔细阅读官方文档，确保消息体结构符合对应消息类型的要求。
@某人或@所有人不生效
- 原因：语法错误或ID不正确。@指定成员时，user_id 必须使用正确的 ou_xxxxx 格式的 open_id。@所有人需要群组开启了@所有人功能。

通过本文的介绍，你应该已经掌握了使用飞书自定义机器人通过cURL和Shell脚本发送消息的基本方法。关键在于获取正确的Webhook URL，构造合法的JSON消息体，并根据需要配置好安全设置。