Nextcloud Talk Bot

Custom component for Home Assistant to communicate between Home Assistant and Nextcloud Talk.

What can I do with this component?

• Send a message from Home Assistant to a room in Nextcloud Talk to send updates or alerts.
• React to messages sent in this room and do some stuff like open the garage door if somebody is asking.

You can choose if you want to communicate one way or in both ways.

Requirements

• Nextcloud >= 27.1
• Nextcloud Talk >= 17.1

The base endpoint is: /ocs/v2.php/apps/spreed/api/v1 (requires the bots-v1 capability - available since Nextcloud 27.1).

Installation

Preparation

Install this component in Home Assistant:

• Ensure you have Home Assistant Community Store installed

• Search for nctalkbot in HACS under integrations and install it:

  

• Restart Home Assistant

• Choose one of the following methods to continue

Method 1: Send messages only (One-way HA -> NC)

Method 1: Step 1

• Generate a 128-char hex string as a secret (minimum is 40 chars).

Method 1: Step 2

Create a bot in Nextcloud Talk (see nextcloud docs):

• Use occ to create a new bot:

  occ talk:bot:install -f response "<name>" "<shared_secret>" "<webhook_url>" "[<description>]"

  Note: Although we don't need the feature to forward messages from the Nextcloud Talk chat to another system that can process the messages (webhook) to send messages from Home Assistant to Nextcloud Talk only, webhook_url must be provided in a valid format (e.g. http://127.0.0.1 or http://wedontcare.local).

• Get the id of the created bot:

  occ talk:bot:list

• Create a room in Nextcloud Talk (you get the room token within the response):

  occ talk:room:create --user <your_uid> --owner <your_uid> <room_name>

• Assign bot to this room:

  occ talk:bot:setup <bot_id> <room_token>

Method 1: Step 3

• Add this to your configuration.yaml:

  notify:
    - platform: nctalkbot
      name: nctalkbot
      url: !secret nextcloud_url
      shared_secret: !secret nextcloud_talk_shared_secret
      room_default: !secret nextcloud_talk_room_token

  Note: room_default is optional. If you don't set it here, you must provide a target when calling the notify service.

• Add needed secrets in your secrets.yaml. It should look like this:

  # Nextcloud Push
  nextcloud_url: https://cloud.my-domain.local
  nextcloud_talk_shared_secret: your-own-128-char-hex-string
  nextcloud_talk_room_token: room-token

• Restart Home Assistant again.

Method 2: React to messages (Two-way HA <-> NC or One-way NC -> HA)

Method 2: Step 1

• Add this integration (Settings > Devices & Integrations):

  

• You have to provide your URL to your Nextcloud instance (e.g. https://nextcloud.local/) and click on submit.

• The next window shows a Webhook URL and a Shared secret. You will need this info for installing the Nextcloud Talk Bot.

Method 2: Step 2

Create a bot in Nextcloud Talk (see nextcloud docs):

• Use occ to create a new bot:

  occ talk:bot:install "<name>" "<shared_secret>" "<webhook_url>" "[<description>]"

  Note: Fill in the Webhook URL and the Shared secret generated by the config entry.

• Get the id of the created bot:

  occ talk:bot:list

• Create a room in Nextcloud Talk (you get the room token within the response):

  occ talk:room:create --user <your_uid> --owner <your_uid> <room_name>

• Assign bot to this room:

  occ talk:bot:setup <bot_id> <room_token>

Method 2: Step 3 (Optional)

• Add notify platform settings and secrets to your configuration.yaml as explained in Step 3 of Method 1 if you want to send messages too (Two-way HA <> NC).
• Restart Home Assistant again.

Send message

Use service notify.nctalkbot:

service: notify.nctalkbot
data:
  message: Test from Home Assistant

If you want to target another room, you can set the room token like this:

service: notify.nctalkbot
data:
  message: Test from Home Assistant
  target: <room-token>

Note: The bot must be assigned to your target room!

React to message

The webhook will be triggered whenever something happens in the Nextcloud Talk room (e.g. new message, reaction...). After verifying that this is a valid message from an authorized bot the event nctalkbot_webhook_received will be fired.

The content of the fired event looks like this:

event_type: nctalkbot_webhook_received
data:
  type: Create
  actor:
    type: Person
    id: users/kevin.latka
    name: Kevin Latka
  object:
    type: Note
    id: "807"
    name: message
    content: "{\"message\":\"I love this component\",\"parameters\":[]}"
    mediaType: text/markdown
  target:
    type: Collection
    id: f7wt6tng
    name: nctalkbot
  rendered_content: I love this component
  webhook_id: bdb898075abcf8214e5a296d7f3f0d516c69c986638ab92f7baa8e929670f7bb
origin: LOCAL
time_fired: "2023-10-26T16:29:23.417885+00:00"
context:
  id: 01HDPD3C2S6C6BAEVMMRH8N18N
  parent_id: null
  user_id: null

At this point, you can create plenty of automation for this webhook event (see docs):

• If the message is open garage -> open garage in Home Assistant
• Feed assistants with the message to let them handle it
• more