Mastering Local Interactions: Google Assistant Relay with Home Assistant for Advanced Voice Automations

Unlocking Advanced Voice Control with Google Assistant Relay and Home Assistant

In the quest for a truly intelligent and private smart home, leveraging existing voice assistants locally often presents a challenge. While Home Assistant offers robust integrations with cloud-based Google Assistant services (often via Nabu Casa), these rely on external servers and may lack the granular control many enthusiasts crave. Enter Google Assistant Relay (GAR) – a powerful self-hosted solution that enables Home Assistant to send commands and dynamic voice broadcasts directly to your Google Home and Nest devices, bypassing much of the cloud overhead for specific interactions.

This guide will walk you through setting up Google Assistant Relay, integrating it with Home Assistant, and crafting advanced automations for dynamic announcements, contextual feedback, and even indirect device control, all while enhancing your smart home's privacy and responsiveness.

Why Google Assistant Relay?

• Local Control: Send commands directly to your Google devices within your local network.
• Dynamic Broadcasts: Play custom, templated messages on individual or all speakers.
• Enhanced Privacy: Reduce reliance on cloud processing for routine voice outputs.
• Rich Interactions: Go beyond basic TTS by leveraging Google Assistant's native broadcast capabilities and even triggering routines.
• Cost-Effective: Avoid recurring subscription fees for advanced voice features (though a Google Cloud project is still involved for authentication).

Prerequisites

Before diving in, ensure you have:

• A running Home Assistant instance (Supervisor recommended for ease of Docker management).
• Access to a machine capable of running Docker (or Python directly) for the Google Assistant Relay server. This can be your Home Assistant host if it supports Docker.
• Google Home/Nest speakers connected to your network.
• A Google Account.

Step-by-Step Setup: Google Assistant Relay

Part 1: Google Cloud Project Configuration

Google Assistant Relay requires authentication with the Google Assistant API. This involves setting up a project in the Google Cloud Console.

1. Create a New Project: Go to the Google Cloud Console. From the project selector, click NEW PROJECT. Give it a descriptive name like Home Assistant Google Relay and create it.
2. Enable Google Assistant API: Once your project is created, navigate to APIs & Services > Library. Search for Google Assistant API and enable it.
3. Configure OAuth Consent Screen: Go to APIs & Services > OAuth consent screen.
• Choose External and click CREATE.
• Fill in the required app information (App name, User support email, Developer contact email). You can add your own email as a test user under Test users.
• Save and continue through scopes and test users.
4. Create OAuth 2.0 Client IDs: Go to APIs & Services > Credentials.
• Click + CREATE CREDENTIALS and select OAuth client ID.
• For Application type, choose Desktop app. Give it a name like Google Assistant Relay Client and click CREATE.
• A dialog will appear with your client ID and client secret. Click the download icon (DOWNLOAD JSON) to save your client_secret.json file. Keep this file secure; it contains sensitive credentials.

Part 2: Install and Configure Google Assistant Relay

We recommend using Docker for easy deployment and management.

Create a directory for GAR, e.g., /opt/google-assistant-relay. Place your downloaded client_secret.json file in this directory.

Next, create a docker-compose.yml file in the same directory:

version: '3.8'
services:
  google-assistant-relay:
    container_name: google-assistant-relay
    image: ghcr.io/greghesp/google-assistant-relay:latest
    restart: unless-stopped
    network_mode: host # This is important for discovery and device targeting
    volumes:
      - ./config:/config
      - ./client_secret.json:/config/client_secret.json:ro
    environment:
      - TZ=Your/Timezone # e.g., America/New_York
      - NGROK_AUTH_TOKEN=YOUR_NGROK_AUTH_TOKEN # Only if you need external access, otherwise omit.
      - PORT=5000

Note on network_mode: host: This allows GAR to see your Google Home devices on the local network directly, which is crucial for its functionality. Ensure port 5000 is not in use by another service on the host.

Start the relay:

cd /opt/google-assistant-relay
docker-compose up -d

The first time it runs, GAR will require authentication. Check the container logs:

docker logs -f google-assistant-relay

You'll see a URL in the logs. Copy this URL, paste it into a web browser, and log in with your Google account that manages your Google Home devices. Grant the necessary permissions. After successful authentication, you'll see a success message, and the Relay will be ready.

Part 3: Home Assistant Integration

Home Assistant communicates with Google Assistant Relay via REST commands. Add the following to your configuration.yaml:

# configuration.yaml
rest_command:
  google_assistant_broadcast:
    url: http://<GAR_IP_ADDRESS>:5000/broadcast?message={{ message }}
    method: POST

  google_assistant_command:
    url: http://<GAR_IP_ADDRESS>:5000/command?message={{ message }}
    method: POST

  google_assistant_device_broadcast:
    url: http://<GAR_IP_ADDRESS>:5000/broadcast?message={{ message }}&speaker={{ speaker }}
    method: POST

  google_assistant_device_command:
    url: http://<GAR_IP_ADDRESS>:5000/command?message={{ message }}&speaker={{ speaker }}
    method: POST

Replace <GAR_IP_ADDRESS> with the IP address of the machine running your Google Assistant Relay Docker container.

Restart Home Assistant to load the new REST commands.

Device Integration Tips

