99 lines
3.0 KiB
Markdown
99 lines
3.0 KiB
Markdown
# Nextcloud Talk Setup
|
|
|
|
This guide covers native Nextcloud Talk integration for ZeroClaw.
|
|
|
|
## 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.
|
|
|
|
## 2. Configuration
|
|
|
|
Add this section in `~/.zeroclaw/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 = ["*"]
|
|
```
|
|
|
|
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).
|
|
|
|
Environment override:
|
|
|
|
- `ZEROCLAW_NEXTCLOUD_TALK_WEBHOOK_SECRET` overrides `webhook_secret` when set.
|
|
|
|
## 3. Gateway endpoint
|
|
|
|
Run the daemon or gateway and expose the webhook endpoint:
|
|
|
|
```bash
|
|
zeroclaw daemon
|
|
# or
|
|
zeroclaw 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, ZeroClaw 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`.
|
|
|
|
## 5. Message routing behavior
|
|
|
|
- ZeroClaw accepts both payload variants:
|
|
- legacy Talk webhook payloads (`type = "message"`)
|
|
- Activity Streams 2.0 payloads (`type = "Create"` + `object.type = "Note"`)
|
|
- ZeroClaw ignores bot-originated webhook events (`actorType = bots` or `actor.type = "Application"`).
|
|
- ZeroClaw ignores non-message/system events.
|
|
- Reply routing uses the Talk room token from `object.token` (legacy) or `target.id` (AS2).
|
|
- For actor allowlists, both full (`users/alice`) and short (`alice`) IDs are accepted.
|
|
|
|
Example Activity Streams 2.0 webhook payload:
|
|
|
|
```json
|
|
{
|
|
"type": "Create",
|
|
"actor": { "type": "Person", "id": "users/test", "name": "test" },
|
|
"object": {
|
|
"type": "Note",
|
|
"id": "177",
|
|
"content": "{\"message\":\"hello\",\"parameters\":[]}",
|
|
"mediaType": "text/markdown"
|
|
},
|
|
"target": { "type": "Collection", "id": "yyrubgfp", "name": "TESTCHAT" }
|
|
}
|
|
```
|
|
|
|
## 6. Quick validation checklist
|
|
|
|
1. Set `allowed_users = ["*"]` for first-time validation.
|
|
2. Send a test message in the target Talk room.
|
|
3. Confirm ZeroClaw 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).
|