### N8N Workflow Integration Setup (Bash)

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Bash commands for setting up and configuring N8N to integrate with Olvid bots. This includes starting the Docker services, accessing the N8N interface, installing the Olvid community node, creating Olvid API credentials within N8N, and building workflows using Olvid triggers and actions.

```bash
# Setup steps:
# 1. Start services
docker compose up -d

# 2. Open N8N interface
open http://localhost:5678

# 3. Install community node
# Settings > Community Nodes > Install
# Package: n8n-nodes-olvid

# 4. Create credentials
# Add: Olvid API
# - Server URL: http://daemon:50051
# - Client Key: your-client-key-uuid

# 5. Create workflow with Olvid trigger/actions
# - Trigger: "On Message Received"
# - Actions: "Send Message", "Create Discussion", etc.
```

--------------------------------

### Start the Bot

Source: https://github.com/olvid-io/olvid-bot-documentation/blob/main/examples/broadcast-bot/README.md

Starts the Olvid Bot by executing the main Python script. The bot will run continuously until manually stopped with CTRL+C. This script serves as a foundation for custom bot projects.

```shell
python3 main.py
```

--------------------------------

### Install Dependencies

Source: https://github.com/olvid-io/olvid-bot-documentation/blob/main/examples/broadcast-bot/README.md

Installs the Python dependencies required for the Olvid Bot using pip. It reads the necessary packages from the 'requirements.txt' file.

```shell
pip3 install -r requirements.txt
```

--------------------------------

### Clone Repository

Source: https://github.com/olvid-io/olvid-bot-documentation/blob/main/examples/broadcast-bot/README.md

Clones the Olvid Bot documentation repository from GitHub and navigates into the broadcast bot example directory. This is the first step to get the project code.

```shell
git clone https://github.com/olvid-io/Olvid-Bot-Documentation
cd Olvid-Bot-Documentation/examples/broadcast-bot
```

--------------------------------

### Python Olvid Client Setup

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Basic setup for an Olvid bot client using Python. It loads environment variables for configuration and connects to the Olvid service to fetch identity information. Requires the 'olvid' and 'python-dotenv' libraries.

```python
from olvid import OlvidClient
from dotenv import load_dotenv
import asyncio

# Load .env file
load_dotenv()

# Client automatically reads environment variables
client = OlvidClient()

async def main():
    identity = await client.identity_get()
    print(f"Connected as: {identity.display_name}")
    await client.run()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Set Up Olvid Client Key

Source: https://github.com/olvid-io/olvid-bot-documentation/blob/main/examples/broadcast-bot/README.md

Sets up the Olvid client key by creating a .env file with the OLVID_CLIENT_KEY environment variable. This key is essential for the bot to authenticate with the Olvid daemon. If the key is forgotten, it can be retrieved using the 'olvid CLI' command 'key get'.

```shell
echo OLVID_CLIENT_KEY=....> .env
```

--------------------------------

### N8N Workflow Integration Setup (Docker Compose)

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Configuration for `docker-compose.yaml` to integrate N8N with the Olvid bot daemon. This setup involves defining services for both the Olvid daemon and N8N, setting environment variables, and mounting volumes for persistent data. It also includes installing the necessary Olvid community node for N8N.

```yaml
# docker-compose.yaml - Add N8N service
services:
  daemon:
    image: olvid/bot-daemon:1.5.0
    environment:
      - OLVID_ADMIN_CLIENT_KEY_CLI=SetARandomValue
    ports:
      - 50051:50051
    volumes:
      - ./data:/daemon/data

  n8n:
    image: docker.n8n.io/n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      - N8N_REINSTALL_MISSING_PACKAGES=true
    volumes:
      - ./n8n_data:/home/node/.n8n
    entrypoint: sh -c "npm install @olvid/bot-node@0.0.15-alpha && tini -- /docker-entrypoint.sh"
```

--------------------------------

### Python Message Sending and Handling

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Covers sending messages, handling incoming messages via callbacks, and using command decorators for pattern-based message processing with examples for ping, help, and choose commands.

```APIDOC
## Python Message Sending and Handling

