OpenClaw Manual OpenClaw

OpenClaw Nextcloud Talk Channel

Enterprise
Medium

Connect OpenClaw to Nextcloud Talk, the privacy-focused enterprise communication platform built into the Nextcloud ecosystem. The integration uses a webhook-based bot architecture — Nextcloud Talk sends message events to your Gateway via webhooks, and the bot responds through the Talk REST API. This enables your AI assistant to participate in direct messages, room conversations, and react to messages with emoji, all within your self-hosted Nextcloud environment.

Quick Info
Difficulty Medium
Category Enterprise
Features Supported 4 / 6

Nextcloud Talk Supported Features

Text Messages

Supported

Media & Files

Supported

Reactions

Supported

Threads

Not Supported

Voice Messages

Not Supported

Group Chat

Supported

Nextcloud Talk Prerequisites

  • A Nextcloud server (v27.1+) with administrator access and the Talk app installed
  • A shared secret (40-128 characters) for webhook signature validation
  • The Gateway's webhook endpoint accessible from the Nextcloud server (public URL or internal network)
  • OpenClaw Gateway installed and running
  • The Nextcloud Talk plugin installed via 'openclaw plugins install @openclaw/nextcloud-talk'

Nextcloud Talk Quick Setup

1

Install the Nextcloud Talk plugin

Run 'openclaw plugins install @openclaw/nextcloud-talk' to add Nextcloud Talk support to your Gateway.

2

Register the bot on your Nextcloud server

SSH into your Nextcloud server and run the OCC command: ./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction. Replace <shared-secret> with a strong 40+ character secret, and <webhook-url> with the Gateway's publicly accessible webhook endpoint (e.g., https://gateway.example.com:8788/webhook).

3

Enable the bot and configure

In Nextcloud Talk, go to the room settings and enable the OpenClaw bot. Then add the channel configuration to ~/.openclaw/openclaw.json with your baseUrl and botSecret. Start the Gateway with 'openclaw start' and send a message in the room to verify the connection.

Nextcloud Talk Configuration Example

config.json 
{
  "channels": {
    "nextcloud-talk": {
      "enabled": true,
      "baseUrl": "https://nextcloud.example.com",
      "botSecret": "your-shared-secret-min-40-chars",
      "dmPolicy": "pairing"
    }
  }
}

Nextcloud Talk Deep Dive

Architecture Overview

OpenClaw integrates with Nextcloud Talk through the Talk Bot API (available since Nextcloud 27.1). The architecture is webhook-based: 1. The bot is registered on the Nextcloud server using the OCC command line tool with a shared secret and webhook URL. 2. When a message is posted in a room where the bot is enabled, Nextcloud Talk sends an HTTP POST to the configured webhook URL with the message payload, signed using the shared secret. 3. The Gateway verifies the webhook signature, processes the message through your AI agent, and posts the response back to the conversation using the Talk REST API. This design means the Gateway must expose a webhook endpoint accessible to the Nextcloud server. The webhook listener runs on port 8788 by default and can be customized via the webhookPort and webhookHost configuration options.
The webhook URL must be reachable from the Nextcloud server. For local development, use a tunnel service like ngrok.
Each bot installation generates a unique URL hash (bot-<hash>) used as the actor ID for messages.

Bot Registration via OCC

