Skip to content

README.md

Latest commit

 

History

History
287 lines (214 loc) · 7.24 KB

README.md

File metadata and controls

287 lines (214 loc) · 7.24 KB
Raw

Lark (飛書) Integration for Home Assistant

hacs_badge

A Home Assistant custom integration that enables bidirectional communication with Lark/Feishu (飛書). Send notifications from Home Assistant to Lark and trigger automations from Lark messages.

Features

✨ HA → Lark Notifications

  • Send text messages, images, and rich interactive cards
  • Support for action buttons in cards
  • Multiple notification targets (private DMs and group chats)
  • Easy integration with Home Assistant automations

🔔 Lark → HA Commands

  • Receive messages from Lark bot
  • Trigger Home Assistant automations from Lark
  • Interactive button callbacks execute HA services directly
  • Event-based architecture for flexible automation

🌍 Multi-language Support

  • English
  • 繁體中文 (Traditional Chinese)
  • 简体中文 (Simplified Chinese)

Installation

HACS (Recommended)

  1. Open HACS in your Home Assistant instance
  2. Click on "Integrations"
  3. Click the three dots in the top right corner
  4. Select "Custom repositories"
  5. Add this repository URL: https://github.com/calvinastroboy/ha-lark-integration
  6. Select category: "Integration"
  7. Click "Add"
  8. Find "Lark (飛書)" in the integration list and click "Download"
  9. Restart Home Assistant

Manual Installation

  1. Download the latest release from GitHub
  2. Copy the custom_components/lark folder to your Home Assistant config/custom_components/ directory
  3. Restart Home Assistant

Configuration

Prerequisites

Before setting up this integration, you need to create a Lark bot application:

  1. Go to Lark Open Platform
  2. Create a new app or use an existing one
  3. Enable the bot capability
  4. Add the following permissions:
    • im:message:send_as_bot (send messages as bot)
    • im:chat:readonly (read chat list)
    • im:message (receive messages)
  5. Subscribe to the following events:
    • im.message.receive_v1 (receive messages)
  6. Note down your App ID and App Secret

Setup in Home Assistant

  1. Go to Settings → Devices & Services
  2. Click + Add Integration
  3. Search for Lark (or 飛書)
  4. Enter your App ID and App Secret
  5. Select default notification target chats (you can change this later)
  6. Click Submit

Webhook Configuration

After setup, you need to configure the webhook URL in Lark:

  1. Get your webhook URL from the integration settings:
    • Format: https://your-ha-instance.com/api/webhook/<webhook_id>
  2. Go to your Lark app settings → Event Subscriptions
  3. Enter the webhook URL
  4. Lark will send a verification request
  5. Save the configuration

Note: Your Home Assistant instance must be accessible from the internet for webhooks to work.

Usage

Sending Notifications (HA → Lark)

Simple Text Message

action: notify.lark
data:
  message: "Motion detected in living room"

Message with Title

action: notify.lark
data:
  title: "Security Alert"
  message: "Front door opened at {{ now() }}"

Image Notification

action: notify.lark
data:
  message: "🔔 Doorbell rang"
  data:
    image_url: "http://your-camera-ip/snapshot.jpg"

Interactive Card with Buttons

action: notify.lark
data:
  title: "🔔 Someone at the door"
  message: "Detected at {{ now().strftime('%H:%M:%S') }}"
  data:
    image_url: "http://frigate.local:5000/api/doorbell/latest.jpg"
    buttons:
      - text: "Open Door"
        action: switch.turn_on
        entity_id: switch.door_lock
      - text: "Turn on Light"
        action: light.turn_on
        entity_id: light.entrance
      - text: "Ignore"
        action: dismiss

Specify Target

You can override the default target in each notification:

action: notify.lark
data:
  message: "Test message"
  target: "oc_abc123xyz"  # Specific chat_id or open_id

Receiving Commands (Lark → HA)

Trigger Automation from Lark Message

automation:
  - alias: "Turn on lights from Lark"
    trigger:
      - platform: event
        event_type: lark_command
        event_data:
          text: "開燈"
    action:
      - action: light.turn_on
        target:
          entity_id: light.living_room
      - action: notify.lark
        data:
          message: "✅ Living room light turned on"

Handle Button Callbacks

When a user clicks a button in an interactive card, the integration automatically executes the specified action. You can also listen for the event:

automation:
  - alias: "Log button presses"
    trigger:
      - platform: event
        event_type: lark_button_callback
    action:
      - action: logbook.log
        data:
          name: "Lark Button"
          message: "Action: {{ trigger.event.data.action }}, Entity: {{ trigger.event.data.entity_id }}"

Advanced Configuration

Multiple Targets

Send notifications to multiple chats:

action: notify.lark
data:
  message: "System update completed"
  target:
    - "oc_abc123xyz"
    - "oc_def456uvw"

Target Types

Specify whether the target is a user or chat:

action: notify.lark
data:
  message: "Direct message"
  data:
    target_type: "open_id"  # For direct messages to users
  target: "ou_user123"

Default is chat_id for group chats.

Events

lark_command

Fired when a message is received from Lark.

Event Data:

  • message_type: Type of message (text, image, etc.)
  • content: Full message content
  • text: Extracted text from message
  • sender_id: ID of the sender
  • chat_id: ID of the chat
  • message_id: ID of the message

lark_button_callback

Fired when a button in an interactive card is clicked.

Event Data:

  • action: The action type (e.g., "switch.turn_on")
  • entity_id: The target entity
  • sender_id: ID of the user who clicked
  • message_id: ID of the message

Troubleshooting

Notifications not sending

  1. Check that your App ID and App Secret are correct
  2. Verify the bot is added to the target chat
  3. Check Home Assistant logs for error messages
  4. Ensure the chat_id is correct (check in Lark app settings)

Webhooks not working

  1. Ensure your Home Assistant instance is accessible from the internet
  2. Verify the webhook URL is correctly configured in Lark
  3. Check that Lark has successfully verified the webhook URL
  4. Check Home Assistant logs for incoming webhook requests

Bot not in chat list

  1. Add the bot to the desired chat in Lark
  2. The bot must be a member of the chat to send messages
  3. Refresh the integration options to see updated chat list

Support

If you encounter any issues or have questions:

  1. Check the Issues page
  2. Search for existing solutions
  3. Create a new issue with detailed information:
    • Home Assistant version
    • Integration version
    • Error logs
    • Steps to reproduce

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Developed by calvinastroboy

Note: This integration is not officially affiliated with Lark/Feishu or ByteDance.