### Description
This section details how to send messages to discussions and manage incoming messages using notification callbacks (`on_message_received`) and command decorators (`@OlvidClient.command`) for specific command handling.

### Method
N/A (Client-side message handling and sending)

### Endpoint
N/A (Client-side message handling and sending)

### Parameters
None

### Request Example
```python
from olvid import OlvidClient, datatypes

class ChatBot(OlvidClient):
    # Handle all incoming messages
    async def on_message_received(self, message: datatypes.Message):
        print(f"Received: {message.body}")
        if message.body.lower() == "hello":
            await message.reply("Hello there!")

    # Command decorator for pattern-based handling
    @OlvidClient.command(regexp_filter="^!ping")
    async def ping(self, message: datatypes.Message):
        await message.reply("pong!")

    @OlvidClient.command(regexp_filter="^!help")
    async def help(self, message: datatypes.Message):
        help_text = """
        Available commands:
        !ping - Test bot responsiveness
        !help - Show this message
        """
        await message.reply(help_text)

    @OlvidClient.command(regexp_filter="^!choose")
    async def choose(self, message: datatypes.Message, matched_body: str):
        import secrets
        choices = message.body.removeprefix(matched_body).strip().split()
        if choices:
            await message.reply(f"I chose: {secrets.choice(choices)}")
        else:
            await message.reply("Please provide options: !choose option1 option2")

# Run the bot
import asyncio
asyncio.run(ChatBot().run())
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
```
Received: hello
Received: !ping
Received: !help
Received: !choose apple banana orange
```
```

--------------------------------

### Set up Olvid Browser Client with gRPC-Web Proxy

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Configures the Olvid bot API for web browsers using a gRPC-Web proxy. This involves manual setup of the server URL and client key directly in the JavaScript code.

```javascript
// HTML: <script type="module">
import {OlvidClient} from "https://cdn.jsdelivr.net/npm/@olvid/bot-web/+esm";

// Manual configuration (no environment variables in browser)
const client = new OlvidClient({
    serverUrl: "http://localhost:8080",
    clientKey: "your-client-key-uuid"
});

async function init() {
    const identity = await client.identityGet();
    document.getElementById('bot-name').textContent = identity.displayName;

    // List discussions
    for await (const discussion of client.discussionList({})) {
        const li = document.createElement('li');
        li.textContent = discussion.title;
        document.getElementById('discussions').appendChild(li);
    }

    // Handle incoming messages
    client.onMessageReceived({
        callback: async (message) => {
            console.log(`New message: ${message.body}`);
            const notification = document.createElement('div');
            notification.textContent = message.body;
            document.getElementById('notifications').appendChild(notification);
        }
    });

    await client.run();
}

init().catch(console.error);
// </script>
```

--------------------------------

### Python OlvidClient Storage API

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Demonstrates the usage of the Python OlvidClient's storage API for persisting key-value data. Shows how to set and get global storage values and discussion-specific storage values, including deletion.

```python
from olvid import OlvidClient
import asyncio

async def storage_example():
    client = OlvidClient()

    # Global storage - shared across all discussions
    await client.storage_set(key="bot_version", value="1.0.0")
    version = await client.storage_get(key="bot_version")
    print(f"Bot version: {version}")

    # Discussion-specific storage
    discussion_id = 1
    webhook_url = "https://example.com/webhook/abc123"

    await client.discussion_storage_set(
        key="webhook_url",
        value=webhook_url,
        discussion_id=discussion_id
    )

    # Retrieve per-discussion data
    stored_url = await client.discussion_storage_get(
        key="webhook_url",
        discussion_id=discussion_id
    )
    print(f"Webhook URL for discussion {discussion_id}: {stored_url}")

    # Delete stored value
    await client.discussion_storage_set(
        key="webhook_url",
        value=None,
        discussion_id=discussion_id
    )

asyncio.run(storage_example())
```

--------------------------------

### Daemon Docker Compose Configuration

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Full Docker Compose setup for the Olvid Bot daemon. Includes environment variables for admin keys, server ports, logging levels, and optional TLS/SSL configurations for both server and mutual authentication. It also defines volumes for data, backups, and credentials.

