Bird Buddy ↔ Home Assistant Skill

intent

this skill walks you through a complete production-grade bird buddy integration with home assistant. you'll install the ha-birdbuddy custom component, add a live camera entity that polls the graphql watching api, set up five notification automations (new bird, rare species, low battery, offline, daily summary), configure telegram routing, and build a dashboard. use this when you want full bird feeder observability in HA with zero manual checks.

inputs

External Connections:

• Bird Buddy Account: owned or member account with API access. member accounts require explicit permission grant from feeder owner (postcards + livestream access in bird buddy app).
• Home Assistant: v2024.1+ running locally or in docker. long-lived token required for api calls (create in HA Profile → Security).
• Telegram Bot: created via @BotFather on telegram. requires bot token and chat/group id (negative integer for groups). optional: topic/thread id if using telegram topics.

Required Variables (substitute in all config snippets):

Variable	Description	Example
{{HA_CONFIG_DIR}}	HA config directory on disk	/home/mike/homeassistant or /config
{{FEEDER_ID}}	Bird Buddy feeder UUID from HA entity attributes	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
{{TELEGRAM_BOT_TOKEN}}	Telegram Bot API token	123456789:AAF...
{{TELEGRAM_CHAT_ID}}	Telegram chat/group id, bare integer	-1001234567890 (NOT quoted)
{{TELEGRAM_THREAD_ID}}	Telegram topic id (optional)	42
{{HA_URL}}	Home Assistant base url	http://homeassistant.local:8123
{{HA_TOKEN}}	Long-lived HA access token	created in HA Profile → Security

Files Needed (from skill references):

• references/camera.py - custom camera platform with graphql watching api
• references/automations.yaml - six notification automations
• references/rest_commands.yaml - telegram rest_command template
• assets/dashboard_config.json - lovelace dashboard config

procedure

Step 1: Install ha-birdbuddy Custom Component

1a. Input: ha-birdbuddy repository url https://github.com/jhansche/ha-birdbuddy, version 0.0.21 or later. 1b. HACS path (recommended): Open HACS → Integrations → ⋮ menu → Custom repositories. Paste repo url as Integration type. Search "Bird Buddy" → Download. 1c. Manual path: Run mkdir -p {{HA_CONFIG_DIR}}/custom_components/birdbuddy. Clone or download release tarball. Copy ha-birdbuddy/custom_components/birdbuddy/* to {{HA_CONFIG_DIR}}/custom_components/birdbuddy/. 1d. Restart Home Assistant (both paths). 1e. Output: custom component installed. Go to Settings → Devices & Services → Add Integration. Search "Bird Buddy". Enter your bird buddy account email + password. 1f. Verification: integration appears in Settings → Devices & Services. feeder entities (sensor.birdbuddy_*) visible in Settings → Entities.

Step 2: Add Camera Platform to Component

2a. Input: references/camera.py file. 2b. Output: copy camera.py to {{HA_CONFIG_DIR}}/custom_components/birdbuddy/camera.py. 2c. Edit init file: open {{HA_CONFIG_DIR}}/custom_components/birdbuddy/__init__.py. locate the PLATFORMS list. add Platform.CAMERA to the list. 2d. Input/Output example:

from homeassistant.const import Platform

PLATFORMS = [
    Platform.BINARY_SENSOR,
    Platform.SENSOR,
    Platform.CAMERA,           # ← add this line
]

2e. Restart Home Assistant. 2f. Verification: entity camera.bird_buddy_camera appears in Settings → Entities.

Step 3: Configure rest_command for Telegram

3a. Input: {{HA_CONFIG_DIR}}/configuration.yaml file. references/rest_commands.yaml template. 3b. Backup and edit config.yaml: if docker, use move trick: mv configuration.yaml configuration.yaml.bak && cp configuration.yaml.bak configuration.yaml. add line rest_command: !include rest_commands.yaml to configuration.yaml. 3c. Create rest_commands.yaml: copy references/rest_commands.yaml to {{HA_CONFIG_DIR}}/rest_commands.yaml. substitute {{TELEGRAM_BOT_TOKEN}}, {{TELEGRAM_CHAT_ID}}, {{TELEGRAM_THREAD_ID}} with your actual values. 3d. Output file should look like:

