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 and so on.
• 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: webhook_url must be a valid URL. Even if you explicitly leave out the webhook feature like above. If you enable the webhook feature, all your messages will be sent to this URL.

• 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

Every time something happens in the Nextcloud Talk room, the webhook will be triggered. 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