```yaml
# docker-compose.yaml
version: "3.8"

services:
  daemon:
    image: "olvid/bot-daemon:1.5.0"
    container_name: "olvid-daemon"
    restart: "unless-stopped"

    environment:
      # Required: Admin key for CLI
      - OLVID_ADMIN_CLIENT_KEY_CLI=change-this-to-random-uuid

      # Optional: Server settings
      - DAEMON_PORT=50051
      - DAEMON_LOG_LEVEL=INFO
      - ENGINE_LOG_LEVEL=WARNING

      # Optional: TLS/SSL (server authentication)
      - DAEMON_CERTIFICATE_FILE=/credentials/server.pem
      - DAEMON_KEY_FILE=/credentials/server.key

      # Optional: Mutual TLS (client authentication)
      - DAEMON_ROOT_CERTIFICATE_FILE=/credentials/ca.pem

      # Optional: JVM proxy settings
      - JAVA_FLAGS=-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080

    ports:
      - "50051:50051"

    volumes:
      - "./data:/daemon/data"
      - "./backups:/daemon/backups"
      - "./credentials:/credentials:ro"

  cli:
    image: "olvid/bot-python-runner:1.5.0"
    entrypoint: "olvid-cli"
    environment:
      - OLVID_ADMIN_CLIENT_KEY=change-this-to-random-uuid
      - OLVID_DAEMON_TARGET=daemon:50051
      # Optional: TLS client settings
      - OLVID_SERVER_CERTIFICATE_PATH=/credentials/server.pem
    stdin_open: true
    tty: true
    profiles: ["cli"]
    volumes:
      - "./credentials:/credentials:ro"

# Start daemon
# docker compose up -d

# Run CLI
# docker compose run --rm cli
```

--------------------------------

### Utilize Olvid Message Helper Methods in JavaScript

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Shows how to use convenient helper methods on message and discussion objects in JavaScript for common operations. Includes replying, getting sender/discussion info, attachments, and reacting to messages.

```javascript
import {OlvidClient, datatypes} from "@olvid/bot-node";

const client = new OlvidClient();

client.onMessageReceived({
    callback: async (message: datatypes.Message) => {
        // Reply to message
        await message.reply(client, "Thanks for your message!");

        // Get sender contact information
        const sender = await message.getSenderContact(client);
        console.log(`From: ${sender?.displayName}`);

        // Get discussion
        const discussion = await message.getDiscussion(client);
        console.log(`In: ${discussion?.title}`);

        // Get attachments
        const attachments = await message.getAttachments(client);
        for (const attachment of attachments) {
            console.log(`Attachment: ${attachment.filename}`);
            // Save to disk
            await attachment.save(client, `./downloads/${attachment.filename}`);
        }

        // React to message
        await client.messageReact({
            messageId: message.id,
            reaction: "👍"
        });
    }
});

client.run().catch(console.error);
```

--------------------------------

### CLI: Storage Operations

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Commands for managing persistent key-value storage using the command-line interface. Supports setting and getting global storage values (requires admin key) and discussion-specific storage values, as well as deleting stored values.

```bash
# Global storage (requires admin key)
olvid-cli -k admin-key-uuid storage set bot_config "enabled=true"
olvid-cli -k admin-key-uuid storage get bot_config

# Discussion-specific storage
olvid-cli -i 1 storage set webhook_url "https://example.com" --discussion 1
olvid-cli -i 1 storage get webhook_url --discussion 1

# Delete stored value
olvid-cli -i 1 storage set webhook_url "" --discussion 1

# List all storage keys (if supported)
olvid-cli -i 1 storage get
```

--------------------------------

### Python Auto-Invitation and Utility Tools

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Python code demonstrating the use of Olvid bot utility tools. This includes setting up an auto-invitation bot, configuring filters for invitations, and implementing a self-cleaning bot to automatically delete messages after processing. Assumes the 'olvid' library is installed.

