Bird Buddy ↔ Home Assistant Skill#

This skill walks you through a complete production-grade Bird Buddy integration with Home Assistant: custom component, live camera entity, Telegram notifications, and a purpose-built dashboard.

---

Variable Reference#

Substitute these placeholders wherever you see {{VAR}} in config snippets and reference files.

VariableDescriptionExample{{HA_CONFIG_DIR}}HA config directory on disk/home/mike/homeassistant (Docker) or /config (HA OS){{FEEDER_ID}}Bird Buddy feeder UUID (from HA entity attributes)xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``{{TELEGRAM_BOT_TOKEN}}Telegram Bot API token123456789:AAF...``{{TELEGRAM_CHAT_ID}}Telegram chat/group ID (integer, negative for groups)-1001234567890``{{TELEGRAM_THREAD_ID}}Telegram message thread / topic ID42``{{HA_URL}}Home Assistant base URLhttp://homeassistant.local:8123``{{HA_TOKEN}}Long-lived HA access tokencreated in HA Profile → Security

---

Step 1 — Install ha-birdbuddy Custom Component#

Option A: HACS (recommended)

1. Open HACS → Integrations → ⋮ menu → Custom repositories
2. Add https://github.com/jhansche/ha-birdbuddy as an Integration
3. Search "Bird Buddy" → Download (version 0.0.21 tested)
4. Restart Home Assistant

Option B: Manual

bash

