# Nextcloud Talk Setup

This guide covers native Nextcloud Talk integration for Construct.

## 1. What this integration does

- Receives inbound Talk bot webhook events via `POST /nextcloud-talk`.
- Verifies webhook signatures (HMAC-SHA256) when a secret is configured.
- Sends bot replies back to Talk rooms via Nextcloud OCS API.

<!-- TODO screenshot: Nextcloud Talk admin settings panel showing webhook integration configuration -->
![Nextcloud Talk admin settings panel showing webhook integration configuration](../assets/setup/nextcloud-talk-01-webhook-config.png)

## 2. Configuration

Add this section in `~/.construct/config.toml`:

```toml
[channels_config.nextcloud_talk]
base_url = "https://cloud.example.com"
app_token = "nextcloud-talk-app-token"
webhook_secret = "optional-webhook-secret"
allowed_users = ["*"]
# bot_name is the Nextcloud Talk display name of the bot (e.g. "construct").
# Used to ignore the bot's own messages and prevent feedback loops.
# bot_name = "construct"
```

Field reference:

- `base_url`: Nextcloud base URL.
- `app_token`: Bot app token used as `Authorization: Bearer <token>` for OCS send API.
- `webhook_secret`: Shared secret for verifying `X-Nextcloud-Talk-Signature`.
- `allowed_users`: Allowed Nextcloud actor IDs (`[]` denies all, `"*"` allows all).
- `bot_name`: Display name of the bot in Nextcloud Talk. When set, messages from this actor name are silently ignored to prevent feedback loops.

Environment override:

- `CONSTRUCT_NEXTCLOUD_TALK_WEBHOOK_SECRET` overrides `webhook_secret` when set.

## 3. Gateway endpoint

Run the daemon or gateway and expose the webhook endpoint:

```bash
construct daemon
# or
construct gateway --host 127.0.0.1 --port 3000
```

Configure your Nextcloud Talk bot webhook URL to:

- `https://<your-public-url>/nextcloud-talk`

## 4. Signature verification contract

When `webhook_secret` is configured, Construct verifies:

- header `X-Nextcloud-Talk-Random`
- header `X-Nextcloud-Talk-Signature`

Verification formula:

- `hex(hmac_sha256(secret, random + raw_request_body))`

If verification fails, the gateway returns `401 Unauthorized`.

<!-- TODO screenshot: Nextcloud Talk room showing the Construct bot responding to a user message -->
![Nextcloud Talk room showing the Construct bot responding to a user message](../assets/setup/nextcloud-talk-02-bot-message.png)

## 5. Message routing behavior

- Construct ignores bot-originated webhook events (`actorType = bots`).
- Construct ignores non-message/system events.
- Reply routing uses the Talk room token from the webhook payload.

## 6. Quick validation checklist

1. Set `allowed_users = ["*"]` for first-time validation.
2. Send a test message in the target Talk room.
3. Confirm Construct receives and replies in the same room.
4. Tighten `allowed_users` to explicit actor IDs.

## 7. Troubleshooting

- `404 Nextcloud Talk not configured`: missing `[channels_config.nextcloud_talk]`.
- `401 Invalid signature`: mismatch in `webhook_secret`, random header, or raw-body signing.
- No reply but webhook `200`: event filtered (bot/system/non-allowed user/non-message payload).