birdbuddy_telegram_notify:
  url: "https://api.telegram.org/bot{{TELEGRAM_BOT_TOKEN}}/sendMessage"
  method: POST
  content_type: "application/json"
  payload: >-
    {
      "chat_id": {{TELEGRAM_CHAT_ID}},
      "message_thread_id": {{TELEGRAM_THREAD_ID}},
      "text": "{{ message }}",
      "parse_mode": "Markdown"
    }

3e. Restart Home Assistant. 3f. Verification: Settings → Developer Tools → Services. search "rest_command". birdbuddy_telegram_notify service appears.

Step 4: Create input_boolean Notification Toggles

4a. Input: five toggle names. 4b. Via UI: Settings → Helpers → Create Helper → Toggle. create each of these:

• input_boolean.bird_buddy_new_bird_detected (name: Bird Buddy - New Bird Detected)
• input_boolean.bird_buddy_rare_species_alert (name: Bird Buddy - Rare Species Alert)
• input_boolean.bird_buddy_low_battery_alert (name: Bird Buddy - Low Battery Alert)
• input_boolean.bird_buddy_offline_alert (name: Bird Buddy - Offline Alert)
• input_boolean.bird_buddy_daily_summary (name: Bird Buddy - Daily Summary)

4c. Output: five toggle entities created in HA. enable the toggles you want active (automations check these before firing). 4d. Verification: Settings → Entities. filter by "bird_buddy". all five toggles present and switchable.

Step 5: Import Automations

5a. Input: references/automations.yaml file. {{HA_CONFIG_DIR}}/automations.yaml (may not exist yet). 5b. Check/create automations.yaml: if file doesn't exist, create empty list []. if file exists, ensure automation: !include automations.yaml is in configuration.yaml (default for new installs). 5c. Copy automations: append or merge contents of references/automations.yaml into {{HA_CONFIG_DIR}}/automations.yaml. the six automations handle: new bird detected, rare species alert, low battery alert, feeder offline, feeder online, daily summary at 00:00 utc. 5d. Output: automations.yaml contains all six automations with triggers, conditions (check input_boolean toggles), and actions (call rest_command.birdbuddy_telegram_notify). 5e. Reload automations: Developer Tools → YAML → Automations. or restart HA. 5f. Verification: Settings → Automations & Scenes → Automations. all six bird buddy automations listed and enabled.

Step 6: Create the Bird Buddy Dashboard

6a. Input: assets/dashboard_config.json file. HA long-lived token. HA base url. 6b. Via UI (simpler): Settings → Dashboards → Create Dashboard. title: "Bird Buddy". url_path: "bird-buddy" (hyphen required). icon: "mdi:bird". show_in_sidebar: true. click create. 6c. Add cards to dashboard: open new dashboard. click edit (pencil). click raw config editor. paste entire contents of assets/dashboard_config.json. 6d. Output: dashboard deployed at /lovelace/bird-buddy with these cards:

• camera card showing live camera.bird_buddy_camera snapshot
• glance card showing battery %, temperature, food level, signal strength, feeder state
• entity card showing last recent visitor sensor
• entities card showing all five notification toggle switches

6e. Verification: navigate to dashboard url. camera snapshot loads. glance cards show sensor values. toggles are clickable.

Step 7: Verify Everything Works

7a. Input: {{HA_URL}}, {{HA_TOKEN}}, {{TELEGRAM_BOT_TOKEN}}, {{TELEGRAM_CHAT_ID}}, {{TELEGRAM_THREAD_ID}}. 7b. Check camera entity exists: run curl -s "{{HA_URL}}/api/states/camera.bird_buddy_camera" -H "Authorization: Bearer {{HA_TOKEN}}" | python3 -m json.tool. output shows camera state + attributes. 7c. Send test telegram notification: run rest_command test via Developer Tools → Services or curl:

curl -s -X POST "{{HA_URL}}/api/services/rest_command/birdbuddy_telegram_notify" \
  -H "Authorization: Bearer {{HA_TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{"message": "🐦 Bird Buddy HA integration test!"}'

