nuqloud-ai/docs/NATIVE_INTEGRATION.md

Native Talk Integration

Talk AI can now receive bot invocations over Talk's native in-process event (OCA\Talk\Events\BotInvokeEvent, Talk 21+) instead of the signed webhook. Replies are posted by Talk itself after the invocation completes, so the app never makes an HTTP request back into its own instance for the normal reply path.

How it works

• A listener (lib/Listener/TalkNativeBotListener.php) is registered for BotInvokeEvent. It only acts on invocations addressed to the shared Talk AI bot (matched by the registered bot URL) and routes them through the same pipeline as the webhook (TalkHandler::handleMessage).
• Replies are delivered through a NativeEventResponseSink, which queues answers on the event (addAnswer()). Talk posts them as bot-authored messages after the invocation completes.
• Because native events are posted only after the invocation finishes, the pipeline coalesces streaming partials into a single final reply for the native path (the webhook path still streams).
• The shared Talk bot is registered with the event feature flag (4). Talk requires this feature to be used alone; it dispatches the in-process event instead of posting to the webhook URL.

Requirements

• Nextcloud Talk 21+ (the BotInvokeEvent class and the event feature flag). On older Talk the listener is a no-op and the webhook transport is used automatically.
• The shared Talk bot must be registered with the event feature. This happens automatically on app enable / settings save (see TalkBotRegistrationService), or manually with occ (below).

Staging install

1. Deploy the app into the staging Nextcloud apps directory and build the frontend:

   cd /path/to/nextcloud/apps-extra
   git clone <your-repo> educai
   cd educai
   npm ci && npm run build
   

2. Enable the app (runs migrations + repair steps, which re-register the shared Talk bot with the event feature):

   sudo -u www-data php occ app:enable educai
   

3. Configure under Administration settings → Talk AI:

   • Primary API endpoint + API key (any OpenAI-compatible provider)
   • A default model (or allowed model list)
   • Webhook secret (openssl rand -hex 32)

   Saving the settings triggers bot registration.

4. Verify the bot registration has the event feature:

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

   You should see the Talk AI bot with state = 1 and features webhook, response, event.

   If your environment blocks automatic registration, register manually:

   sudo -u www-data php occ talk:bot:uninstall "Talk AI"
   sudo -u www-data php occ talk:bot:install \
     -f event \
     "Talk AI" \
     "YOUR_WEBHOOK_SECRET" \
     "https://cloud.example.com/index.php/apps/educai/webhook/talk"
   

5. Activate the bot in a Talk room (conversation settings → "Talk AI" → activate), create a bot in the Talk AI app, and mention it.

Confirming the native path is active

Watch the log while mentioning the bot:

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

A native invocation logs:

EducAI: Native Talk bot invocation received
Extracted Talk message data (room_token: "xxx", ...)
Bot detected (bot_id: 1, mention_name: @mybot)
Calling LLM API

and the reply appears as a bot-authored message without a Successfully sent reply to Talk HTTP log line (that line is the webhook transport). If you instead see ========== Talk AI Webhook Received ========== the invocation arrived over the webhook (e.g. the event flag is not set, or Talk is older than 21).

Notes / trade-offs

• Synchronous processing. Native events are dispatched within the request that sends the chat message, so the LLM call runs in that request's context. This is Talk's native behaviour; for very slow models the sender's request will wait. The webhook transport has the same characteristic (the webhook POST blocks until processing finishes).

• No streaming over native. Replies are coalesced to a single final message (Talk posts answers after the invocation completes). The webhook transport still streams partials.

• Out-of-context replies (rate-limit queue, test rooms) still use the signed Talk bot HTTP API, since no native event is in flight for those.

• Rollback. To revert to webhook-only, re-register the bot without the event flag:

  sudo -u www-data php occ talk:bot:uninstall "Talk AI"
  sudo -u www-data php occ talk:bot:install \
    -f webhook,response \
    "Talk AI" \
    "YOUR_WEBHOOK_SECRET" \
    "https://cloud.example.com/index.php/apps/educai/webhook/talk"