Nextcloud Talk

Nextcloud Talk integration via the Talk Bot webhook protocol. Self-hosted, federated, and E2E-capable: another sovereign-communication option alongside Matrix and Mattermost.

Who can talk to the agent

Inbound senders are gated against the peer set resolved for the bound agent, drawn from the peer_groups config the agent belongs to. Matching strips a leading @ and is case-insensitive against the channel’s native sender identifier. An empty set denies everyone; a set containing "*" accepts anyone; otherwise only the listed external peers (and peer agents) are accepted. This is separate from gateway pairing (gateway.require_pairing), which authenticates HTTP/WebSocket clients, not chat-channel senders.

A peer group for nextcloud sets channel to nextcloud, lists the allowed senders in external_peers (for nextcloud, the Nextcloud actor ID; ["*"] accepts anyone), optionally names peer agents for cross-agent dispatch, an ignore blocklist, and an output_modality (mirror, voice, or text). See Peer Groups for the field reference.

Where to set this:

What this integration does

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

Prerequisites

• Nextcloud server with the Talk app enabled (v17 or later recommended)
• Bot account in Talk settings, give it a display name (e.g. zeroclaw-bot)
• Bot app token from the Talk admin UI for OCS API bearer auth (used for outbound replies)
• Webhook secret from the Talk admin UI if you want signature verification (strongly recommended)
• Publicly-reachable gateway: see Setup → Container for tunnel options if self-hosted

Configuration

zeroclaw config set channels.nextcloud_talk.<alias>.app_token    # masked input, stored encrypted

export ZEROCLAW_channels__nextcloud_talk__<alias>__app_token=

zeroclaw config set channels.nextcloud_talk.<alias>.base_url <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__base_url=

zeroclaw config set channels.nextcloud_talk.<alias>.bot_name <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__bot_name=

zeroclaw config set channels.nextcloud_talk.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__draft_update_interval_ms=

zeroclaw config set channels.nextcloud_talk.<alias>.excluded_tools <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__excluded_tools=

zeroclaw config set channels.nextcloud_talk.<alias>.proxy_url <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__proxy_url=

zeroclaw config set channels.nextcloud_talk.<alias>.stream_mode <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__stream_mode=

zeroclaw config set channels.nextcloud_talk.<alias>.webhook_secret    # masked input, stored encrypted

export ZEROCLAW_channels__nextcloud_talk__<alias>__webhook_secret=

The channel is read from the default alias. Set it through any config surface:

webhook_secret can also be supplied at runtime via the generic env override ZEROCLAW_channels__nextcloud_talk__default__webhook_secret, useful for rotating it without editing the config.

Gateway endpoint

zeroclaw daemon

Configure your Talk bot’s webhook URL to point at:

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

Local development? Configure [tunnel] in your config (ngrok, Cloudflare, or Tailscale) and the gateway exposes itself on startup: see Operations → Network deployment.

Signature verification

When webhook_secret is set, inbound requests must carry:

• X-Nextcloud-Talk-Random header
• X-Nextcloud-Talk-Signature header

ZeroClaw verifies:

expected_sig = hex(hmac_sha256(secret, random + raw_request_body))
if X-Nextcloud-Talk-Signature != expected_sig:
    return 401

Without a secret, no verification: don’t expose this endpoint publicly in that mode.

Message routing

• Bot-originated events (actorType = "bots") are ignored: prevents feedback loops
• System events (joins, leaves, membership changes) are ignored
• Non-message events are ignored
• User messages are dispatched to the agent loop
• Replies go back to the originating room via the token in the webhook payload

Quick validation

1. Set external_peers = ["*"] in the peer group for first-time testing
2. Send a test message in the configured Talk room
3. Confirm ZeroClaw receives and replies in the same room
4. Tighten the peer group to explicit actor IDs (e.g. ["alice", "bob"])

Troubleshooting

• 404 Nextcloud Talk not configured: [channels.nextcloud_talk.default] section missing or enabled = false
• 401 Invalid signature: secret mismatch, wrong random header, or body-signing bug. Check the raw body is being signed (not the parsed JSON)
• No reply, webhook 200: event was filtered. Check logs for “actorType = bots” or a sender not in the peer set
• Replies delivered but look wrong: check thread context; Talk replies are currently root-level only

Streaming

Nextcloud Talk does not support message edits via the Bot API, so streaming draft updates are disabled for this channel. Replies are sent on stream completion only.

Self-hosting notes

• TLS: terminate at your reverse proxy; webhook signature verification works over HTTP-to-container loopback
• The OCS API is authenticated via Bearer token: use the bot app token from the Talk admin UI
• Rate limits are Nextcloud-server dependent; the default bot doesn’t run into them in normal conversation cadences
• Per-channel proxy: set proxy_url to override the global [proxy] setting for Nextcloud Talk only (http://, https://, socks5://, socks5h://)

See also

• Matrix: richer E2EE but more operational complexity
• Mattermost: similar self-hosted posture, different protocol
• Channels → Overview