nuqloud-ai/docs/QUICK_START.md

Talk AI Quick Start

This guide gets a working Talk AI installation from source into Nextcloud.

1. Install And Build

Put the app into a Nextcloud apps directory:

cd /path/to/nextcloud/apps-extra
git clone https://github.com/EDUCAlliance/talk-ai.git educai
cd educai
npm ci
npm run build

Enable the app:

cd /path/to/nextcloud
sudo -u www-data php occ app:enable educai

Run upgrade if Nextcloud reports pending migrations:

sudo -u www-data php occ upgrade --no-interaction
sudo -u www-data php occ migrations:status educai

2. Configure The Admin Settings

Open Administration settings > Talk AI and configure the required model settings:

• Primary API Endpoint
• Primary API Key
• Default Model
• Webhook Secret

Optional settings you can add later:

• secondary endpoint and fallback model
• allowed model list for per-bot model selection
• RAG and embedding endpoint
• Docling document conversion
• vision and speech endpoints
• rate limits
• MCP tools

Save settings before testing Talk.

3. Register The Talk Bot

Talk AI tries to register the shared Talk AI Talk bot when the app is enabled and when settings change. Check registration with:

sudo -u www-data php occ talk:bot:list

If the bot is missing, register it manually:

sudo -u www-data php occ talk:bot:install \
  -f webhook,response \
  "Talk AI" \
  "your-webhook-secret" \
  "https://your-nextcloud.example/index.php/apps/educai/webhook/talk"

The webhook URL must include /index.php on installations that route apps through that path. Disabling and re-enabling the app also re-runs the automatic registration.

4. Create A Bot

Open the Talk AI app and create a bot:

• choose a bot name
• choose a Talk mention such as @supportbot
• write the system prompt
• choose visibility: personal, groups, teams, or global
• choose a model if per-bot model selection is enabled
• enable RAG, tools, or a personal wiki if needed

Shared bots may start as drafts or pending approvals depending on the user's scope rights.

5. Activate Talk AI In A Talk Room

Open a Talk conversation and activate the shared Talk AI bot from the room settings or Smart Picker flow.

Then mention your app-level bot:

@supportbot Can you summarize the project plan?

The shared Talk bot receives the webhook. Talk AI resolves @supportbot, checks access, runs the configured model and tools, and sends the answer back to Talk.

6. Check Logs

Watch Nextcloud logs while testing:

tail -f /path/to/nextcloud/data/nextcloud.log | grep -i educai

Common checks:

• talk:bot:list shows the shared Talk bot.
• The webhook URL contains /index.php when the installation needs it.
• The admin endpoint, key, and model are valid.
• The bot visibility allows the current user or room participants.
• Background jobs or cron.php run when testing RAG indexing.

See Troubleshooting for deeper debugging.