```python
from olvid import OlvidClient, tools, datatypes
import asyncio

class MyBot(OlvidClient):
    async def on_message_received(self, message: datatypes.Message):
        # Process message
        await message.reply("Message received!")

async def main():
    client = MyBot()

    # Auto-accept all group invitations in background
    tools.AutoInvitationBot()

    # Alternative: Auto-accept with filter
    auto_invite = tools.AutoInvitationBot()
    auto_invite.filter = datatypes.InvitationFilter(
        # Add filter criteria here
    )

    # Self-cleaning bot: delete messages after processing
    # Useful for privacy-focused bots
    tools.SelfCleaningBot(client)

    # For Keycloak environments: auto-add Keycloak users
    # tools.KeycloakAutoInvitationBot()

    await client.run()

asyncio.run(main())
```

--------------------------------

### Broadcast Message with Curl

Source: https://github.com/olvid-io/olvid-bot-documentation/blob/main/examples/broadcast-bot/README.md

Sends a simple broadcast message using the curl command. This example demonstrates how to make an HTTP POST request to the bot's webhook URL to send a message to all contacts and groups. The message content is provided as the POST data.

```shell
curl -X POST --data 'Hello Olvid !' http://localhost:8080/$WEBHOOK_NONCE
```

--------------------------------

### Docker Compose: Add gRPC-Web Proxy

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

This configuration adds a gRPC-Web proxy service to the Docker Compose setup. The proxy routes requests to the daemon service and is configured to run without TLS and allow all origins. It exposes port 8080 for external access.

```yaml
services:
  daemon:
    image: "olvid/bot-daemon:1.5.0"
    environment:
      - OLVID_ADMIN_CLIENT_KEY_CLI=SetARandomValue
    ports:
      - "50051:50051"
    volumes:
      - "./data:/daemon/data"

  proxy:
    image: "olvid/grpc-web-proxy"
    ports:
      - "8080:8080"
    command:
      - "--backend_addr=daemon:50051"
      - "--run_tls_server=false"
      - "--allow_all_origins"
```

--------------------------------

### Python OlvidClient Initialization

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Demonstrates how to initialize the OlvidClient in Python, connect to the Olvid daemon using environment variables, and retrieve basic identity and discussion information.

```APIDOC
## Python OlvidClient Initialization

### Description
Initializes the `OlvidClient` for Python bot development, automatically configuring the connection to the Olvid daemon using environment variables. It shows how to fetch the bot's identity and list discussions.

### Method
N/A (Client-side initialization)

### Endpoint
N/A (Client-side initialization)

### Parameters
None

### Request Example
```python
from olvid import OlvidClient, datatypes
import asyncio

# Initialize client with environment variables
# OLVID_CLIENT_KEY and OLVID_DAEMON_TARGET must be set
client = OlvidClient()

async def main():
    # Get current bot identity
    identity = await client.identity_get()
    print(f"Bot: {identity.display_name}")

    # List all discussions
    async for discussion in client.discussion_list():
        print(f"Discussion {discussion.id}: {discussion.title}")

    # Start listening for notifications
    await client.run()

if __name__ == "__main__":
    asyncio.run(main())
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
```
Bot: YourBotName
Discussion 123: General Chat
Discussion 456: Development Team
```
```

--------------------------------

### Initialize Python OlvidClient and Interact

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Initializes the OlvidClient in Python using environment variables for connection and demonstrates basic interactions like fetching identity and listing discussions. Requires OLVID_CLIENT_KEY and OLVID_DAEMON_TARGET environment variables to be set.

```python
from olvid import OlvidClient, datatypes
import asyncio

# Initialize client with environment variables
# OLVID_CLIENT_KEY and OLVID_DAEMON_TARGET must be set
client = OlvidClient()

async def main():
    # Get current bot identity
    identity = await client.identity_get()
    print(f"Bot: {identity.display_name}")

    # List all discussions
    async for discussion in client.discussion_list():
        print(f"Discussion {discussion.id}: {discussion.title}")

    # Start listening for notifications
    await client.run()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Initialize OlvidClient in Node.js/TypeScript

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Initializes the OlvidClient for Node.js and TypeScript projects using environment variables. Supports modern async/await syntax and BigInt for IDs. Requires OLVID_CLIENT_KEY and OLVID_DAEMON_TARGET.

