Bird Buddy Home Assistant Integration

Custom integration for Bird Buddy.

This component makes use of the pybirdbuddy library for API calls, also available on PyPI.

Requirements

• Home Assistant 2026.7.1 or newer (Python 3.14).
• A Bird Buddy account. You will need its email and password.

Note

If your Bird Buddy account was created using SSO (Google, Facebook, etc), those methods will not work currently. To work around that, you can sign up a new account using email and password, and then invite that new account as a member of your main/owner account. Be aware that certain information or functionality may not be available to member accounts (for example, "off-grid" settings and firmware version).

Alternatively, you may reset the Bird Buddy unit and re-pair it with a new account that was created with a password. See Bird Buddy support for more information.

Installation

With HACS

1. Open HACS Settings and add this repository (https://github.com/jhansche/ha-birdbuddy/) as a Custom Repository (use Integration as the category).
2. The Bird Buddy page should automatically load (or find it in the HACS Store)
3. Click Install
4. Continue to Setup

Alternatively, click on the button below to add the repository:

Manual

Copy the birdbuddy directory from custom_components in this repository, and place inside your Home Assistant Core installation's custom_components directory.

Setup

1. Install this integration.
2. Navigate to the Home Assistant Integrations page (Settings --> Devices & Services)
3. Click the + Add Integration button in the bottom-right
4. Search for Bird Buddy

Alternatively, click on the button below to add the integration:

Devices

A device is created for each Bird Buddy feeder associated with the account. See below for the entities available.

Entities

Entity	Entity Type	Notes
Audio	switch	Whether recorded visitor videos will include audio.
Battery	sensor	Current Bird Buddy battery percentage
Charging	binary_sensor	Whether the Bird Buddy is currently charging
Off-Grid	switch	Present and toggle Off-Grid status (owners only)
Power Profile	select	Choose between the Power Profile settings the feeder reports.
Recent Visitor	sensor	State represents the most recent visitor's bird species name, and the entity_picture points to the first image on that postcard.
State	sensor	Current state (ready, offline, etc)
Signal	sensor	Current wifi signal (RSSI)
Update	update	Show and install Firmware updates (owners only)

Some entities are disabled or hidden by default, if they represent an advanced use case (for example, the "Signal" and "Recent Visitor" entities). There are also some entities that are disabled by default because the support is not yet enabled by the Bird Buddy API (for example, the Temperature and Food Level sensors are not yet enabled by Bird Buddy).

More entities may be added in the future.

Media

Bird species and sightings that have already been collected from postcards can be viewed in the Home Assistant Media Browser. To collect a postcard you will need to use the mobile app to open the postcards as they arrive. Only opened postcards can be viewed in the Media Browser (same as the Collections tab in the Bird Buddy app).

Events

birdbuddy_new_postcard

This event is fired when a new postcard is detected in the feed and Bird Buddy has identified its species.

Field	Description
postcard_id	Id of the postcard. Pass this to the birdbuddy.collect_postcard service to collect the postcard.
feeder_id	Id of the feeder that captured the postcard, or null. Can be used to filter/target automations.
species	List of recognized species (each an { "id", "name" } object). Empty when nothing was recognized.
media	The first image on the postcard ({ "contentUrl", "thumbnailUrl", ... }), or null.

media.contentUrl and media.thumbnailUrl are time-sensitive URLs that can be used to download the postcard image. The event carries the media object as Bird Buddy returns it, so these keys keep the API's spelling. Every media item has a thumbnailUrl; contentUrl accompanies the ones that carry full-size content.

This event can also be handled with the "A new postcard is ready" Device Trigger, which automatically filters to the matching feeder:

triggers:
  - trigger: device
    domain: birdbuddy
    type: new_postcard
    device_id: <ha device id>

Services

birdbuddy.collect_postcard

Collects a postcard into your Collections, adding its media to the associated species and making them available in the Media Browser. This is the same effect as opening and saving the postcard in the Bird Buddy app.

Note

This service is meant to be used with the birdbuddy_new_postcard event, Device Trigger, or Blueprint, which supply the postcard_id.

Service data	Optional	Description
postcard_id	No	Id of the postcard to collect, from the birdbuddy_new_postcard event.
feeder_id	Yes	Feeder id, used to pick the account when more than one Bird Buddy account is configured.
share	Yes	Whether the collected media is also shared with the Bird Buddy community (default: false).

Bird Buddy now identifies species server-side, so the integration no longer chooses a species client-side (and there is no longer a strategy or best_guess_confidence option): the postcard is collected exactly as the Bird Buddy app would collect it.

Automation example

triggers:
  - trigger: event
    event_type: birdbuddy_new_postcard
  # OR a device trigger:
  - trigger: device
    domain: birdbuddy
    type: new_postcard
    # $ids...
actions:
  - action: birdbuddy.collect_postcard
    data:
      postcard_id: "{{ trigger.event.data.postcard_id }}"
      feeder_id: "{{ trigger.event.data.feeder_id }}"
      share: false

Blueprint

To simplify the combination of the trigger and the action of collecting the postcard, you can import a predefined Blueprint.

To add the Blueprint, use the button below:

or go to Settings > Automations & Scenes > Blueprints, click the Import Blueprint button, and enter this URL:

https://github.com/jhansche/ha-birdbuddy/blob/main/custom_components/birdbuddy/blueprints/collect_postcard.yaml

After the Blueprint has been imported, you still need to create an automation from that Blueprint. Also note that if we update the Blueprint here, your imported Blueprint will not automatically receive the update, and you may need to re-import it to get the update.

Breaking changes

Adopting pybirdbuddy v0.1.0 moves the integration to Bird Buddy's server-side postcardCollect flow. Entities keep their IDs and history, and automations built on the "A new postcard is ready" Device Trigger carry over untouched, since the trigger resolves the event internally. Automations that reference the event or the service directly need updating:

• birdbuddy_new_postcard_sighting — renamed to birdbuddy_new_postcard. The payload carries postcard_id, feeder_id, species, and media in place of the postcard and sighting report objects.
• birdbuddy.collect_postcard — takes postcard_id, plus optional feeder_id and share, in place of the postcard and sighting objects. Bird Buddy identifies species server-side, so the schema now rejects strategy and best_guess_confidence; share_media becomes share.
• The bundled Blueprint — re-import it and re-create any automation built from it, since it now uses the renamed event and the new service inputs.

Re-importing the Blueprint covers everything if you use it without customizing the payload.

Home Assistant raises a Repairs notice while an automation or script still triggers on birdbuddy_new_postcard_sighting. Editing that trigger clears the notice on a following update poll.

Development

make deps    # create venv (Python 3.14.4) + install dev/test tooling
make check   # ruff + ruff format --check + markdownlint + pyright + pytest
make format  # auto-fix ruff issues

The pinned pytest-homeassistant-custom-component selects the exact Home Assistant version tested against (see requirements-dev.txt).

License

Released under the MIT No Attribution License.