Talk beyond your own server.

before you start

What you need

• A Chirkle server on a public domain with HTTPS, for example one started with npx chirkle chat.example.com. Linking and the Telegram webhook only work over https:// on a public address.
• A superuser (admin) account. Create one with npx chirkle superuser upsert you@example.com <password>.
• The admin UI, at https://chat.example.com/_/. Everything below is done there, under Settings and Collections.

part 1 · linked instances

Link Chirkle servers together

Two or more Chirkle servers, paired by their admins, can share rooms and let their people write DMs to each other. Ann on a.example and Bob on b.example talk in one room, each signed in on their own server.

Every shared room has a home: the server it was created on. The other servers keep a copy of it. Messages, edits, replies, reactions and files go both ways. People from the other server show up under stand-in names with its label, like Ann (B). Nothing else is shared: collections, unread state, search, drafts and settings stay on each server.

Turn linking on (on each server)

1. Set the Application URL. In the admin UI, open Settings → Application and set Application URL to the server's public address, for example https://chat.example.com. The default http://localhost:8090 won't do.

   The address becomes part of the ids the other servers keep, so it can't be changed while any peer is listed. Pick the final domain first.

2. Tick federation. Open Collections → site, edit its one record and tick federation. Until it is ticked, the linking routes answer 404 and nothing is sent.

Pair two servers

1. Send a request from server A. On A, open Collections → fed_peers and add a row: B's address as origin (https://b.example) and a short label for B's people, up to 8 characters (for example B). Tick dms if A's people may write DMs to B's.
2. Accept it on server B. The request shows on B under fed_peers with status requested. B checks back with A that the request is real before it shows. B's admin sets the status to active, picks a label for A's people and, if wanted, ticks dms. Both rows become active.

• If B can't be reached, A keeps trying every minute. A request nobody accepts expires after 7 days.
• Deleting a pending request declines or withdraws it.
• If both admins add each other, the servers pair at once.

Share a room

1. Offer it from the room's home. On the server where the room lives, open Collections → fed_shares and add a row with the room and the peer.
2. Accept it on the other server. The other admin finds the offer under fed_shares and ticks accepted. The room appears there named after the original plus the label, like general (A), with its latest 200 messages. That admin may rename the copy.

Any room can be shared, whatever its access:

• Public rooms are seen by everyone signed in on either server.
• Private rooms stay members-only everywhere. On the home, the room's creator can add people from the other server by full address, like ann@b.example. On the copy, that server's admins add or remove their own people by editing the room's members in the admin UI.
• Open Air rooms stay readable without an account on every server.

DMs across servers

With dms ticked on both sides, people open New message and type the other person's address, like ann@b.example, as they would anyone's name at home.

Pause, unshare or unpair

• Stop sharing one room: delete its row under fed_shares on either side. The copy is archived: it keeps its history and becomes read-only.
• Pause a peer: set its status to suspended.
• Unpair: delete the peer's row under fed_peers. Shared copies are archived and DMs across become read-only. Pairing again starts fresh with a new secret.

part 2 · telegram bridge

Bridge Telegram groups

A Telegram bot of your own sits in your groups. Once a group is linked to a room, messages, replies, edits and files go both ways, and reactions too when the bot is a group admin. Telegram people show in the room under stand-in names like Lee Li (TG), with their names and pictures. The bot posts Chirkle messages to the group with the author's name in bold above them.

Set it up

1. Create a bot. In Telegram, talk to @BotFather, send /newbot and keep the token it gives you.
2. Turn privacy mode off. Still with @BotFather, send /setprivacy, choose your bot and pick Disable, so the bot sees all group messages, not only commands. If the bot is already in a group, remove it and add it again afterwards.
3. Give the token to your server and restart it. Set two environment variables:
   • TELEGRAM_BOT_TOKEN: the bot's token. Without it the bridge is off.
   • TELEGRAM_WEBHOOK_URL: https://<your domain>/api/telegram/webhook. Without it the bridge polls Telegram instead, which is meant for local development.

   # with npx
   $ TELEGRAM_BOT_TOKEN='123456:ABC…' \
     TELEGRAM_WEBHOOK_URL='https://chat.example.com/api/telegram/webhook' \
     npx chirkle chat.example.com
   
   # with Dokku
   $ dokku config:set chirkle \
       TELEGRAM_BOT_TOKEN='123456:ABC…' \
       TELEGRAM_WEBHOOK_URL='https://chat.example.com/api/telegram/webhook'

4. Add the bot to a Telegram group. A row for the group appears in the admin UI under Collections → tg_links, disabled and without a room.
5. Link the group to a room. Edit that row: pick the room and tick enabled. The room gets a notice that the Telegram group was connected. Send /chatid in the group at any time to see whether it is linked.
6. Optional: make the bot a group admin. Telegram tells only admins about reactions, so this brings reactions over in both directions.

Options

• Several groups per room. A room can be linked to more than one group. Each group's messages reach the others too.
• Anonymous reposts. Tick anonymous on a tg_links row to post the room's messages to that group without their authors' names. An anonymous room (ticked under Collections → rooms) also shows the room's name as the author in its linked groups.
• Channels. A Telegram channel links like a group. The bot must be one of its admins, with permission to post messages.
• Unlinking. Untick enabled, move the row to another room or delete it. Removing the bot from the group disables the link too. The room is told each time.

Good to know

• Telegram doesn't tell bots about deletes, so a message deleted in Telegram stays in the room. Deletes from Chirkle do reach Telegram.
• Bots can delete their own messages only for 48 hours. After that, a message deleted in Chirkle is edited to "Message deleted" in the group instead.
• Files up to 20 MB come over. Bigger files, animated stickers, locations, polls and the like arrive as a line of text saying what they were.
• Albums arrive as one message with up to 10 files. Long Telegram messages are split into several, since a Chirkle message holds 2,000 characters.
• Telegram people can't sign in as their stand-ins, and nobody can open a DM with them.

more detail

The full design of both features, including every edge case, is in the project's design notes (§26 for the Telegram bridge, §33 for linked instances) and in the README.