```typescript
import {OlvidClient, datatypes} from "@olvid/bot-node";

// Initialize with environment variables
// OLVID_CLIENT_KEY and OLVID_DAEMON_TARGET required
const client = new OlvidClient();

async function main() {
    // Get bot identity
    const identity = await client.identityGet();
    console.log(`Bot: ${identity.displayName}`);

    // List discussions (async iterator)
    for await (const discussion of client.discussionList({})) {
        console.log(`Discussion ${discussion.id}: ${discussion.title}`);
    }

    // Send message
    const message = await client.messageSend({
        discussionId: 1n,  // BigInt required
        body: "Hello from TypeScript!"
    });

    // Start listening for notifications
    await client.run();
}

main().catch(console.error);
```

--------------------------------

### Olvid Daemon Backup and Restore

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Commands for managing Olvid daemon backups and performing restores. Backups are stored in `/daemon/backups/` and include a `backup_seed.txt` file crucial for restoration. The restore process uses a Docker container to replace current data with a specified backup file.

```bash
# Backups are created automatically in /daemon/backups/
# Structure: /daemon/backups/XXXX/backup_YYYY-MM-DD_HH-MM-SS.bytes

# View backups
ls -la ./backups/0001/

# Important: Save backup_seed.txt file - required for restore!
cat ./backups/0001/backup_seed.txt

# Restore from backup (replaces current data)
docker run --rm \
  -v ./data:/daemon/data \
  -v ./backups:/daemon/backups \
  olvid/bot-daemon:1.5.0 \
  -r /daemon/backups/0001/backup_2025-01-15_10-30-00.bytes

# Restore with custom seed file location
docker run --rm \
  -v ./data:/daemon/data \
  -v ./backups:/daemon/backups \
  -v ./custom_seed.txt:/seed.txt:ro \
  olvid/bot-daemon:1.5.0 \
  -r /daemon/backups/0001/backup_2025-01-15_10-30-00.bytes \
  -s /seed.txt

# After restore, restart daemon
docker compose restart daemon
```

--------------------------------

### Python Storage API for Persistent Data

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Explains how to use the Storage API to persistently store and retrieve key-value data, both globally and on a per-discussion basis, for managing configuration and state.

```APIDOC
## Python Storage API for Persistent Data

### Description
This API allows bots to store and retrieve persistent data. It supports both global storage (accessible by all discussions) and discussion-specific storage, which is useful for storing per-conversation settings like webhook URLs or state information.

### Method
N/A (Client-side storage operations)

### Endpoint
N/A (Client-side storage operations)

### Parameters
None

### Request Example
```python
from olvid import OlvidClient
import asyncio

async def storage_example():
    client = OlvidClient()

    # Global storage - shared across all discussions
    await client.storage_set(key="bot_version", value="1.0.0")
    version = await client.storage_get(key="bot_version")
    print(f"Bot version: {version}")

    # Discussion-specific storage
    discussion_id = 1
    webhook_url = "https://example.com/webhook/abc123"

    await client.discussion_storage_set(
        key="webhook_url",
        value=webhook_url,
        discussion_id=discussion_id
    )

    # Retrieve per-discussion data
    stored_url = await client.discussion_storage_get(
        key="webhook_url",
        discussion_id=discussion_id
    )
    print(f"Webhook URL for discussion {discussion_id}: {stored_url}")

    # Delete stored value
    await client.discussion_storage_set(
        key="webhook_url",
        value=None,
        discussion_id=discussion_id
    )

asyncio.run(storage_example())
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
```
Bot version: 1.0.0
Webhook URL for discussion 1: https://example.com/webhook/abc123
```
```

--------------------------------

### CLI: Identity and Key Management

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Command-line interface commands for managing identities and client keys. This includes creating new identities interactively or non-interactively, retrieving identity details and invitation links, creating and managing client keys, and switching between identities.

```bash
# Start CLI in interactive mode
docker compose run --rm cli
# or if olvid-cli is installed locally
olvid-cli

