Envoy Web

Home Assistant custom integration for controlling Enphase IQ Battery profile and backup reserve percentage via the Enphase Enlighten cloud API.

Overview

This integration allows you to monitor and control your Enphase battery system directly from Home Assistant:

• View the current battery profile and backup reserve percentage
• Change the battery profile between Self-Consumption and Backup modes
• Adjust the backup reserve percentage (0-100%)
• Automate battery settings based on weather, time-of-use rates, or grid conditions
• Handles sessions automatically, renewing access when needed and prompting you to re-authenticate if credentials change

Notices

• This integration uses the same private Enlighten web API that powers the official app and dashboard, and requires your Enlighten account credentials.
• The API is not publicly documented; endpoints, payloads, or authentication flows can change without warning and break the integration.
• Automated access may be detected as non-human activity, which can trigger rate limiting, access restrictions, or account suspension.
• There is no guarantee of long-term compatibility or support from Enphase/Enlighten.
• The integration is not affiliated with Enphase Energy, Inc.

Installation

HACS (recommended)

1. Open HACS in Home Assistant
2. Go to Integrations -> click the ... menu -> Custom repositories
3. Add https://github.com/ccitro/envoy-web with category Integration
4. Click Install on the Envoy Web card
5. Restart Home Assistant

Manual installation

1. Download the latest release
2. Extract and copy custom_components/envoy_web/ to your config/custom_components/ directory
3. Restart Home Assistant

Configuration

Add the integration

1. Go to Settings -> Devices & Services
2. Click + Add Integration
3. Search for Envoy Web
4. Enter your configuration:

Field	Description
Battery ID	Your battery system ID (see Finding your IDs)
User ID	Your Enlighten user ID (see Finding your IDs)
Email	Your Enphase Enlighten account email
Password	Your Enphase Enlighten account password

If your password changes, re-authenticate from Settings -> Devices & Services -> Envoy Web -> Reconfigure.

Finding your IDs

1. Log in to Enphase Enlighten
2. Navigate to your system and open the battery settings page
3. Open your browser's Developer Tools (F12) -> Network tab
4. Look for API calls to batteryConfig - the URL contains both IDs:

   /service/batteryConfig/api/v1/profile/{BATTERY_ID}?userId={USER_ID}
   

Options

After setup, you can configure additional options:

Option	Default	Description
Scan interval	3600 seconds (1 hour)	How often to poll the API (10-3600 seconds)

Entities

This integration creates the following entities. Entity IDs include your battery ID (e.g., 123456).

Battery Profile (select)

Attribute	Value
Entity ID	select.envoy_web_BATTERY_ID_battery_profile
Options	self-consumption, backup_only

Profile descriptions:

• self-consumption: Battery prioritizes powering your home and storing excess solar. Grid is used as backup.
• backup_only: Battery reserves capacity for power outages. Does not discharge during normal operation.

Battery Backup Percentage (number)

Attribute	Value
Entity ID	number.envoy_web_BATTERY_ID_battery_backup_percentage
Range	0-100%
Step	1%

This controls the minimum battery charge level to maintain as backup reserve.

Services

envoy_web.set_profile

Set both the battery profile and backup percentage in a single API call.

service: envoy_web.set_profile
data:
  profile: self-consumption
  battery_backup_percentage: 20

Field	Required	Description
profile	Yes	self-consumption or backup_only
battery_backup_percentage	Yes	Integer from 0 to 100
entry_id	No	Target a specific config entry (for multiple battery systems)

You can also control entities directly using select.select_option and number.set_value.

Automation example

Maximize battery reserve when severe weather is expected:

automation:
  - alias: "Storm Prep - Maximize Battery Reserve"
    trigger:
      - platform: state
        entity_id: binary_sensor.severe_weather_warning
        to: "on"
    action:
      - service: envoy_web.set_profile
        data:
          profile: backup_only
          battery_backup_percentage: 100

Troubleshooting

Authentication errors

• Verify your Enlighten email and password are correct
• Check that you can log in to enlighten.enphaseenergy.com
• Ensure your account has access to the battery system
• Re-authenticate from Settings -> Devices & Services -> Envoy Web -> Reconfigure

Entities unavailable

• Check Home Assistant logs for error messages
• Verify your Battery ID and User ID are correct
• The Enlighten API may be temporarily unavailable

Rate limiting

The integration polls every hour by default. If API rate limits or timeouts occur, increase the scan interval in the integration options.

Development and testing

For contributor setup, linting, and testing details, see:

• CONTRIBUTING.md
• tests/README.md

Local CLI testing

A CLI tool is included for testing the API without Home Assistant. It uses uv for zero-setup dependency management:

# Create credentials file
cat > scripts/.env << 'ENV_EOF'
ENVOY_BATTERY_ID=123456
ENVOY_USER_ID=789012
ENVOY_EMAIL=you@example.com
ENVOY_PASSWORD=yourpassword
ENV_EOF

# Run commands (uv handles dependencies automatically)
uv run scripts/envoy_cli.py login
uv run scripts/envoy_cli.py get
uv run scripts/envoy_cli.py put self-consumption 30

Or make it executable and run directly:

chmod +x scripts/envoy_cli.py
./scripts/envoy_cli.py get

Contributing

Contributions are welcome. Please review CONTRIBUTING.md before opening a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Attribution

This repo was created with the assistance of GPT 5.2 Codex to both fill my personal need for the component and to test the capabilities of the LLM.