7d. Output: telegram message arrives in your chat/topic within 2 seconds. 7e. Watch HA logs (docker example): docker logs homeassistant 2>&1 | grep -i birdbuddy. look for successful camera platform load and graphql api calls. 7f. Trigger a real automation: take a photo in bird buddy app. wait 30 seconds. check if new bird notification toggle is on and telegram message fired (if toggle enabled).

decision points

if using hacs (most common): follow step 1b. if you don't have hacs installed yet, install hacs first from https://hacs.xyz.

else if hacs not available or blocked: follow step 1c manual installation path.

if your HA config.yaml is root-owned in docker: use the move trick in step 3b (mv configuration.yaml configuration.yaml.bak && cp configuration.yaml.bak configuration.yaml). nano or direct edits will fail with permission denied.

if you are a member account (not feeder owner): the feeder owner must add you as a member in the bird buddy app AND explicitly grant you access to postcards + livestream. without explicit grant, the integration will fail auth and you'll see "permission denied" in logs.

if feeder is in deep_sleep mode: camera.py will poll graphql watchingActiveKeep for up to 45 seconds, get "RESOURCE_NOT_FOUND", then fall back to cached postcard thumbnail. this is expected behavior. live stream only works when feeder is awake (online or taking postcards).

if you want telegram messages in a topic (not main chat): set {{TELEGRAM_THREAD_ID}} to your topic id. omit this field if using main chat. message_thread_id in rest_commands.yaml will be ignored if {{TELEGRAM_THREAD_ID}} is empty.

if you don't have telegram set up: skip steps 3 and 5 (rest_command + automations). you can still use the dashboard and camera entity for manual checks.

if camera.py fails to load or camera entity doesn't appear: verify Platform.CAMERA is in init.py PLATFORMS list (step 2c). restart HA. check logs for import errors or schema mismatches in camera.py syntax.

if automations fire but telegram doesn't send: verify rest_command.birdbuddy_telegram_notify exists (step 3f). check that {{TELEGRAM_CHAT_ID}} is a bare integer (not quoted string). verify bot token is correct. check HA error logs for telegram api 400/401 errors.

if food_level sensor always reports "low": this is a known bug in ha-birdbuddy or bird buddy api. do not rely on this sensor. it does not reflect actual feeder hardware state. ignore until integration is fixed upstream.

output contract

success looks like:

1. Integration installed: Settings → Devices & Services shows "Bird Buddy" integration. feeder entity list includes sensor.birdbuddy_battery, sensor.birdbuddy_temperature, sensor.birdbuddy_signal_strength, sensor.birdbuddy_feeder_state, sensor.birdbuddy_recent_visitor.

2. Camera entity created: camera.bird_buddy_camera exists in Settings → Entities. entity state is "idle" or "streaming". attributes include entity_picture url pointing to current snapshot.

3. rest_command registered: Developer Tools → Services lists rest_command.birdbuddy_telegram_notify as callable service.

4. Five toggles created: Settings → Helpers shows five input_boolean entities with names matching step 4 list. all are switchable on/off.

5. Six automations loaded: Settings → Automations & Scenes → Automations lists six automations with ids: birdbuddy_new_bird_detected, birdbuddy_rare_species_alert, birdbuddy_low_battery_alert, birdbuddy_feeder_offline, birdbuddy_feeder_online, birdbuddy_daily_summary. all show "enabled" status.

6. Dashboard deployed: Settings → Dashboards shows "Bird Buddy" dashboard. url_path is "bird-buddy" (with hyphen). navigating to /lovelace/bird-buddy renders dashboard with camera + glance + entity cards without errors.

7. Test notification sent: telegram message "🐦 Bird Buddy HA integration test!" appears in configured chat/topic within 2 seconds of step 7c curl command.

8. Logs clean: HA logs show no birdbuddy integration errors, auth failures, or graphql schema errors. camera entity logs show successful graphql queries or expected "RESOURCE_NOT_FOUND" when feeder is deep_sleep.

outcome signal

you know the skill worked when:

• dashboard loads instantly with live bird buddy camera snapshot, glance cards showing green battery/signal/online status, and toggle switches responsive to clicks.

• first bird detection fires automatically: bird buddy app detects a visitor. within 30 seconds, input_boolean.bird_buddy_new_bird_detected toggles on (if enabled). telegram message arrives in your chat with species name + timestamp.