• Targeting Specific Speakers: Use the google_assistant_device_broadcast or google_assistant_device_command services and specify the speaker parameter. The speaker name should match exactly how it appears in your Google Home app (e.g., Living Room Speaker, Kitchen Display).
• Dynamic Message Content: Leverage Home Assistant's powerful templating engine to generate context-rich messages.
• Volume Control: Google Assistant Relay doesn't directly control speaker volume, but you can use Home Assistant's built-in media player entities for your Google Home devices to adjust volume before/after broadcasts.

Advanced Configuration Examples & Real-World Use Cases

1. Dynamic Morning Briefing

Get a personalized morning update on your bedroom speaker.

# automations.yaml
- alias: 'Morning Briefing on Bedroom Speaker'
  trigger:
    platform: time
    at: '06:30:00'
  condition:
    condition: state
    entity_id: binary_sensor.sleep_mode
    state: 'off'
  action:
    - service: media_player.volume_set
      data:
        entity_id: media_player.bedroom_speaker
        volume_level: 0.4
    - service: rest_command.google_assistant_device_broadcast
      data_template:
        speaker: 'Bedroom Speaker'
        message: >
          Good morning! The time is {{ now().strftime('%H:%M') }}. 
          The outside temperature is {{ states('sensor.outside_temperature') }} degrees Celsius. 
          Today's forecast: {{ state_attr('weather.home', 'forecast')[0].detailed_description }}.
          Your first calendar event is at {{ state_attr('calendar.my_google_calendar', 'start_time') }} today: 
          {{ state_attr('calendar.my_google_calendar', 'message') | default('No events') }}.
    - delay: '00:00:10' # Give time for broadcast
    - service: media_player.volume_set
      data:
        entity_id: media_player.bedroom_speaker
        volume_level: 0.2 # Return to lower volume

2. Security Alerts for Doors/Windows

Announce when a door or window is left open for too long.

# automations.yaml
- alias: 'Front Door Left Open Alert'
  trigger:
    platform: state
    entity_id: binary_sensor.front_door_contact
    to: 'on'
    for:
      minutes: 5
  action:
    - service: rest_command.google_assistant_broadcast
      data:
        message: 'Alert! The front door has been left open for five minutes.'
    - service: persistent_notification.create
      data:
        title: 'Security Alert'
        message: 'Front door open for too long!'

3. Contextual Feedback for Device Actions

Confirm actions or provide updates on device status.

# automations.yaml
- alias: 'Washing Machine Done Notification'
  trigger:
    platform: state
    entity_id: binary_sensor.washing_machine_power_sensor
    to: 'off'
    for:
      minutes: 2
  condition:
    condition: numeric_state
    entity_id: sensor.washing_machine_power
    below: 5 # Low power consumption indicates finished cycle
  action:
    - service: rest_command.google_assistant_device_broadcast
      data:
        speaker: 'Kitchen Speaker'
        message: 'The washing machine cycle is finished. Time to unload!'

4. Triggering Google Assistant Routines (Indirectly)

You can 'command' your Google Assistant to trigger routines you've already set up.

# script.yaml
wake_up_routine_google_home:
  sequence:
    - service: rest_command.google_assistant_command
      data:
        message: 'Good morning'

Calling script.wake_up_routine_google_home will make your Google Home device execute its 'Good morning' routine.

Troubleshooting Advice

• Authentication Issues: If messages aren't broadcasting, check your docker logs google-assistant-relay for authentication errors. You might need to re-authenticate by deleting the /config/oauth.json file (inside the Docker volume) and restarting the container.
• Network Connectivity: Ensure Home Assistant can reach the GAR IP and port (5000). Check firewalls. Verify network_mode: host is correctly configured if using Docker.
• Speaker Names: Double-check that the speaker parameter in your Home Assistant service calls exactly matches the name of your Google Home device in the Google Home app. Case sensitivity matters!
• Logs, Logs, Logs: Both Home Assistant logs and Google Assistant Relay Docker logs are your best friends for debugging.
• Google Rate Limits: While less common for simple broadcasts, excessive rapid commands might hit Google's API rate limits. Introduce small delays between multiple commands if you encounter issues.

Best Practices for Scalability, Reliability, and Security

• Security:
  • Keep your client_secret.json file strictly confidential and only accessible by the GAR container.
  • If exposing GAR outside your local network (e.g., via Ngrok as shown in some guides), ensure strong authentication and consider VPN access instead. For most use cases, GAR should remain local.
  • Limit network access to the GAR server (port 5000) to only your Home Assistant instance's IP if possible using firewall rules.
• Reliability:
  • Use Docker with a restart: unless-stopped policy to ensure GAR automatically restarts if the host reboots or the container crashes.
  • Monitor the Docker container's health using tools like Portainer or simple scripts.
  • Regularly check Google Cloud Console for any API quota issues (unlikely for typical home use but good to know).
• Scalability:
  • For most home setups, a single GAR instance is sufficient.
  • Leverage Home Assistant's templating capabilities to generalize commands and broadcasts, making it easier to manage many automations.
• Backup: Periodically back up your /config directory for the Google Assistant Relay container (which contains oauth.json and other configuration). This saves you from re-authenticating after a catastrophic failure.

Conclusion

Integrating Google Assistant Relay with Home Assistant unlocks a new dimension of voice automation, moving beyond simple TTS to a more interactive and locally controlled smart home experience. By following this guide, you can create dynamic broadcasts, provide contextual feedback, and even trigger Google Assistant routines with precision, enhancing both the intelligence and privacy of your Home Assistant ecosystem. Experiment with the powerful templating engine and discover countless ways to make your smart home truly speak to you.