home-assistant.io/source/_components/hangouts.markdown

layout, title, description, date, sidebar, comments, sharing, footer, logo, ha_category, ha_release, redirect_from

layout	title	description	date	sidebar	comments	sharing	footer	logo	ha_category	ha_release	redirect_from
page	Google Hangouts	Hangouts chatbot support	2018-08-18 20:00	true	false	true	true	hangouts.png	Hub Notifications	0.77	/components/notify.hangouts/

This component allows you to send messages to Google Hangouts conversations, as well as to react to messages in conversations. Reacting to commands is accomplished by firing an event when one of the configured commands is triggered. Home Assistant will impersonate a Smartisan YQ603 phone which will then show up in your Google devices.

There is currently support for the following device types within Home Assistant:

• Notifications

{% linkable_title Setup the component via the frontend %}

Menu: Configuration -> Integrations

Configure the integration:

• Enter your Google Mail Address and Password
• If you secured your account with 2-factor authentication you will be asked for a 2-factor authentication token.

You can't write messages to yourself or get notifications in a group, if "you" write the message. The best way is to create a new Google Hangouts account for this integration.

If you secured your account with 2-factor authentication: Only verification by app or SMS are supported. There is no support for verification by prompt on your phone.

If you are sure your email and password are correct, but the component says the login is invalid, wait a few hours and try again. It might be that Google asks for a captcha which we can't support. Google does not provide official support for using bots with Google Hangouts, that's why we have to work around this.

The authentication token will be generated and stored internally.

# Example configuration.yaml entry
hangouts:
  intents:
    HangoutsHelp:
      sentences:
        - Help
    LivingRoomTemperature:
      sentences:
        - What is the temperature in the living room
      conversations:
        - id: CONVERSATION_ID1
        - id: CONVERSATION_ID2
  default_conversations:
    - id: CONVERSATION_ID1
  error_suppressed_conversations:
    - id: CONVERSATION_ID2

{% configuration %} intents: description: "Intents that the hangouts component should understand." required: false type: map default: empty keys: '<INTENT NAME>': description: "Single intent entry." required: true type: map keys: sentences: description: "Sentences that should trigger this intent." required: true type: list conversations: description: "A list of conversations that triggers this intent. If no conversation are given, every conversations triggers the intent." required: false type: [map] default: empty keys: id: description: "Specifies the id of the conversation. The conversation id can be obtained from the hangouts.conversations entity." required: true type: string default_conversations: description: "A list of conversations that are used for intents if no conversations entry for an intent is given." required: false type: [map] default: empty keys: id: description: "Specifies the id of the conversation. The conversation id can be obtained from the hangouts.conversations entity." required: true type: string error_suppressed_conversations: description: "A list of conversations that won't get a message if the intent is not known." required: false type: [map] default: empty keys: id: description: "Specifies the id of the conversation. The conversation id can be obtained from the hangouts.conversations entity." required: true type: string {% endconfiguration %}

