EverShelf/docs/wiki/Home-Assistant.md

Home Assistant Integration

EverShelf integrates natively with Home Assistant to bring your pantry data into your smart-home automations.

Capabilities:

• 📡 REST sensors — expose pantry counts as HA sensor entities (expiring, expired, shopping list, total items)
• 🔔 Webhooks — trigger HA automations on pantry events (expiry alerts, shopping additions, stock updates)
• 📣 Push notifications — send alerts to your phone via any HA notify.* service
• 🔊 TTS on smart speakers — read recipe steps aloud on any HA media_player entity
• ⚙️ In-app config panel — configure everything from Settings → 🏠 tab (no need to edit .env manually)

---

Quick Setup

1. Generate a Long-Lived Access Token in Home Assistant:

   • Open HA → your Profile (bottom-left avatar) → Security → Long-Lived Access Tokens → Create Token
   • Copy the generated token — you won't see it again.

2. Open EverShelf Settings → tab 🏠 Home Assistant.

3. Fill in Home Assistant URL (e.g. http://homeassistant.local:8123) and paste the token.

4. Click Test connection — you should see ✅.

5. Enable the features you want (TTS, Webhooks, REST Sensors) and click Save HA settings.

---

REST Sensors

Add EverShelf pantry data as native HA sensor entities that update automatically.

Endpoints

URL	Returns	Sensor
/api/?action=ha_sensor	Items expiring soon (≤3 days)	sensor.evershelf_overview
/api/?action=ha_sensor&sensor=expired	Expired items count	sensor.evershelf_expired
/api/?action=ha_sensor&sensor=shopping	Shopping list item count	sensor.evershelf_shopping
/api/?action=ha_sensor&sensor=total	Total pantry items	sensor.evershelf_total

Generate & Copy YAML

In Settings → 🏠 Home Assistant → REST Sensors card, click Copy YAML to get a ready-to-paste configuration.yaml block that already contains your EverShelf URL.

Manual YAML example

# configuration.yaml
sensor:
  - platform: rest
    name: "EverShelf Overview"
    unique_id: evershelf_overview
    resource: "http://YOUR_EVERSHELF_URL/api/?action=ha_sensor"
    scan_interval: 300        # seconds
    value_template: "{{ value_json.state }}"
    json_attributes:
      - expiring_soon
      - expiring_3d
      - expired_items
      - total_items
      - shopping_items
      - expiring_list
      - last_updated
    unit_of_measurement: "items"

  - platform: rest
    name: "EverShelf Shopping Count"
    unique_id: evershelf_shopping
    resource: "http://YOUR_EVERSHELF_URL/api/?action=ha_sensor&sensor=shopping"
    scan_interval: 180
    value_template: "{{ value_json.state }}"
    unit_of_measurement: "items"

Restart Home Assistant after editing configuration.yaml.

---

Webhook Automations

EverShelf fires an HTTP POST to your HA webhook URL when pantry events occur.

Create the HA Webhook Automation

1. HA → Settings → Automations & Scenes → Create Automation
2. Click Add Trigger → choose Webhook
3. HA generates a Webhook ID — copy it
4. Paste the ID into Settings → 🏠 Home Assistant → Webhook ID
5. Select which events should trigger the webhook

Supported Events

Event key	When it fires
expiry	Daily cron — items expiring within HA_EXPIRY_DAYS days
shopping_add	Item added to the shopping list
stock_update	Inventory quantity changed
barcode_scan	(reserved for future use)

Webhook Payload (POST body)

{
  "event": "expiry_alert",
  "timestamp": "2025-06-12T08:00:00+00:00",
  "data": {
    "type": "expiring_soon",
    "count": 3,
    "days": 3,
    "summary": "3 products expiring within 3 days",
    "items": [
      { "name": "Milk", "expiry_date": "2025-06-14", "quantity": 1, "unit": "l" }
    ]
  }
}

Example: Expiry Alert → Telegram

alias: EverShelf Expiry Alert
trigger:
  - platform: webhook
    webhook_id: "evershelf_webhook_abc123"   # ← your Webhook ID
action:
  - service: notify.telegram_bot
    data:
      message: >
        🥫 EverShelf: {{ trigger.json.data.summary }}
        {% for item in trigger.json.data.items %}
        — {{ item.name }} (expires {{ item.expiry_date }})
        {% endfor %}

---

Push Notifications

If you prefer to receive push alerts without using webhooks, configure a HA notify service directly:

1. Find your notify service name in HA: Developer Tools → Services → search notify
2. Paste it into Settings → 🏠 → Notify service (e.g. notify.mobile_app_my_phone)
3. Save

EverShelf will call this service from the cron job whenever expiry alerts fire.

---

TTS on Smart Speakers

Read recipe steps aloud on an Amazon Echo, Google Home, Sonos, or any HA media_player.

Configuration

1. Enter the Entity ID of your media player (e.g. media_player.kitchen_display)
   • Find it in HA: Developer Tools → States
2. Click Apply HA preset to TTS tab — this auto-fills the TTS tab with the correct HA endpoint and auth headers
3. Save settings

How it Works

When recipe step TTS is triggered, EverShelf calls:

POST /api/services/tts/speak
Authorization: Bearer <HA_TOKEN>
{
  "entity_id": "media_player.kitchen_display",
  "message": "Add 200 g of flour and mix well."
}

The request is proxied through the EverShelf PHP backend (avoids CORS / mixed-content issues).

---

Environment Variables Reference

All settings are configurable from .env or from the in-app Settings panel.

Variable	Default	Description
HA_ENABLED	false	Master switch for all HA features
HA_URL	(empty)	Base URL of HA instance, no trailing slash
HA_TOKEN	(empty)	Long-Lived Access Token
HA_TTS_ENTITY	(empty)	media_player entity for TTS
HA_WEBHOOK_ID	(empty)	Webhook trigger ID from HA automation
HA_WEBHOOK_EVENTS	expiry,shopping_add,stock_update	Comma-separated list of events
HA_NOTIFY_SERVICE	(empty)	HA notify service (e.g. notify.mobile_app_phone)
HA_EXPIRY_DAYS	3	Days before expiry to trigger the daily alert

---

Troubleshooting

Test shows ❌ "Connection failed"

• Verify the URL is reachable from the EverShelf server (not just your browser)
• If using HTTPS with a self-signed certificate, the server-side cURL request may fail — use HTTP on the local network instead
• Check that port 8123 (or your custom port) is open on the HA host

Test shows ❌ "bad_token"

• The Long-Lived Access Token may have expired or been revoked — generate a new one in HA Profile

Webhook not firing

• Confirm HA_ENABLED=true and the Webhook ID is exactly as shown in HA
• Check the EverShelf cron is running (/api/cron_smart_shopping.php every 5 minutes)
• For shopping/stock events: verify the event name is in HA_WEBHOOK_EVENTS

TTS not speaking

• Ensure the media player entity is online in HA (check its state in Developer Tools)
• Try the "Apply HA preset to TTS tab" button and send a test from the TTS tab
• Check HA logs for tts.speak errors (some platforms require tts_options)

Sensors show unavailable in HA

• The EverShelf URL must be reachable from the HA host
• If running EverShelf behind a reverse proxy, ensure /api/ is accessible
• Use scan_interval ≥ 60 to avoid hammering the server