kyle
5b521afec1
Channel list working, url generation, just need posting working now - Update dependency to Nextcloud 33 and add `spreed` dependency - Change webhook route from `/webhook` to `/bot-webhook` - Add `NavigationProvider` to add app to admin settings menu - Refactor `TalkService` to query Talk DB directly for room listing (public channels) - Update `postToRoom` to use Talk Chat API with Basic Auth for `talk-bot` user - Add debug helper methods to `TalkService` for room debugging - Enhance `debug` endpoint with detailed system and Talk configuration info - Update admin settings UI with "Default Sender Name" field and improved room selection - Add localization strings to admin settings - Update documentation (`INSTALL.md`, `README.md`) for new route and bot admin requirement - Improve `getBaseUrl` logic to prioritize `trusted_domains` for Docker compatibility
127 lines
4.5 KiB
Markdown
127 lines
4.5 KiB
Markdown
# NCdiscordhook — Installation Guide
|
|
|
|
## Prerequisites
|
|
|
|
- Nextcloud 28+ with the **Talk** app enabled
|
|
- PHP 8.1+
|
|
- Access to the Nextcloud server (SSH or direct file access)
|
|
|
|
## Step 1: Enable the `talk-bot` user
|
|
|
|
The app posts messages as a dedicated bot user using the Talk Chat API (Basic auth). You must create this user and generate an app password.
|
|
|
|
### Create the bot user (via `occ`):
|
|
|
|
```bash
|
|
cd /path/to/nextcloud
|
|
php occ user:add --password-from-env talk-bot
|
|
# You'll be prompted to set a password interactively, or:
|
|
export OC_PASS="your-bot-password-here"
|
|
php occ user:add --password-from-env talk-bot
|
|
```
|
|
|
|
### Make the bot user an admin
|
|
|
|
The bot must have admin privileges to list all Talk rooms. Grant admin access:
|
|
|
|
1. Go to **Settings → Users**
|
|
2. Find **talk-bot** and click it
|
|
3. Check **Admin** under "Settings"
|
|
4. Save
|
|
|
|
### Generate an app password for the bot:
|
|
|
|
1. Log in to Nextcloud as **admin**
|
|
2. Go to **Settings → talk-bot → Devices & sessions**
|
|
3. Click **Add device** and give it a name (e.g., "NCdiscordhook")
|
|
4. Copy the generated device password — you'll need this in Step 3
|
|
|
|
## Step 2: Install the app
|
|
|
|
### Option A: From the web UI (recommended)
|
|
|
|
1. ZIP only the `ncdiscordhook` directory (not the parent folder):
|
|
|
|
```bash
|
|
cd /path/to/ncdiscordhook
|
|
zip -r ../ncdiscdhook.zip .
|
|
```
|
|
|
|
2. Upload via web UI:
|
|
- Go to **Apps → Apps management** (or **Administration → Apps**)
|
|
- Click **Upload app** (or **Download and enable** → upload the ZIP)
|
|
- Select `ncdiscdhook.zip`
|
|
- The app will install and enable automatically
|
|
|
|
### Option B: From the command line
|
|
|
|
```bash
|
|
cd /path/to/nextcloud/apps
|
|
git clone https://github.com/Mr-Newlove/nc_bot_webhooks.git
|
|
# or copy the directory manually:
|
|
# cp -r /path/to/ncdiscordhook /path/to/nextcloud/apps/ncdiscordhook
|
|
```
|
|
|
|
Enable the app:
|
|
|
|
```bash
|
|
cd /path/to/nextcloud
|
|
php occ app:enable ncdiscordhook
|
|
```
|
|
|
|
## Step 3: Configure the app
|
|
|
|
1. Log in to Nextcloud as **admin**
|
|
2. Go to **Settings → Admin → NCdiscordhook**
|
|
3. **Bot App Password** — Paste the device password you generated in Step 1
|
|
4. **Default Sender Name** — Set the name that appears as the message sender (default: "Webhook Bot")
|
|
5. **Image Retention** — Set how many days to keep uploaded images (default: 90)
|
|
6. **Room Selection** — Click **Fetch Rooms** to list available Talk rooms
|
|
7. Check the rooms you want to accept webhooks for
|
|
8. For each room, click **+ Generate Auth Token** to create a webhook URL
|
|
9. Click **Save Configuration**
|
|
|
|
## Step 4: Set up the Discord webhook
|
|
|
|
1. In your Discord channel, go to **Channel Settings → Integrations → Webhooks**
|
|
2. Create a new webhook (or edit an existing one)
|
|
3. Set the Webhook URL to:
|
|
|
|
```
|
|
https://your-nextcloud-server/apps/ncdiscordhook/bot-webhook/<room-token>/<auth-token>
|
|
```
|
|
|
|
Replace `<room-token>` and `<auth-token>` with the values shown in the Nextcloud admin settings for the selected room.
|
|
|
|
4. Save the webhook in Discord
|
|
|
|
## Step 5: Verify
|
|
|
|
Send a test message through the Discord webhook. You should see it appear in the corresponding Nextcloud Talk room with the configured sender name.
|
|
|
|
Test with curl:
|
|
|
|
```bash
|
|
curl -X POST \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"content":"Test message from NCdiscordhook","username":"CI Bot"}' \
|
|
https://your-nextcloud-server/apps/ncdiscordhook/bot-webhook/<room-token>/<auth-token>
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
- **"talk-bot user not found"** — The `talk-bot` user doesn't exist. Re-run Step 1.
|
|
- **"Bot password not configured"** — You haven't entered the bot password in the admin settings, or it was cleared. Re-enter it in Step 3.
|
|
- **Messages not appearing** — Check the Nextcloud log (`data/nextcloud.log` or Settings → Admin → Logging) for errors from the `ncdiscordhook` app.
|
|
- **Image upload fails** — Verify the bot user has file storage quota and the `NCdiscordhook-images` folder can be created.
|
|
|
|
## Security Notes
|
|
|
|
- Each room has its own auth token — treat them like passwords
|
|
- The webhook endpoint is public (no auth required) but validates the auth token from the URL path
|
|
- Admin settings endpoints (`/save-config`, `/rooms`) require admin login
|
|
- Images are stored in the bot user's files and purged after the retention period
|
|
- **Known limitations (to be fixed in a future release):**
|
|
- Auth tokens generated from the settings UI use client-side generation; for higher security, regenerate them via the server API
|
|
- The webhook endpoint has no rate limiting — consider placing it behind a reverse proxy rate limiter if exposing to untrusted sources
|