Nextcloud Talk bots are registered on the server using OCC (Nextcloud Command Console) commands. This is a server-side operation that requires SSH or console access. To install the bot: ./occ talk:bot:install "OpenClaw" "<secret>" "<webhook-url>" --feature reaction Parameters: • name (required): Display name shown as the message author (1-64 characters) • secret (required): Shared secret for webhook signature validation (40-128 characters) • url (required): Your Gateway's webhook endpoint URL • --feature: Bot capabilities — use 'reaction' to enable emoji reactions • --no-setup: Prevents moderators from toggling the bot per-room Other useful OCC commands: • talk:bot:list — List all installed bots • talk:bot:remove <bot-id> — Remove a bot from specific conversations • talk:bot:setup <bot-id> <token> — Enable a bot in a conversation • talk:bot:state <bot-id> <state> — Change bot state (0=disabled, 1=enabled, 2=no-setup) • talk:bot:uninstall <id> — Completely remove a bot from the server
Terminal 
./occ talk:bot:install "OpenClaw" "a]72@Bz&V!LKMO*xhQib7p^E%yzGMG(8a7Bp*x6o" "https://gateway.example.com:8788/webhook" --feature reaction
Generate a strong shared secret using: openssl rand -base64 48
The --feature reaction flag is recommended to allow the bot to react to messages with emoji.

DM Policies

Direct Message (DM) policies control how the bot handles private one-on-one conversations. **pairing (default)** — Unknown senders receive a pairing code that must be verified before the bot responds. This is the most secure mode, requiring explicit user authorization. **open** — Any user who messages the bot receives a response. Requires setting allowFrom to ["*"]. **disabled** — The bot does not respond to direct messages at all. Note: Nextcloud Talk bots cannot initiate DMs — the user must message the bot first. The allowFrom field matches Nextcloud user IDs (not display names).
openclaw.json 
{
  "channels": {
    "nextcloud-talk": {
      "dmPolicy": "pairing",
      "allowFrom": ["user-id-1", "user-id-2"]
    }
  }
}
Bots cannot initiate direct messages in Nextcloud Talk. Users must contact the bot first to start a conversation.

Room Configuration

Room (group chat) policies control which conversations the bot participates in and how it is triggered. **allowlist (default)** — The bot only responds in rooms where it has been explicitly enabled by a moderator via the room settings. Per-room configuration can be customized using the rooms object. Each room is identified by its conversation token and can have independent settings: • requireMention — When true, the bot only responds when @mentioned (default behavior in rooms) • Rooms not listed in the configuration use the default room settings To find a room's token, look at the URL when viewing the room in Nextcloud Talk (e.g., https://nextcloud.example.com/call/<token>).
openclaw.json 
{
  "channels": {
    "nextcloud-talk": {
      "groupPolicy": "allowlist",
      "rooms": {
        "abc123token": {
          "requireMention": true
        },
        "def456token": {
          "requireMention": false
        }
      }
    }
  }
}
A room moderator must enable the bot in the room settings before it can receive messages.
Use requireMention: true for busy rooms to avoid the bot responding to every message.

API Credentials for Room Detection

By default, the webhook payload from Nextcloud Talk does not distinguish between direct messages and room messages. To enable accurate room-type detection, you can provide API credentials. When apiUser and apiPassword are configured, the Gateway makes an additional API call to determine whether an incoming message is from a DM or a room conversation. This allows the bot to apply different policies (dmPolicy vs groupPolicy) correctly. Without API credentials, the bot treats all messages according to a unified policy, which may be sufficient for simple deployments.
openclaw.json 
{
  "channels": {
    "nextcloud-talk": {
      "apiUser": "bot-service-account",
      "apiPassword": "service-account-password",
      "apiPasswordFile": "/run/secrets/nc-api-password"
    }
  }
}
Create a dedicated Nextcloud user account for the API credentials rather than using an admin account.
Use apiPasswordFile to load the password from a file (e.g., Docker secret) instead of storing it in the config.
Without API credentials, the bot cannot distinguish DMs from room messages. This may cause DM-only policies to not function correctly.

Webhook Configuration