• rare species alerts work: when a species marked "rare" in bird buddy is detected, both new bird AND rare species automations fire. you get two telegram messages.

• low battery alert triggers: when sensor.birdbuddy_battery drops below 20%, automation fires (if toggle enabled) and telegram message arrives immediately.

• offline/online state changes propagate: unplug feeder. within 2 minutes, sensor.birdbuddy_feeder_state changes to "offline". offline automation fires. telegram message says "feeder offline". plug feeder back in. within 2 minutes, state changes to "online" and online automation fires.

• daily summary at midnight utc: at 00:00 utc each day (8 pm et if in est), telegram message arrives with postcard count from previous 24 hours (if toggle enabled).

• no manual intervention needed: after step 7, zero clicks required. all notifications, state updates, camera snapshots flow automatically. dashboard updates in real time without refresh.

---

Reference Files

File	Purpose
references/camera.py	complete ha camera entity with graphql watching api polling + postcard thumbnail caching. handles deep_sleep fallback.
references/automations.yaml	six automations with triggers (events, state changes, time), conditions (toggle checks), actions (rest_command calls). includes all placeholder vars.
references/rest_commands.yaml	telegram rest_command template with payload, content_type, method. substitute bot token, chat id, thread id.
assets/dashboard_config.json	lovelace dashboard raw config. includes camera card, glance card, entity card, entities card.

Sensor Entity IDs (ha-birdbuddy v0.0.21)

Entity	Description
sensor.birdbuddy_battery	battery % (0-100). platform calls bird buddy graphql every 60 sec.
sensor.birdbuddy_temperature	ambient temperature (fahrenheit or celsius per HA settings).
sensor.birdbuddy_food_level	food level (always reports "low" - known bug, ignore).
sensor.birdbuddy_signal_strength	wifi signal strength (attribute level).
sensor.birdbuddy_feeder_state	feeder state: online, offline, deep_sleep, taking_postcards, error.
sensor.birdbuddy_recent_visitor	species name of last recorded visitor (updates on each new postcard).
camera.bird_buddy_camera	live snapshot (added by step 2). polls graphql watching api for live stream when feeder awake. falls back to postcard thumbnail if deep_sleep or stream unavailable.

Known Issues & Workarounds

1. chat_id must be bare integer: pass -1001234567890 not "-1001234567890". telegram api rejects quoted strings in json payloads.

2. configuration.yaml may be root-owned in docker: use move trick in step 3b to create user-owned copy. nano/vim direct edits will fail permission denied.

3. watchingActiveKeep returns RESOURCE_NOT_FOUND when feeder deep_sleep: expected behavior. camera.py retries for 45 sec then returns cached postcard. live stream only available when feeder awake.

4. Platform.CAMERA must be in PLATFORMS list: v0.0.21 does not ship camera.py or include Platform.CAMERA in init.py. without adding it, HA never calls async_setup_entry for camera platform.

5. lovelace url_path must contain hyphen: birdbuddy (no hyphen) rejected by HA slug validation. use bird-buddy.

6. food_level sensor always "low": known bug in integration or api. do not rely on this value. ignore until fixed upstream.

7. content_type top-level key only: do NOT use headers: block with Content-Type in rest_commands.yaml. use content_type: "application/json" at top level. otherwise payload not parsed by HA.

8. member account needs explicit grant: if using member account (not feeder owner), owner must add you as member in bird buddy app AND separately grant postcards + livestream access. without both, auth fails.

9. me.feed for member postcard access: member accounts query me.feed for recent postcards. field FeederForMember.recentPostcards does not exist in api. querying it returns schema error.

10. WatchingStartV2 returns REQUESTED when deep_sleep: streamUrl field only populates after feeder wakes to STREAMING or READY_TO_STREAM. camera.py handles this by polling watchingActiveKeep up to 45 sec before timeout.

11. rate limits on graphql: bird buddy api may rate-limit repeated queries. camera.py includes exponential backoff. if you see "too many requests" errors, increase graphql poll interval (default 60 sec).

12. network timeout on slow connections: if ha-birdbuddy graphql calls timeout, increase request timeout in custom component code. default is often 10 sec. check logs for timeout errors.

original author: jhansche (ha-birdbuddy) / clawhub (skill).