The conversations has to be precreated, the conversation id can be obtained from the hangouts.conversations entity. Make sure to use quotes around the conversation id or alias to escape special characters (!, and #) in YAML.

The intent HangoutsHelp is part of the component and return a list of all sentences the component unterstand in this conversation.

{% linkable_title Adding sentences %}

{% raw %}

# The Hangouts component
hangouts:
  intents:
    HassLightSet:
      sentences:
        - Toggle {name}.
      conversations:
        - id: CONVERSATION_ID1
    Ping:
      sentences:
        - How many Conversation do you know
  error_suppressed_conversations:
    - id: CONVERSATION_ID2

intent_script:
  Ping:
    speech:
      text: I know {{ states.hangouts.conversations.state }} conversations

{% endraw %}

This configuration will:

• Toggle the light in the given location in a specific conversation.
• Return the conversations the bot know.

{% linkable_title Adding advanced custom sentences %}

Sentences can contain slots (marked with curly braces: {name}) and optional words (marked with square brackets: [the]). The values of slots will be passed on to the intent and are available inside the templates.

The following configuration can handle the following sentences:

• Change the lights to red
• Change the lights to green
• Change the lights to blue
• Change the lights to the color red
• Change the lights to the color green
• Change the lights to the color blue

{% raw %}

# Example configuration.yaml entry
hangouts:
  intents:
    ColorLight:
      sentences:
        - Change the lights to [the color] {color}

intent_script:
  ColorLight:
    speech:
      text: Changed the lights to {{ color }}.
    action:
      service: light.turn_on
      data_template:
        rgb_color:
          - "{% if color == 'red' %}255{% else %}0{% endif %}"
          - "{% if color == 'green' %}255{% else %}0{% endif %}"
          - "{% if color == 'blue' %}255{% else %}0{% endif %}"

{% endraw %}

{% linkable_title Services %}

{% linkable_title Service hangouts.update %}

Updates the list of conversations.

Service data attribute	Optional	Description

{% linkable_title Service hangouts.send_message %}

Sends a message to the given conversations.

Service data attribute	Optional	Description
target	List of targets with id or name. [Required]	[{"id": "UgxrXzVrARmjx_C6AZx4AaABAagBo-6UCw"}, {"name": "Test Conversation"}]
message	List of message segments, only the "text" field is required in every segment. [Required]	[{"text":"test", "is_bold": false, "is_italic": false, "is_strikethrough": false, "is_underline": false, "parse_str": false, "link_target": "http://google.com"}, ...]
data	Extra options	{"image_file": "path"} / {"image_url": "url"}

{% linkable_title Service hangouts.reconnect %}

Reconnects the hangouts bot.

Service data attribute	Optional	Description

{% linkable_title Advanced %}

{% linkable_title Automatic reconnect after ip change %}

The hangouts component can't detect if your ip address changes, so it can't automatic reconnect to the Google servers. This is a workaround for this problem.

{% raw %}

sensor:
  - platform: rest
    resource: https://api.ipify.org?format=json
    name: External IP
    value_template: '{{ value_json.ip }}'
    scan_interval: 10

automation:
  - alias: Reconnect Hangouts
    trigger:
      - entity_id: sensor.external_ip
        platform: state
    condition:
      - condition: template
        value_template: '{{ trigger.from_state.state != trigger.to_state.state }}'
      - condition: template
        value_template: '{{ not is_state("sensor.external_ip", "unavailable") }}'
    action:
      - service: hangouts.reconnect

{% endraw %}

{% linkable_title Notifications %}

The hangouts platform allows you to deliver notifications from Home Assistant to Google Hangouts conversations. Conversations can be both direct as well as group chats.

To enable Hangouts notifications in your installation, you first need to configure the Hangouts component. Then, add the following to your configuration.yaml file:

# Example configuration.yaml entry  
notify:
  - name: NOTIFIER_NAME
    platform: hangouts
    default_conversations:
      - id: CONVERSATION_ID1
      - id: CONVERSATION_ID2

{% configuration %} name: description: "Setting the optional parameter name allows multiple notifiers to be created. The default value is notify. The notifier will bind to the service notify.NOTIFIER_NAME." required: false type: string default_conversations: description: "The conversations all messages will be sent to, when no other target is given." required: true type: [map] keys: id: description: "Specifies the id of the conversation. The conversation id can be obtained from the hangouts.conversations entity." required: true type: string {% endconfiguration %}

{% linkable_title Finding the conversation ID %}

The conversations has to be precreated, the conversation id can be obtained from the hangouts.conversations entity, this can be found in with the states developer tool that is shown as this icon in the side bar. Using your web browsers search tool to find the hangouts.conversations entity. You will find something like below.

0: {
  "id": "<Hangout ID>",
  "name": "A simple hangout",
  "users": [
    "Steve",
    "Jo"
  ]
}

This may have more if the account is in multiple hangout conversations, for configuring the bot to be in a conversation you will need the ID that would be where <Hangout ID> is in that example. Make sure to use quotes around the conversation id or alias to escape special characters (!, and #) in YAML.

To use notifications, please see the getting started with automation page.