The Gateway starts a built-in HTTP server to receive webhook events from Nextcloud Talk. The webhook listener configuration controls how and where the server listens. **webhookPort** (default: 8788) — The port for the webhook HTTP server. **webhookHost** (default: 0.0.0.0) — The interface to bind to. Use 0.0.0.0 to listen on all interfaces or 127.0.0.1 for localhost only. **webhookPath** — Custom URL path for the webhook endpoint. **webhookPublicUrl** — The full public URL that Nextcloud should use to reach the webhook. Required when behind a reverse proxy or NAT. The webhook URL provided during bot installation (OCC command) must match the public URL that resolves to this listener.
openclaw.json 
{
  "channels": {
    "nextcloud-talk": {
      "webhookPort": 8788,
      "webhookHost": "0.0.0.0",
      "webhookPath": "/webhook",
      "webhookPublicUrl": "https://gateway.example.com:8788/webhook"
    }
  }
}
If running behind a reverse proxy, set webhookPublicUrl to the externally accessible URL.
Ensure your firewall allows inbound connections on the webhook port from the Nextcloud server.

Message Handling and Streaming

OpenClaw provides fine-grained control over how messages are chunked and delivered to Nextcloud Talk. **textChunkLimit** — Maximum character count per message chunk. Nextcloud Talk supports long messages, but chunking can improve readability for lengthy AI responses. **chunkMode** — Controls how text is split: 'length' splits at the character limit, 'newline' splits at paragraph boundaries for more natural breaks. **blockStreaming** — When enabled, the bot waits for the complete AI response before sending, instead of streaming partial responses. **blockStreamingCoalesce** — When block streaming is enabled, this combines the final response into a single message instead of multiple chunks. **mediaMaxMb** — Maximum file size (in MB) for media attachments. Note that Nextcloud Talk transmits media as URLs rather than direct file uploads.
openclaw.json 
{
  "channels": {
    "nextcloud-talk": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "blockStreaming": true,
      "blockStreamingCoalesce": true,
      "mediaMaxMb": 10
    }
  }
}
Use blockStreaming: true for cleaner responses in rooms where multiple users are active.
Media is shared as URLs in Nextcloud Talk — the bot cannot upload files directly.

Conversation History

Control how many previous messages are included as context when the AI agent processes a new message. **historyLimit** — Maximum number of previous messages to include for room conversations. **dmHistoryLimit** — Maximum number of previous messages to include for direct message conversations. This can be set independently from the room history limit. Per-DM overrides are also supported, allowing you to configure different history limits for specific users. A higher history limit provides more context for the AI but increases token usage and processing time.
openclaw.json 
{
  "channels": {
    "nextcloud-talk": {
      "historyLimit": 20,
      "dmHistoryLimit": 50
    }
  }
}

Reactions Support

Nextcloud Talk supports emoji reactions on messages, and the OpenClaw bot can both read and add reactions. To enable reaction support, the bot must be registered with the --feature reaction flag during OCC installation. Once enabled, the AI agent can react to user messages with emoji to provide acknowledgment or feedback. Reactions are a lightweight way for the bot to interact without posting full text responses — for example, reacting with a checkmark emoji to confirm a completed task. The Nextcloud Talk Reaction API (available since the bots-v1 capability) handles the underlying mechanics of adding and removing reactions.
The --feature reaction flag must be set during bot installation for reactions to work.
Reactions can be used as a non-intrusive acknowledgment mechanism in busy rooms.

Security and Webhook Signing

All webhook payloads from Nextcloud Talk are signed using the shared secret configured during bot installation. The Gateway verifies each signature to ensure authenticity and integrity. The signing mechanism uses HMAC-SHA256: 1. Nextcloud computes an HMAC-SHA256 hash of the webhook payload body using the shared secret. 2. The signature is included in the HTTP headers of the webhook request. 3. The Gateway independently computes the hash and compares it to the received signature. 4. If the signatures don't match, the request is rejected. This ensures that only legitimate requests from your Nextcloud server are processed. Keep the shared secret confidential and rotate it periodically by reinstalling the bot with a new secret.
Use a cryptographically strong secret: openssl rand -base64 48 generates a suitable value.
Store the secret using botSecretFile to avoid committing it to version control.
Never expose the shared secret in public repositories or logs. Use environment variables or secret files for production deployments.

Nextcloud Talk Configuration Reference

