Kanso Talk — installation and usage

The Nextcloud app kanso_talk connects Kanso cards with Nextcloud Talk threads.

What it does

In any personal or group Talk conversation, send:

/kanso https://cloud.example.com/apps/kanso/card/65

The app creates a thread in that conversation:

• the thread title is the card title;
• the first message:

  Parser
  
  <card description>
  
  https://cloud.example.com/apps/kanso/card/65
  

• the root message is authored by the person who sent the command.

From then on, every message in that thread is copied into the card's Discussion in Kanso:

• if the author may write to Kanso, the comment is created under their name;
• if the author is a guest, an external user, or a member without write access, the comment is created on behalf of the card owner (or board owner) with the real author marked at the top:

  **Jane Doe (Talk):**
  
  the message text
  

One card can be discussed in several conversations. The card's Discussion gets a separate top-level thread per conversation, named after it, so replies from different chats do not mix.

A Talk conversation has a wider audience than a board does, so only public cards are published by default. internal and private cards are refused with a notice; see the option below to override that for a single command.

Interface language

The messages the app posts into Talk — notices and failure explanations — are Russian, because that is the language of the people using it. The translations live in l10n/ru.json. Any other language falls back to English source strings, which is also why no English catalogue ships: in Nextcloud the source text is the English translation.

This README and the test report are in English.

To add another language, drop a <lang>.json next to ru.json; tests/unit.php checks that every translatable string in the code has a Russian entry, so copy its structure.

Package contents

dist/ is generated, not committed. Build it with ./build.sh; it produces:

• kanso_talk-<version>.zip — the app for installation (contains a kanso_talk/ folder);
• kanso_talk-<version>.tar.gz — the same archive in tar.gz;
• kanso_talk-<version>-delivery.zip — the app, the root *.md documents and SHA256SUMS.txt;
• SHA256SUMS.txt — checksums of the two app archives.

Only the kanso_talk folder is needed for installation. Keep l10n/ru.json inside it — without that file the interface falls back to English.

Building the package

./build.sh            # build dist/, then verify the checksums
./build.sh --check    # fail if dist/ does not match the working tree
./build.sh --verify   # re-verify SHA256SUMS.txt only

Requirements: bash and python3 (no zip binary needed). The version comes from <version> in appinfo/info.xml — bump it there and rebuild; the old archives are removed so a stale name cannot linger.

The archives are reproducible: entries are added in sorted order with one timestamp derived from the newest source file, so rebuilding an unchanged tree produces byte-identical files. Set SOURCE_DATE_EPOCH to pin that timestamp.

--check compares the archive against the tree byte for byte and also reports a delivery archive that references documents which no longer exist, so a renamed file cannot silently ship stale. Run it before tagging.

Requirements

• Nextcloud 35.x
• Nextcloud Talk 25.x (or newer — see the note below)
• Kanso 0.40.x (or newer — see the note below)
• PHP 8.2+

The app checks the Talk and Kanso versions. Below the minimum it logs an error and stays inert. Above the tested range it logs a warning and keeps working, so a Kanso minor release does not silently switch the bridge off.

Installation (without SSH)

1. Back up the database and the custom_apps directory.
2. Find the directory that holds the installed kanso app (on the server this is the same custom_apps that serves /custom_apps/kanso/js/...).
3. Upload the kanso_talk folder from the archive into it. The result must be kanso_talk/appinfo/info.xml — not an extra nested directory.
4. Set the owner and permissions to match the neighbouring apps:
   • owner — the web server user (www-data on a typical Ubuntu install);
   • directories 755, files 644.
5. Enable the app:
   • Settings → Apps → Your apps / Disabled apps → Kanso Talk → Enable;
   • or from the console: php occ app:enable kanso_talk (as the web server user).
6. Check that the migration created the tables:
   • oc_kanso_talk_links
   • oc_kanso_talk_messages

No board configuration is needed. The "Project chat" field in Kanso is not used.

Usage

Publishing

In a personal or group Talk conversation:

/kanso <card link>

Accepted link forms:

• https://cloud.example.com/apps/kanso/card/65 (deep link, preferred — it survives the login round-trip);
• https://cloud.example.com/apps/kanso/#/board/3/card/65 (hash route);
• /kanso 65 — the card id on this server.

Only links to the Kanso app on this server are accepted. A Deck link, or any other URL that merely contains /card/<n>, is rejected.

Options

Option	Meaning
--skip-visibility	Publish an internal or private card anyway. Without it, only public cards are published. It can be placed before or after the link.

Example:

/kanso --skip-visibility https://cloud.example.com/apps/kanso/card/65

Use it deliberately. Everything published is visible to everyone in the conversation: the card title, its description and every reply mirrored back into the card's discussion.

Replying

Reply inside the thread, not in the main conversation. Each reply becomes a Kanso comment under that conversation's anchor, with the Talk timestamp.

Replies are one level deep, matching Kanso's discussion structure.

When something fails

If a reply cannot be copied to the card, the conversation is told why, next to the message that failed: the card is gone, nobody in the conversation can write to it, or the discussion link could not be created. The reason is also in nextcloud.log.

Command-level problems (unknown link, card not accessible, already published, not public) are reported as a system notice in the conversation.

What is not synchronised

Version 1 is one-way from Talk to Kanso and covers new replies only:

• editing or deleting a Talk message does not change the Kanso comment;
• attachments are not copied — only the text;
• reactions are not synchronised;
• changes made in Kanso are not posted back into Talk.

Troubleshooting

/kanso does nothing at all. Check that the app is enabled, then look for kanso_talk lines in nextcloud.log. With Talk < 25 or Kanso < 0.40 the app logs an error and stays inert.

"The link does not point to a Kanso card on this server." The link must point at /apps/kanso on the same scheme, host and port as this Nextcloud instance. A link from another server is refused on purpose: card ids are only meaningful locally.

"Card not found, no access, or you cannot edit this Kanso board." You need read access to the card and the EDIT permission on its board.

Replies are not copied. Confirm the reply is inside the thread, not in the main conversation. Also check that the card still exists and that somebody in the conversation can write to it — the app now says so in the conversation when it cannot mirror a reply.

Uninstalling

occ app:disable kanso_talk (or disable it in the Apps screen). New replies stop being synchronised; existing Kanso comments, Talk threads and the two oc_kanso_talk_* tables stay as they are. Removing the folder afterwards leaves the tables in place.