# Create new identity (interactive)
0 > identity new John Doe "Software Engineer" "Acme Corp"
# Save the client key provided
# Scan QR code to add bot to contacts

# Non-interactive identity creation
olvid-cli -i 0 identity new John Doe

# Get current identity details
1 > identity get

# Get invitation link for sharing
1 > identity get -l
# Output: https://invitation.olvid.io/#...

# Create client key for bot authentication
1 > key new my-bot-key 1
# Output: Created key: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

# Create admin key (identity_id = 0)
1 > key new admin-key 0

# List all client keys
1 > key get
# Shows: key_uuid, name, identity_id, admin status

# Delete key
1 > key rm aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

# Switch identity in interactive mode
1 > identity current 2
# Prompt changes to: 2 >
```

--------------------------------

### Python Client Configuration with TLS

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Configuration for the Python Olvid Bot client using environment variables. It specifies the client key and daemon target address. Optional settings for simple TLS (server authentication only) are also provided, requiring the path to the server certificate.

```bash
# .env file for Python bot
OLVID_CLIENT_KEY=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
OLVID_DAEMON_TARGET=localhost:50051

# Optional: Simple TLS (server authentication only)
OLVID_SERVER_CERTIFICATE_PATH=./credentials/server.pem
```

--------------------------------

### Environment Variables for Bot Configuration

Source: https://github.com/olvid-io/olvid-bot-documentation/blob/main/examples/broadcast-bot/README.md

Defines essential environment variables for configuring the Olvid Bot's webhook server and behavior. These include the server host and port, a webhook nonce for privacy, and the welcome message sent by the bot.

```shell
# ip adress the webhook server listens on
SERVER_HOST=0.0.0.0
# port used by webhook server
SERVER_PORT=8080
# add a prefix in webhook url to make it "private"
WEBHOOK_NONCE=
# message sent by your bot when add it as a contact or in a group
WELCOME_MESSAGE='Hi 👋 !'
```

--------------------------------

### Handle Olvid Bot Events with Callbacks and Decorators

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Demonstrates handling incoming messages and events using both a callback-based approach and class-based decorators in TypeScript. This allows for structured bot development.

```typescript
import {OlvidClient, datatypes, command, onMessageReceived} from "@olvid/bot-node";

// Callback-based approach
const client = new OlvidClient();

client.onMessageReceived({
    callback: async (message: datatypes.Message) => {
        console.log(`Received: ${message.body}`);
        if (message.body === "hello") {
            await message.reply(client, "Hello there!");
        }
    },
    // Optional filter
    filter: new datatypes.MessageFilter({
        bodySearch: "urgent"
    }),
    count: 0n  // 0 = unlimited
});

// Class-based approach with decorators
class ChatBot extends OlvidClient {
    @command("^!ping")
    async ping(message: datatypes.Message) {
        await message.reply(this, "pong!");
    }

    @command("^!help")
    async help(message: datatypes.Message) {
        const helpText = `
Available commands:
!ping - Test bot responsiveness
!help - Show this message
        `.trim();
        await message.reply(this, helpText);
    }

    @onMessageReceived()
    async messageReceived(message: datatypes.Message) {
        console.log(`[${message.id}] ${message.body}`);
    }
}

// Run bot
new ChatBot().run().catch(console.error);
```

--------------------------------

### Python Bot Message Handling with Commands

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Defines a Python chatbot class inheriting from OlvidClient to handle incoming messages and implement commands using decorators. Supports direct replies, pattern-based command matching with regular expressions, and dynamic command arguments.

```python
from olvid import OlvidClient, datatypes

