Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/klatka/nc-talk-bot-component
Custom component for Home Assistant to communicate between Home Assistant and Nextcloud Talk
https://github.com/klatka/nc-talk-bot-component
hacs hacs-integration home-assistant homeassistant-custom-component nextcloud nextcloud-talk nextcloud-talk-bot nextcloud-talk-chat-bot notify
Last synced: 3 months ago
JSON representation
Custom component for Home Assistant to communicate between Home Assistant and Nextcloud Talk
- Host: GitHub
- URL: https://github.com/klatka/nc-talk-bot-component
- Owner: klatka
- License: apache-2.0
- Created: 2023-09-16T22:57:39.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-06T15:56:07.000Z (9 months ago)
- Last Synced: 2024-05-06T17:16:10.470Z (9 months ago)
- Topics: hacs, hacs-integration, home-assistant, homeassistant-custom-component, nextcloud, nextcloud-talk, nextcloud-talk-bot, nextcloud-talk-chat-bot, notify
- Language: Python
- Homepage:
- Size: 48.8 KB
- Stars: 9
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Nextcloud Talk Bot
[](https://hacs.xyz/docs/user/)
[](https://codecov.io/github/klatka/nc-talk-bot-component)
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](https://hacs.xyz/) installed
- Search for **nctalkbot** in HACS under integrations and install it:
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=klatka&repository=nc-talk-bot-component&category=integration)
- 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](https://nextcloud-talk.readthedocs.io/en/latest/bots/)):
- Use [occ](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/occ_command.html) to create a new bot:
```bash
occ talk:bot:install -f response "" "" "" "[]"
```
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:
```bash
occ talk:bot:list
```
- Create a room in Nextcloud Talk (you get the room token within the response):
```bash
occ talk:room:create --user --owner
```
- Assign bot to this room:
```bash
occ talk:bot:setup
```
#### Method 1: Step 3
- Add this to your `configuration.yaml`:
```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:
```yaml
# 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](https://my.home-assistant.io/redirect/integrations)):
[](https://my.home-assistant.io/redirect/config_flow_start/?domain=nctalkbot)
- 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](https://nextcloud-talk.readthedocs.io/en/latest/bots/)):
- Use [occ](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/occ_command.html) to create a new bot:
```bash
occ talk:bot:install "" "" "" "[]"
```
Note: Fill in the `Webhook URL` and the `Shared secret` generated by the config entry.
- Get the id of the created bot:
```bash
occ talk:bot:list
```
- Create a room in Nextcloud Talk (you get the room token within the response):
```bash
occ talk:room:create --user --owner
```
- Assign bot to this room:
```bash
occ talk:bot:setup
```
#### 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`:
```yaml
service: notify.nctalkbot
data:
message: Test from Home Assistant
```
If you want to target another room, you can set the room token like this:
```yaml
service: notify.nctalkbot
data:
message: Test from Home Assistant
target:
```
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:
```plain
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](https://www.home-assistant.io/docs/automation/trigger/#event-trigger)):
- If the message is `open garage` -> open garage in Home Assistant
- Feed assistants with the message to let them handle it
- more