enabled
Type: boolean Default: true

Enable or disable the Nextcloud Talk channel

baseUrl
Type: string Default: ""

Full URL of your Nextcloud server (e.g., https://nextcloud.example.com)

botSecret
Type: string Default: ""

Shared secret used for webhook signature validation (must match the OCC install secret)

botSecretFile
Type: string Default: ""

Path to a file containing the shared secret (alternative to inline botSecret)

apiUser
Type: string Default: ""

Nextcloud username for API calls (used for room-type detection)

apiPassword
Type: string Default: ""

Password for the API user account

apiPasswordFile
Type: string Default: ""

Path to a file containing the API password (alternative to inline apiPassword)

dmPolicy
Type: string Default: "pairing"

DM access policy: 'pairing' (verification code), 'open' (any user), or 'disabled' (no DMs)

allowFrom
Type: string[] Default: []

Nextcloud user IDs allowed to DM the bot (use ["*"] for open access)

groupPolicy
Type: string Default: "allowlist"

Room access policy: 'allowlist' (moderator-enabled rooms only)

webhookPort
Type: number Default: 8788

Port for the built-in webhook HTTP server

webhookHost
Type: string Default: "0.0.0.0"

Interface to bind the webhook server to

webhookPath
Type: string Default: "/webhook"

URL path for the webhook endpoint

webhookPublicUrl
Type: string Default: ""

Full public URL for the webhook endpoint (required behind reverse proxy)

historyLimit
Type: number Default: 20

Maximum previous messages included as context for room conversations

dmHistoryLimit
Type: number Default: 50

Maximum previous messages included as context for DM conversations

textChunkLimit
Type: number Default: 4000

Maximum characters per message chunk

chunkMode
Type: string Default: "length"

Text splitting mode: 'length' (character limit) or 'newline' (paragraph boundaries)

blockStreaming
Type: boolean Default: false

Wait for complete AI response before sending (no streaming)

blockStreamingCoalesce
Type: boolean Default: false

Combine streaming chunks into a single final message

mediaMaxMb
Type: number Default: 10

Maximum file size in MB for media URL references

Nextcloud Talk Frequently Asked Questions

Nextcloud Talk Troubleshooting

Bot does not respond to messages

The webhook URL is unreachable, the bot is not enabled in the room, or the shared secret does not match.

Verify the webhook URL is accessible from the Nextcloud server (test with curl). Check that the bot is enabled in the room settings. Ensure the botSecret in openclaw.json matches the secret used in the OCC install command.
Webhook signature verification fails

The shared secret in openclaw.json does not match the one used during bot installation.

Verify both secrets match exactly. If uncertain, uninstall and reinstall the bot with a known secret. Check Gateway logs for signature mismatch errors.
Bot responds in DMs but not in rooms

The bot has not been enabled by a moderator in the target room, or requireMention is true and the bot was not @mentioned.

Ask a room moderator to enable the bot in room settings. If requireMention is configured, ensure users @mention the bot name. Check the rooms configuration in openclaw.json.
Cannot distinguish DMs from room messages

API credentials (apiUser, apiPassword) are not configured.

Add apiUser and apiPassword to your nextcloud-talk channel configuration. Create a dedicated Nextcloud service account for this purpose. The Gateway uses these credentials to query the Talk API for conversation type detection.
Gateway fails to start the webhook listener

The configured webhook port is already in use or the host binding is invalid.

Change webhookPort to an available port (default: 8788). If binding to a specific interface, verify the webhookHost IP address is correct. Check for port conflicts using 'lsof -i :8788' or 'netstat -tlnp'.
View Full Documentation Back to All Channels

Related Channels

Feishu / Lark

Medium

OpenClaw Feishu/Lark integration via WebSocket

Setup Guide

Slack

Medium

OpenClaw workspace app via Bolt SDK

Setup Guide

Google Chat

Medium

OpenClaw Google Chat API app via HTTP endpoint

Setup Guide