Feishu Notifier

Ruby gem and CLI for sending Feishu app notifications. It supports plain text messages, custom interactive cards, existing CardKit card IDs, and existing card template IDs.

Repository: https://github.com/Youngv/feishu-notifier-ruby

Features

  • Sends messages through Feishu im/v1/messages.
  • Uses receive_id_type=user_id.
  • Reads app credentials from .env, environment variables, or --config.
  • Provides built-in card levels: info, debug, and error.
  • Can be used as a CLI or as a Ruby library.

Requirements

  • Ruby 3.2 or newer.
  • This project is developed with Ruby 3.4.7.
  • A Feishu app with permission to send IM messages.
  • A reachable Feishu recipient user_id.

Configuration

Create a .env file:

cp .env.example .env

Required variables:

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=your_app_secret
FEISHU_USER_ID=your_user_id
FEISHU_BASE_URL=https://open.feishu.cn

The local .env file is ignored by git. Do not commit real app secrets.

Development Setup

cd /root/feishu-notifier-ruby
source /usr/local/rvm/scripts/rvm
rvm use ruby-3.4.7
bundle install

Run tests:

bundle exec rake test

CLI Usage

Run from this repository:

bin/feishu-notifier --level info --text "Hello from Ruby"

Run after installing the gem:

feishu-notifier --config /root/feishu-notifier-ruby/.env --level error --text "Something failed"

If the target project has its own .env, run feishu-notifier from that directory without --config.

Plain Text

bin/feishu-notifier --text "Hello from Ruby"

Custom Cards

The --level option sends a custom interactive card. Available levels:

  • info: blue header, default title Info
  • debug: grey header, default title Debug
  • error: red header, default title Error
bin/feishu-notifier --level info --text "Normal notification"
bin/feishu-notifier --level debug --text "Debug details"
bin/feishu-notifier --level error --text "Something failed"

Override the card title:

bin/feishu-notifier --level error --title "Deploy failed" --text "Rollback required"

Existing Cards and Templates

Send an existing CardKit card by card ID:

bin/feishu-notifier --card-id CARD_ID

Send an existing card template by template ID:

bin/feishu-notifier --template-id TEMPLATE_ID

Recipient Override

bin/feishu-notifier --user-id your_user_id --level info --text "Hello"

Dry Run

Use --dry-run to print the request summary without calling Feishu:

bin/feishu-notifier --dry-run --level error --title "Gem check" --text "Installed executable works"

Ruby Library Usage

Add the gem to another Ruby project, or install the local gem first.

require "feishu_notifier"

FeishuNotifier::EnvFile.load("/root/feishu-notifier-ruby/.env")
config = FeishuNotifier::Config.from_env
client = FeishuNotifier::Client.new(config: config)

card = FeishuNotifier::Card.custom(
  level: "error",
  title: "Task failed",
  text: "Check logs"
)

client.send_card(card)

Send plain text:

client.send_text("Hello from Ruby")

Build and Install

Build the gem:

gem build feishu_notifier.gemspec

Install the generated gem:

gem install ./feishu_notifier-0.1.1.gem

Project Layout

  • bin/feishu-notifier: CLI executable.
  • lib/feishu_notifier/client.rb: Feishu API client.
  • lib/feishu_notifier/card.rb: Card content builders.
  • lib/feishu_notifier/config.rb: Environment-based configuration.
  • lib/feishu_notifier/env_file.rb: Minimal .env loader.
  • lib/feishu_notifier/version.rb: Gem version.
  • test/: Minitest coverage.

Permissions

The Feishu app must be enabled in the target tenant and have permission to send IM messages. The recipient must be reachable by user_id.