class ChatBot(OlvidClient):
    # Handle all incoming messages
    async def on_message_received(self, message: datatypes.Message):
        print(f"Received: {message.body}")
        if message.body.lower() == "hello":
            await message.reply("Hello there!")

    # Command decorator for pattern-based handling
    @OlvidClient.command(regexp_filter="^!ping")
    async def ping(self, message: datatypes.Message):
        await message.reply("pong!")

    @OlvidClient.command(regexp_filter="^!help")
    async def help(self, message: datatypes.Message):
        help_text = """
        Available commands:
        !ping - Test bot responsiveness
        !help - Show this message
        """
        await message.reply(help_text)

    @OlvidClient.command(regexp_filter="^!choose")
    async def choose(self, message: datatypes.Message, matched_body: str):
        import secrets
        choices = message.body.removeprefix(matched_body).strip().split()
        if choices:
            await message.reply(f"I chose: {secrets.choice(choices)}")
        else:
            await message.reply("Please provide options: !choose option1 option2")

# Run the bot
import asyncio
asyncio.run(ChatBot().run())
```

--------------------------------

### Configure Webhook Server Environment Variables

Source: https://github.com/olvid-io/olvid-bot-documentation/blob/main/examples/webhook-bot/README.md

Sets environment variables to configure the webhook server's host, port, and public URL. These settings are crucial for the bot to receive incoming requests and for generating accessible webhook URLs.

```shell
# ip address the webhook server listens on
WEBHOOK_SERVER_HOST=0.0.0.0
# port used by webhook server
WEBHOOK_SERVER_PORT=8080
# how to access your webhook server. This is used to send webhook url in olvid discussions.
WEBHOOK_PUBLIC_URL=http://localhost:${WEBHOOK_SERVER_PORT}
```

--------------------------------

### CLI: Message and Discussion Operations

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Commands for interacting with messages and discussions via the command-line interface. Supports sending text messages, listing and retrieving discussions, listing messages within a discussion, sending location data, and managing contact and group information.

```bash
# Send text message
olvid-cli -i 1 message send 1 "Hello from CLI!"

# Send message in interactive mode
1 > message send 1 "Hello World"

# List discussions with filtering
1 > discussion get
1 > discussion get -f id,title,lastMessageTimestamp

# Get specific discussion
1 > discussion get 1

# List messages in discussion
1 > message get --discussion 1

# Send location
1 > message location send 1 48.8566 2.3522

# Start location sharing (live location)
1 > message location start 1 48.8566 2.3522
# Update location
1 > message location update 1 48.8567 2.3523
# Stop sharing
1 > message location stop 1

# List contacts
1 > contact get

# List groups
1 > group get

# Create group
1 > group new "Team Chat" "Project discussion"
# Add members
1 > group invite <group_id> <contact_id>
```

--------------------------------

### Python Webhook Server Bot

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

A complete webhook server bot that accepts HTTP POST requests and forwards them as Olvid messages. It generates unique webhook URLs for each discussion and verifies incoming requests using a nonce. The bot also integrates with aiohttp for handling web requests.

```python
from olvid import OlvidClient, datatypes
from aiohttp import web
import asyncio
import secrets

class WebhookBot(OlvidClient):
    def __init__(self):
        super().__init__()
        self.app = web.Application()
        self.app.router.add_post('/webhook/{discussion_id}/{nonce}', self.handle_webhook)

    async def on_discussion_new(self, discussion: datatypes.Discussion):
        # Generate unique nonce for this discussion
        nonce = secrets.token_urlsafe(16)
        webhook_url = f"http://localhost:8080/webhook/{discussion.id}/{nonce}"

        # Store nonce in daemon storage
        await self.discussion_storage_set(
            key="webhook_nonce",
            value=nonce,
            discussion_id=discussion.id
        )

        # Send webhook URL to discussion
        await discussion.post_message(
            f"Your webhook URL:\n{webhook_url}\n\nSend POST requests to forward messages here."
        )

    async def handle_webhook(self, request):
        discussion_id = int(request.match_info['discussion_id'])
        nonce = request.match_info['nonce']

        # Verify nonce from storage
        stored_nonce = await self.discussion_storage_get(
            key="webhook_nonce",
            discussion_id=discussion_id
        )

        if nonce != stored_nonce:
            return web.Response(status=403, text="Invalid nonce")

        # Parse JSON payload
        try:
            data = await request.json()
            message_text = data.get('message', 'No message provided')
        except:
            return web.Response(status=400, text="Invalid JSON")

        # Send message to discussion
        await self.message_send(
            discussion_id=discussion_id,
            body=f"Webhook message:\n{message_text}"
        )

        return web.Response(text="Message sent")

    async def run_with_server(self):
        # Start HTTP server
        runner = web.AppRunner(self.app)
        await runner.setup()
        site = web.TCPSite(runner, 'localhost', 8080)
        await site.start()
        print("Webhook server running on http://localhost:8080")

        # Run bot
        await self.run()