mkdir -p {{HA_CONFIG_DIR}}/custom_components/birdbuddy
# Clone or download release tarball from https://github.com/jhansche/ha-birdbuddy
cp -r ha-birdbuddy/custom_components/birdbuddy/* {{HA_CONFIG_DIR}}/custom_components/birdbuddy/

After installing, go to Settings → Devices & Services → Add Integration and search "Bird Buddy". Enter your Bird Buddy account credentials.

Account note: If using a member account (not the feeder owner), the owner must add you as a member in the Bird Buddy app AND explicitly grant postcards and livestream access.

---

Step 2 — Add Camera Platform to Component#

The v0.0.21 component does not include the camera platform by default. You must:

1. Copy references/camera.py to {{HA_CONFIG_DIR}}/custom_components/birdbuddy/camera.py
2. Edit {{HA_CONFIG_DIR}}/custom_components/birdbuddy/__init__.py and add Platform.CAMERA to the PLATFORMS list:

python

from homeassistant.const import Platform

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

1. Restart Home Assistant. A new entity camera.bird_buddy_camera will appear.

---

Step 3 — Configure rest_command#

Bird Buddy automations send Telegram messages via rest_command.

3a. Add include to configuration.yaml#

bash

# Docker: configuration.yaml may be root-owned — use the move trick
cd {{HA_CONFIG_DIR}}
mv configuration.yaml configuration.yaml.bak
cp configuration.yaml.bak configuration.yaml
# Now edit as your user

Add to configuration.yaml:

yaml

rest_command: !include rest_commands.yaml

3b. Create rest_commands.yaml#

Copy references/rest_commands.yaml to {{HA_CONFIG_DIR}}/rest_commands.yaml and substitute your Telegram values.

The final file should look like:

yaml

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"
    }

⚠️ chat_id must be a bare integer, not a quoted string. "-1001234567890" will be rejected by the Telegram API; use -1001234567890.

Restart HA after editing configuration.yaml.

---

Step 4 — Create input_boolean Notification Toggles#

Create these five helpers via Settings → Helpers → Create Helper → Toggle, or via the HA WebSocket API:

Entity IDNameinput_boolean.bird_buddy_new_bird_detectedBird Buddy - New Bird Detectedinput_boolean.bird_buddy_rare_species_alertBird Buddy - Rare Species Alertinput_boolean.bird_buddy_low_battery_alertBird Buddy - Low Battery Alertinput_boolean.bird_buddy_offline_alertBird Buddy - Offline Alertinput_boolean.bird_buddy_daily_summaryBird Buddy - Daily Summary

Enable the toggles you want active.

---

Step 5 — Import Automations#

Copy references/automations.yaml contents into your {{HA_CONFIG_DIR}}/automations.yaml.

If automations.yaml doesn't exist yet, create it (empty list [] to start). HA includes it automatically if you have automation: !include automations.yaml in configuration.yaml (it's the default for new installs).

The six automations cover:

IDTriggerConditionbirdbuddy_new_bird_detected``birdbuddy_new_postcard_sighting eventtoggle enabledbirdbuddy_rare_species_alertsame event + hasNewSpecies == truetoggle enabledbirdbuddy_low_battery_alertbattery sensor < 20%toggle enabledbirdbuddy_feeder_offlinefeeder state → offlinetoggle enabledbirdbuddy_feeder_onlinefeeder state from offlinetoggle enabledbirdbuddy_daily_summarytime trigger 00:00 UTC (8 PM ET)toggle enabled

Each automation calls rest_command.birdbuddy_telegram_notify.

You must supply token, chat_id, and thread_id in the data: block of each action — or inject them via input_text helpers / secrets.yaml for a cleaner setup.

Reload automations: Developer Tools → YAML → Automations or restart HA.

---

Step 6 — Create the Bird Buddy Dashboard#

Use the HA WebSocket API (or the UI) to create a dashboard at path bird-buddy.

⚠️ The url_path must contain a hyphen — birdbuddy (no hyphen) is rejected by HA. Use bird-buddy.

Via WebSocket (curl + websocat or HA REST)#

bash

# Long-lived token required
export HA_URL="{{HA_URL}}"
export HA_TOKEN="{{HA_TOKEN}}"

# 1. Create the dashboard shell
curl -s -X POST "$HA_URL/api/lovelace/dashboards" \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url_path": "bird-buddy",
    "title": "Bird Buddy",
    "icon": "mdi:bird",
    "show_in_sidebar": true
  }'

# 2. Save dashboard config (see assets/dashboard_config.json)

Via UI#

1. Settings → Dashboards → Add Dashboard
2. Title: "Bird Buddy", URL path: bird-buddy, Icon: mdi:bird
3. Open dashboard → Edit → Raw config editor
4. Paste contents of assets/dashboard_config.json

The dashboard includes:

• Camera card — live snapshot from camera.bird_buddy_camera
• Glance card — battery, temperature, food level, signal, feeder state
• Entity card — last recent visitor sensor
• Entities card — all five notification toggle switches

---

Step 7 — Verify Everything Works#

bash

# Check the camera entity exists
curl -s "$HA_URL/api/states/camera.bird_buddy_camera" \
  -H "Authorization: Bearer $HA_TOKEN" | python3 -m json.tool

# Trigger a test notification (fill in your values)
curl -s -X POST "$HA_URL/api/services/rest_command/birdbuddy_telegram_notify" \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "{{TELEGRAM_BOT_TOKEN}}",
    "chat_id": {{TELEGRAM_CHAT_ID}},
    "thread_id": {{TELEGRAM_THREAD_ID}},
    "message": "🐦 Bird Buddy HA integration test!"
  }'

Watch HA logs for camera snapshot activity:

bash

# Docker example
docker logs homeassistant 2>&1 | grep -i birdbuddy

---

Gotchas & Known Issues#

1. Telegram chat_id must be integer — pass -1001234567890, not "-1001234567890". The Telegram API rejects string-formatted chat IDs in JSON payloads from rest_command.

2. configuration.yaml may be root-owned in Docker HA — nano or direct edits may fail with permission denied. Use the move trick: mv configuration.yaml configuration.yaml.bak && cp configuration.yaml.bak configuration.yaml to create a user-owned copy.

3. watchingActiveKeep returns RESOURCE_NOT_FOUND when feeder is DEEP_SLEEP — this is expected behavior. The watching/streaming API is only available when the feeder is awake. The camera entity returns the cached postcard thumbnail instead.

4. Platform.CAMERA must be added to PLATFORMS in __init__.py — the v0.0.21 release does not ship a camera.py. Without adding Platform.CAMERA to PLATFORMS, HA will never call async_setup_entry in camera.py.

5. Lovelace dashboard url_path must contain a hyphen — birdbuddy is rejected; bird-buddy works. This is an HA URL slug validation rule.

6. Food level sensor always reports low — this is a known bug in the ha-birdbuddy integration (or Bird Buddy API). It does not reflect actual hardware food level. Ignore this sensor value until the integration is fixed.

7. content_type: "application/json" in rest_command — do NOT use a headers: block with Content-Type. Use the top-level content_type: key instead, otherwise the payload may not be parsed correctly by HA.

8. Member account needs explicit permission — if you're authenticating with a Bird Buddy member account (not the feeder owner), the feeder owner must add you as a member AND separately grant postcards and livestream access inside the Bird Buddy mobile app.

9. me.feed query for postcards access — member accounts use me.feed for recent postcards. The field FeederForMember.recentPostcards does not exist in the API; attempting to query it returns a schema error.

10. WatchingStartV2 returns REQUESTED when feeder is DEEP_SLEEP — the streamUrl field only populates after the feeder wakes and transitions to STREAMING or READY_TO_STREAM. The camera.py polls with watchingActiveKeep for up to 45 seconds before giving up and returning the cached image.

---

Reference Files#

FilePurposereferences/camera.pyComplete HA camera entity with GraphQL watching API + postcard thumbnail cachingreferences/automations.yamlAll six automations with placeholder variablesreferences/rest_commands.yamlTelegram rest_command templateassets/dashboard_config.jsonLovelace dashboard YAML/JSON config

---

Sensor Entity IDs (ha-birdbuddy v0.0.21)#

These are the entity IDs created by the integration. Adjust if yours differ (check Settings → Entities and filter by "Bird Buddy").

EntityDescriptionsensor.birdbuddy_batteryBattery % (0–100)sensor.birdbuddy_temperatureAmbient temperature (°F or °C per HA settings)sensor.birdbuddy_food_levelFood level (⚠️ always reports low — known bug)sensor.birdbuddy_signal_strengthWiFi signal (attribute level)sensor.birdbuddy_feeder_stateFeeder state: online, offline, deep_sleep, taking_postcards, etc.sensor.birdbuddy_recent_visitorSpecies name of last recorded visitorcamera.bird_buddy_cameraLive snapshot camera (added by this skill)