forked from NuQloud/nc-talk-ai
129 lines
4.6 KiB
Markdown
129 lines
4.6 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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"
|
|
```
|