# Run bot and HTTP server
bot = WebhookBot()
asyncio.run(bot.run_with_server())
```

--------------------------------

### Send Basic Text Message via cURL

Source: https://github.com/olvid-io/olvid-bot-documentation/blob/main/examples/webhook-bot/README.md

Sends a simple text message to the Olvid bot using a cURL POST request. This demonstrates basic interaction with the bot's webhook. Replace ${WEBHOOK_URL} with your actual webhook URL.

```shell
# send a basic text message
curl -X POST --data '{"text":"Hello Olvid !"}' ${WEBHOOK_URL}
```

--------------------------------

### Python Advanced Listeners with Filters

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Implement fine-grained control over notification handling using filters for specific senders, message content, and reaction states. This allows for targeted message processing based on defined criteria. The listener will stop processing after a specified number of matching messages.

```python
from olvid import OlvidClient, datatypes, listeners
import asyncio

async def listener_example():
    client = OlvidClient()

    # Handler function for filtered messages
    async def urgent_handler(message: datatypes.Message):
        print(f"URGENT: {message.body}")
        await message.reply("Urgent message received and logged")

    # Create filter for specific contact sending "urgent" messages
    message_filter = datatypes.MessageFilter(
        sender_contact_id=1,
        body_search="urgent",
        has_reaction=datatypes.MessageFilter_Reaction.NO_REACTION
    )

    # Create listener that handles only 5 matching messages
    listener = listeners.MessageReceivedListener(
        handler=urgent_handler,
        filter=message_filter,
        count=5  # Stop after 5 messages
    )

    client.add_listener(listener)
    await client.run()

asyncio.run(listener_example())
```

--------------------------------

### Send Message with Attachment via cURL

Source: https://github.com/olvid-io/olvid-bot-documentation/blob/main/examples/webhook-bot/README.md

Sends a text message with an attachment to the Olvid bot using a cURL POST request. The attachment payload is base64 encoded. Replace ${WEBHOOK_URL} with your actual webhook URL.

```shell
# send a text message with an attachment
curl -X POST --data '{"text":"Hello Olvid !","attachments":[{"payload":"VXNlIE9sdmlkICEK","filename":"olvid.txt"}]}' ${WEBHOOK_URL}
```

--------------------------------

### Python Ephemeral Messages

Source: https://context7.com/olvid-io/olvid-bot-documentation/llms.txt

Send self-destructing messages with configurable visibility duration, existence time, and read-once settings. These messages are automatically deleted after a specified period or upon being read, enhancing privacy. Supports sending ephemeral messages with attachments.

```python
from olvid import OlvidClient, datatypes
import asyncio

async def ephemeral_example():
    client = OlvidClient()

    # Create ephemeral message settings
    ephemerality = datatypes.MessageEphemerality(
        visibility_duration=10,   # Visible for 10 seconds after reading
        existence_duration=60,    # Deleted after 60 seconds total
        read_once=True           # Destroyed after first read
    )

    # Send ephemeral message
    message = await client.message_send(
        discussion_id=1,
        body="This is a secret message that will self-destruct",
        ephemerality=ephemerality
    )
    print(f"Sent ephemeral message {message.id}")

    # Ephemeral message with attachments
    with open("secret_document.pdf", "rb") as f:
        attachment_data = f.read()

    message = await client.message_send_with_attachments(
        discussion_id=1,
        body="Confidential file attached",
        attachments=[("secret_document.pdf", attachment_data)],
        ephemerality=ephemerality
    )

asyncio.run(ephemeral_example())
```