Nextcloud Talk#
How to let your team ask the OSPREY agent questions from a Nextcloud Talk room, and get answers, plots, and files back in the same room.
Before you start
A project whose build profile has a
dispatch:block — see Event Dispatch.Docker or Podman, for the container path.
A Nextcloud instance with the Talk app, and permission to create a user account on it.
Overview#
The bridge turns a Talk room into a way of talking to the agent. Someone mentions the bot in the room, the bridge hands that question to the event dispatch pipeline, and the answer is posted back as a reply in the room.
It is a poller, not a server: it asks Nextcloud for new messages and waits for them, making only outbound calls.
Like every bridge, it remembers each question and conversation. What is particular to Talk is that each room’s reading position is saved too, so messages posted while the bridge was down are picked up rather than missed.
The first time the bridge sees a room is the exception: it starts from the room as it stands at that moment and does not answer the backlog behind it. The anchor is saved immediately, so “first time” means once per room and not once per restart. Add the bot to a busy room and it joins the conversation from there, rather than replying to a month of history.
Enable It in a Profile#
Add a nextcloud_bridge: block to your build profile. Two settings: which
dispatcher trigger the bridge fires — that trigger decides what the agent is
allowed to do with a chat question — and whether the agent may @mention people:
nextcloud_bridge:
trigger: nextcloud-question # default; must exist in your triggers file
mentions: true # default; false posts @mentions as plain text
env:
required:
- NEXTCLOUD_BASE_URL
- NEXTCLOUD_BOT_ACCOUNT
- NEXTCLOUD_APP_PASSWORD
- NEXTCLOUD_ROOMS
Note
The bridge and the dispatch pair must sit on the same network. Workers go on
the host’s network whenever the agent has to reach a control system or a
co-deployed bridge at a loopback address (Network attachment: bridge or host),
and this bridge then has to move with them: add
services.nextcloud_bridge.network: host to your profile’s config:
block. osprey build refuses a split pair and names the key to change.
Rooms and credentials are not profile settings. They are runtime values you
supply, because they differ per deployment and the password must never be baked
into a build. Listing them under env.required documents them in
.env.example; fill the values into the profile’s .env, which is
where a secret survives a rebuild. The build derives the project’s .env
from it (created mode 0600, readable only by you).
Two mistakes are caught at build time rather than at runtime: declaring the
bridge without a dispatch: block, and naming a trigger that your triggers
file does not declare. Both fail the build with a message naming the problem,
instead of producing a project that deploys and then fails on every message.
Runtime settings#
Variable |
Meaning |
|---|---|
|
Your Nextcloud instance, with no trailing slash, e.g.
|
|
The Nextcloud user id the bridge signs in as — the account people mention to ask a question. |
|
An app password for that account (not the account’s login password). |
|
Comma-separated Talk room tokens to watch. A room’s token is the last
part of its URL: in |
|
The trigger to fire. Filled in for you from the profile block. |
|
Whether @mentions are on. Filled in for you from the profile block. |
|
The two shared secrets the bridge needs to reach the dispatcher and the worker, generated for you when unset — see Authentication. |
Optional settings you can usually leave alone
Variable |
Meaning |
|---|---|
|
Where the dispatcher and worker are. Filled in for you when they run in the same stack; when they run elsewhere you must set them, and the bridge refuses to start without them. |
|
How long the worker may spend on one run. Comes from your project configuration, so raising it raises it for both halves at once. |
|
How long the bridge waits for an answer before giving up on it. Defaults to 30 seconds more than the worker’s own limit, and may never be less than that limit — the bridge refuses to start if it is. |
|
Seconds between checks on an answer in progress (default 2). |
|
Seconds between sweeps of the queue of questions that could not be handed off yet (default 60). |
|
How long a failed hand-off is held before it is retried, so a brief outage has time to clear (default 20 minutes). |
|
Age at which a question that still cannot be handed off is abandoned (default 48 hours). |
|
Hard ceiling on how long anything may sit in that queue, whatever its state (default 7 days). |
|
Set to |
|
Longest earlier answer, in characters, sent back in full with a
follow-up (default 3000). A longer one is sent as its opening, and the
agent reads the rest only if it needs it. |
|
Optional alert host. With |
|
Where the bridge keeps what it remembers: the questions it has
answered and how far it has read in each room. Both default to files
under |
|
Timezone, taken from your project configuration so timestamps match the rest of the stack. |
Bring It Up#
1. Create the bot account. In Nextcloud, add a regular user for the agent to
speak as — the display name is what your team sees replying, so make it obvious
(for example OSPREY agent). Sign in as that user once, then create an app
password under Settings → Security. An app password can be revoked on its own
without disturbing the account, which is why the bridge uses one.
2. Invite it to the rooms it should serve. The bot only sees rooms it is a member of. Add it to each room you want served, and collect those rooms’ tokens.
3. Fill in the environment file. Set the four values from the table above in
the profile’s .env (the build derives the project’s .env from it):
NEXTCLOUD_BASE_URL=https://cloud.example.org
NEXTCLOUD_BOT_ACCOUNT=osprey-agent
NEXTCLOUD_APP_PASSWORD=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx
NEXTCLOUD_ROOMS=a1b2c3d4,e5f6g7h8
4. Bring the stack up. The bridge is registered in deployed_services, so
it starts with everything else:
osprey up # add --dev to bake in a local osprey checkout
Then mention the bot in one of the listed rooms and ask it something. If nothing happens, check the service’s logs first: a missing credential stops the bridge at startup with the missing variable named, rather than letting it run in a broken state.
Important
The bridge keeps what it remembers — which questions it has answered, recent
conversation, and each room’s reading position — in a named volume mounted at
/data. Do not remove that volume. Without it, a restart forgets everything
and the room’s history is either replayed from the beginning or skipped past.
Who Is in the Room, and @Mentions#
Each question reaches the agent with who asked it and who is in the room. The bridge reads the room’s participant list as the bot account, which is already a member, so there is no extra permission to grant. Signed-in users are listed by their Nextcloud display name; guests and users from other servers are not listed.
In a room with the lobby turned on, Nextcloud shows the list only to moderators. Make the bot account a moderator of that room, or its questions reach the agent with the asker only.
The agent may @mention a participant of the same room only when someone in the
room asks it to pass something on or to notify someone. It never does so on its
own. Anyone not in the room is written by name, as plain text, without an
@. Any other @name in an answer is posted without its @ too. Inside
code the @ is kept (so @dataclass survives) unless the word is a room
member’s user id, so the agent never notifies anyone outside these rules.
Set mentions: false in the profile block to have every mention posted as
plain text instead.