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

• 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.

• 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.

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.

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

Install from RubyGems:

gem install feishu_notifier

Then run:

feishu-notifier --config /path/to/.env --level info --text "Hello from Ruby"

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.

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

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"

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

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

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"

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 the gem:

gem build feishu_notifier.gemspec

Install the generated gem:

gem install ./feishu_notifier-0.1.1.gem

• 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.

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.