use-channels

Informational, not binding. Know a better way for the case in front of you — do it your way and say so. You are trusted with the creative work on this project.

The door and the credential are in use-data; reached at /service/channels/* through dataFetch.

1. 🔒 One reader, and it is not you

Telegram gives each incoming update to whoever asks for it first, and to nobody else. Two pollers means the messages split between them at random — the bot answers every other question and looks broken in a way no log explains.

That is why one process owns the bot and everyone else asks IT over the loopback. Never install a Telegram client in this app, never poll getUpdates, never register a webhook of your own for the owner's bot. ✗ that trap already cost this project a day.

2. The whole surface — four routes, and all four are CONTROL

status is the honest first call: configured: false means the owner has not set a bot up, and that is a normal state, not a fault to hide. Show it as "not connected", never as an error.

3. Three MORE routes exist — outbound and inbound (corrected 2026-08-25)

🪦 This section used to say "impossible from your app: there is no outbound route", and that was FALSE. It described the service as it stood on 2026-08-23; sending was added afterwards and the text was never corrected. ✗ Found by a guest agent reading the service's own source while the skill told him the opposite — a wrong law is more dangerous than a missing one, and this one sat exactly where somebody was building.

Verified in services/channels/server.js on 2026-08-25, by line:

🔒 The token never leaves the service. Your app hands over text or bytes; the credential stays on :3500. That is the whole reason these routes exist rather than a Telegram client in your slot (§1).

3b. The four doors this project already owns (added 2026-09-01, step 77)

The setup screens are inside this repository now, and so are their doors. Do not write a fifth one — call these, or add a section to the entry that already exists.

🔒 All four check ARCHITECT_LAYER_ROLES themselves, and all four are thin on purpose: the rules live in the service, and a second copy of them here would diverge on the service's first change. 🔒 available: false is a NORMAL state, not a fault — on the owner's laptop the channel service is not running at all. Say so in words; never render it as an error.

3a. 🔒 What is genuinely NOT there — check before you promise

These are gaps in the product, and a promise made over them is one the platform will not keep.

🪦 TWO ROWS OF THIS TABLE WERE FALSE AND ARE REMOVED (2026-09-01, step 77-6). They said there is no push into your project and that a voice note is dropped silently. Both were checked against services/channels/server.js line by line while writing the bot's own description page, and both are the opposite of what the code does:

🔒 THIS IS THE SECOND TIME THIS EXACT SECTION LIED, AND THAT IS THE LESSON. It already carries a 🪦 from 2026-08-25 for the same kind of error. A capability list written by hand goes stale the day the platform ships something, and nothing wakes it up — so read the service before you promise anything from this table, and treat every row as a claim with an address, not as a law.

✗ A stale law is more dangerous than a missing one. Both removed rows would have made you either build a workaround for something that already works, or tell the owner the product cannot do what it has been doing for weeks.

When one of these is asked for, the honest answer is not "I will build it". Name exactly which is missing, say it is a change in the channel service — platform, not your slot — and hand it over the way CLAUDE.md describes. Then build everything around it that does not depend on it.

4. 🔒 Linking is a handshake, and the human moves first

The code is issued, the owner opens the deep link and presses Start in Telegram, and only then does the chat id exist. Your page polls until it appears, with a visible "waiting" state — and the code expires, so a page that waits forever is wrong.

🪦 "YOU NEVER ASK A PERSON FOR A BOT TOKEN IN THE PRODUCT'S OWN FORM" — REPEALED 2026-09-01 (step 77). That line stood here, and it was right while it stood: there was no place in the project built to hold a credential, so the panel was the only honest answer.

🔒 THE NEW CONDITION, AND IT IS A CONDITION, NOT A PERMISSION. The token is now typed at /{lang}/architect/telegram?section=settings — the architect layer, behind ARCHITECT_LAYER_ROLES, which the door checks itself and not only the page. It leaves the browser by XHR and passes straight through to the channel service: it is never written into a file of this repository, never logged, never returned in a response. /status answers configured: true|false and never the value, so there is nothing to mask and nothing to leak.

What is still forbidden, and this half did not change: a token field on a PUBLIC page, in a product form, or behind any weaker gate than the architect layer; storing it in APP-CONFIG, .env.local or a table of your own; printing it while debugging. A credential asked for in a place that was not built to hold one is exactly the defect the old rule was protecting against — the place was built, the defect was not repealed.

5. What the bot already is

A mouth for the knowledge base: a question in Telegram is passed to the graph (use-agentic-rag) and the answer is repeated back. When the base is switched off or empty it says so plainly rather than inventing an answer.

So "let people ask our documents from Telegram" is mostly a matter of loading the documents, not of writing a bot — and improving the ANSWERS means working on the knowledge base, not on the channel.

6. The shape is channel-agnostic on purpose

The service is written so that WhatsApp, email or a web widget become a second entry in the same config rather than a second service. Another channel is a platform change — name it and hand it over (use-data §5); do not grow a parallel messenger inside the app.

7. Before you call it done

1. status was read first, and the "not connected" path exists in the product, in the user's language.
2. Nothing in this app polls Telegram or holds the bot token.
3. The linking page shows waiting, success and expiry — the human is the slow part of that handshake.
4. Anything from §3 that the owner wanted was named out loud as missing, not quietly worked around.
5. If the answers are poor, you said so about the knowledge base — the channel only carries them.