Telegram

The simplest channel: a free bot from @BotFather, one token, no public address, no cost. Use it as the company bot on your organisation server, or just for you on your own PC.

Telegram: your own bot talks to your PC or to your organisation’s server; nothing passes through SphereHarness.

Which one? See WhatsApp and Telegram: two modes. The channel setup dialog (status window → Company channels → Telegram → Set up…, or ask the chat “set up Telegram”) asks “Who is this for?” first.

Create the bot (both modes)

  1. In your Telegram app open @BotFather (blue tick) and send /newbot.
  2. Choose a display name and a username ending in bot.
  3. BotFather replies with the bot token, shaped <digits>:<about 35 characters>. Treat it like a password: type it only into the dialog's password box, never into the chat.

The assistant guides these steps in words — they happen in your Telegram, not in a browser.

The company bot on your organisation server Tenant admin

The organisation server is the one place that fetches the company bot's messages (long polling — no public address, no tunnel). It routes each message by the sender's Telegram user id to the PC that person paired; that PC collects it over the connection it already has to the organisation server (no inbound port on any PC), and the server sends the answer back. The token exists once, on the organisation server, encrypted. Nothing passes through SphereHarness.

Administrator: once

  1. In the dialog choose Organisation - one bot for everyone, run on our organisation server (the administrator signs in first in Settings → Organisation → Sign in as administrator — the dialog links there; saving is a licensed write under the Tenant Admin licence).
  2. Type the token into the password box. It is sent once to the organisation server over HTTPS and stored there encrypted. On a plain-http organisation server the dialog shows the line to run on the server instead: install-organisation-server.ps1 -TelegramBotToken (typed hidden).
  3. Save. The server starts fetching the bot and restarts when the token changes. The checklist ends “Members: nothing to install - each PC pairs once from Settings → Organisation”.
One bot, one poller. Never use the company token on a PC as a personal bot, on a second server, or with a webhook: Telegram gives each message to only one of them (409 Conflict) and messages go missing. The personal dialog refuses the company token.

Each person: pair once

  1. Settings → Organisation → Company channels shows “/start ABC123 to @bot in Telegram” (6 characters, 15 minutes, 5 tries).
  2. Open the company bot in Telegram and send /start ABC123.
  3. The bot answers “Connected: your messages now reach PcName.”

Before you pair: “Open Settings → Organisation on your SphereHarness PC and send me the code shown there.” Your PC off: “Your PC NAME is not reachable right now (last seen when). Start SphereHarness on it and send your message again.” Licence expired: the reply names the expired licence; your pairing is kept.

Just me: your own bot on your own PC

The desktop agent fetches your own bot's messages itself — no webhook, no public address, no server.

  1. In the dialog choose Just me; type the token into the password box (stored encrypted for your Windows user). A token that is already your company's bot is refused.
  2. Pair — only you. The dialog shows a pairing code. Send /start ABC123 to your bot: your Telegram user id becomes the only allowed sender. A plain /start gets “Open the SphereHarness dialog on your PC and send /start <code>.”; everyone else is refused.
  3. Send a message — it runs on this PC. Try what CAD sessions are open? and take a screenshot of NX (the screenshot arrives as a photo).

Older setups kept the token in plain text in messaging_settings.json; on the next start it moves into encrypted storage. If your company runs a company bot, you may still choose Just me unless the administrator switched that off; one binding per channel per PC.

Using it

One conversation with your PC (1.3.7): a message from you — the account holder (with your own bot, the Telegram user id paired by /start <code>; with the company bot, the person paired to this PC) — continues the conversation in the SphereHarness chat on that PC, exactly as if you had typed it there: the same AI session and history, your saved memories, the CAD session chosen in the chat’s Target box, the same model and the same commands. Your message appears in the chat on the PC marked [from Telegram], and the answer is shown there and sent back to Telegram, as complete as in the chat (only what Telegram cannot show — tables, code blocks, diagrams, Markdown — is left out). A message sent while an answer is still running is passed into it, like typing in the chat; /stop stops the running answer at once (and everything it started), /pause pauses it (it saves and says what was left), a long request sends its checkpoint lines here and continues by itself, /clear starts the conversation over (on the PC too), and /unattended always / /unattended off switch unattended mode on that PC (shown in its chat and written to its unattended log). Approvals are asked in the chat on the PC, as always — nothing is approved for you. Anybody else you allowed keeps a conversation of their own and cannot switch unattended mode.

Photos, files and voice messages (1.3.7): send them to the bot and they reach the chat on your PC like a file you attach there (up to 5 per message, 10 MB each, 20 MB together; anything over is named in the message instead; a photo’s caption is the message). They are fetched with the bot’s own token — on your PC for your own bot, on the organisation server for the company bot — in memory only, and only from the account holder. A voice message is turned into text on your PC, with the speech-to-text you chose for the chat’s microphone, and sent as your message; the answer starts with “🎤 Heard: …”.

Troubleshooting

SymptomCause and fix
Some messages answered, others lost; 409 Conflict in a logThe same token is fetched by two places (a PC and the organisation server, two PCs, a script, a webhook). One bot per place; getWebhookInfo must show an empty url
“Open Settings → Organisation … send me the code”Not paired: send /start <code>
“That code is not valid…”Expired (15 min), mistyped or 5 tries used: a fresh code from Settings → Organisation
“Open the SphereHarness dialog on your PC and send /start <code>.”Personal bot: you sent /start without the code
“Your PC … is not reachable right now”Start SphereHarness; check Settings → Organisation → Test
Nothing at allToken revoked (BotFather /token gives a new one), the messaging service is off, or — with a coding agent on your own account and no API key — Telegram is off until you allow it in Settings → Channels

Related