Skip to content

SPEC.md

Latest commit

 

History

History
132 lines (115 loc) · 4.14 KB

SPEC.md

File metadata and controls

132 lines (115 loc) · 4.14 KB
Raw

HA-Lark Integration — HACS Custom Component

Overview

A Home Assistant custom integration that connects HA with Lark/Feishu (飛書). Bidirectional: HA → Lark notifications, Lark → HA commands. Published as a HACS-compatible integration anyone can install.

User Experience

  1. Install via HACS or manual copy
  2. HA Settings → Integrations → Add → "Lark (飛書)"
  3. Enter App ID + App Secret (from Lark Open Platform)
  4. Bot auto-discovers available chats (groups the bot is in + user who authorized)
  5. Select notification targets (private DM / group chat / multiple)
  6. Use notify.lark in any automation

Architecture

Directory Structure

custom_components/lark/
├── __init__.py          # Integration setup
├── manifest.json        # HACS metadata
├── config_flow.py       # UI configuration flow
├── const.py             # Constants
├── notify.py            # HA notify platform (HA → Lark)
├── webhook.py           # Lark → HA webhook handler
├── lark_api.py          # Lark API client wrapper
├── strings.json         # UI strings (English)
├── translations/
│   ├── en.json
│   └── zh-Hant.json     # Traditional Chinese
└── services.yaml        # Custom service definitions

Core Features

1. HA → Lark (Notifications)

  • notify.lark platform service
  • Text messages (plain + rich text/post)
  • Image messages (URL or local camera entity)
  • Interactive cards with action buttons
  • Multiple targets: private DM (open_id) or group chat (chat_id)
  • Target selection in service call data
# Simple text
action: notify.lark
data:
  message: "Motion detected in living room"

# With image
action: notify.lark
data:
  message: "🔔 Doorbell rang"
  data:
    image_url: "http://frigate:5000/api/doorbell/latest.jpg"
    target: "group"  # or specific chat_id / open_id

# Interactive card with buttons
action: notify.lark
data:
  title: "🔔 Someone at the door"
  message: "Detected at {{ now() }}"
  data:
    image_url: "http://frigate:5000/api/doorbell/latest.jpg"
    buttons:
      - text: "Open Door"
        action: switch.turn_on
        entity_id: switch.door_lock
      - text: "Ignore"
        action: dismiss

2. Lark → HA (Commands)

  • Webhook endpoint: /api/webhook/lark_bot
  • Lark bot receives messages → forwards to HA
  • HA fires lark_command event with message content
  • Users can create automations triggered by Lark messages
  • Button callbacks from interactive cards → trigger HA services directly
# Automation triggered by Lark message
trigger:
  - platform: event
    event_type: lark_command
    event_data:
      text: "開燈"
action:
  - action: light.turn_on
    target:
      entity_id: light.living_room

3. Config Flow (UI Setup)

  • Step 1: Enter App ID + App Secret → validate credentials
  • Step 2: Auto-list available chats (groups bot is in)
  • Step 3: Select default notification target(s)
  • Options flow: change targets, add/remove targets later

Lark API Endpoints Used

  • POST /auth/v3/tenant_access_token/internal — get token
  • POST /im/v1/messages — send messages
  • POST /im/v1/images — upload images
  • GET /im/v1/chats — list bot's group chats
  • POST /im/v1/messages/:id/reply — reply to message
  • Event subscription (webhook) — receive messages sent to bot

Requirements

  • Lark Open Platform app with:
    • Bot capability enabled
    • im:message:send_as_bot permission
    • im:chat:readonly permission (to list groups)
    • im:message.receive_v1 event subscription (for Lark → HA)
  • HA instance accessible via URL (for webhook callback from Lark)

HACS Compatibility

  • manifest.json with proper HACS fields
  • hacs.json in repo root
  • GitHub release workflow
  • README with setup instructions + screenshots

Languages

  • English (default)
  • 繁體中文 (zh-Hant)
  • 简体中文 (zh-Hans)

Technical Notes

  • Use aiohttp for async HTTP (HA standard)
  • Token caching with auto-refresh (tenant_access_token expires every 2 hours)
  • Rate limiting awareness (Lark API limits)
  • Image upload: support both URL fetch + local file
  • Webhook verification: use Lark's verification token