Bots the relay cannot read a word of

The model

A bot is a phone without a screen

The one thing to tell your users. End-to-end encryption to a bot is not privacy from the bot. A bot must read its own messages to work, so its operator reads everything sent to it and learns the sender's account identity. Encryption protects the channel from the relay and third parties — not from you, the operator. Signet shows a disclosure the first time a user opens a chat the client has flagged as a bot — which depends on that flag being set on their device, so treat it as a helpful default rather than a guarantee every user saw it. Say it yourself as well.

SDK reference

What you write against

The intended call surface. None of it is published yet; treat this as the contract being built toward, not an import you can add.

Call	What it does
Bot.connect(apiKey): Bot	Trade the sbk_ key for a session and bring up the crypto engine. On first run it bootstraps the bot's identity keys into your local store; on restart it re-attaches without re-bootstrapping.
bot.onMessage { msg -> … }	Every inbound text message. msg.from carries the sender's cert-verified identity and msg.text the plaintext.
bot.onCommand("weather") { msg, args -> … }	A /command. args is everything after the command token.
bot.onCallbackQuery { cbq -> … }	A tap on an inline-keyboard button. cbq.data is the opaque payload you set on the button; cbq.from is the verified tapper.
bot.sendMessage(chatId, text, replyMarkup? = null)	Send a message, optionally with an inline keyboard. Sealed 1:1 to the recipient.
bot.answerCallback(callbackId, text?, alert? = false)	Acknowledge a button tap — a quiet toast, or a modal alert.
bot.setMyCommands(commands)	Publish the bot's /command menu — clients show it as autocomplete in the composer.
bot.setMyProfile(name?, about?, avatar?)	Set the bot's display name, description, and avatar.

Delivery is long-poll by default. Opt into a webhook and the SDK decrypts on your host, then POSTs the already-plaintext Update to your own HTTPS endpoint — the relay never pushes, because it has nothing in the clear to push.

Three of these do not exist yet. There is no acknowledgement path for a button tap, so answerCallback has nothing to send — the shipped client debounces taps locally instead. There is no long-poll and no webhook: the reference host does a plain two-second poll of GET /v1/messages/pending. The two profile calls are real, but they land on one relay endpoint, and what they publish is stored in the clear — see Limits.

The Update object

Decrypted, delivered to your handler

{ "update_id": 10427, "message": { "message_id": "8f2c…", "from": { "id": "4417029", "verified": true }, // cert-verified — unspoofable "chat": { "id": "4417029", "type": "private" }, // or "group" "date": 1720613400, "text": "/weather Berlin", "entities": [ { "type": "bot_command", "offset": 0, "length": 8 } ] }, "callback_query": { // present INSTEAD of message on a button tap "id": "cbq_77f0", "from": { "id": "4417029", "verified": true }, "message_id": "…", "data": "vote:yes" // your opaque payload, echoed verbatim } }

from.verified is the sealed-sender identity, derived on-device from the sender's key — no field in the JSON can forge it. Attribute every side-effecting action to that identity, not to data.

Read that claim precisely. The sender certificate is signed by the relay's own key, so verified stops other users from impersonating each other — it does not defend against the relay operator, who is the signer. And this Update is an SDK-level object, not the wire: what actually travels inside the sealed ciphertext today are the envelopes bot_message, bot_callback and bot_meta, whose fields do not match the JSON above.

Keyboards & callbacks

Buttons under a bubble

Inline keyboards ride inside the encrypted message — the relay sees only ciphertext. A button has exactly one action:

Key	Button does
cb	Emits a callback_query with your opaque payload (≤64 bytes). Never parsed or run on the client — only echoed back to you.
u	An https:// url. Opened only through a confirm dialog that shows the full URL and warns it is operator-controlled.
cmd	Sends a /command on tap.

bot.sendMessage(chatId, "Confirm your subscription?", keyboard( row(button("Yes", cb="sub:yes"), button("No", cb="sub:no")), row(button("Open docs", url="https://signets.social/docs")), ))

Limits enforced on the client: ≤8 rows, ≤8 buttons per row, labels ≤64 chars. Unknown button types render as an inert chip, so older clients degrade cleanly.

Those limits are real and are enforced by the shipped app. The keyboard(), row() and button() helpers belong to the unpublished SDK; when a button carries more than one action key the client resolves it in the fixed order cb → u → cmd. What goes out on the wire, inside the ciphertext, is:

{"v":1,"ik":[[{"l":"Yes","cb":"sub:yes"},{"l":"No","cb":"sub:no"}]]}

HTTP endpoints

The relay surface

The SDK wraps these — you rarely call them directly. Registration and sessions are live; message send/receive reuses the standard sealed client protocol.

Endpoint	Who	Purpose	Status
POST /v1/bots	owner	Reserve @username + mint a provisioning ticket	live
POST /v1/accounts/bootstrap	SDK	Create the bot account with the ticket (keys stay on your host)	live
POST /v1/bots/session	SDK	Trade the sbk_ key for an access + refresh session	live
POST /v1/bots/{id}/token	owner	Regenerate the API key (old key + sessions revoked)	live
POST /v1/bots/{id}/revoke	owner	Kill the key and all live sessions, atomically	path wrong
POST /v1/messages · GET /pending	SDK	Sealed E2EE send / receive (shared with every client)	path short

Two rows above do not match the deployed router, and are left as written rather than quietly corrected. The kill switch is DELETE /v1/bots/{botAccountID}/token — there is no /revoke route at all, so that call 404s. And the receive path is GET /v1/messages/pending; GET /pending is shorthand, not a route.

Live on the relay, missing from the table

Endpoint	Who	Purpose	Status
POST /v1/bots/profile	bot	Publish display name, description and the /command menu	live
PUT /v1/bots/profile/avatar	bot	Upload the bot's one immutable avatar (raw bytes; type sniffed server-side)	live
GET /v1/discovery/bot-avatar/{ref}	anyone	Read that avatar by its random ref — never by account id	live
GET /b/{username}	anyone	Human-facing web preview of a bot, from its handle alone	live

The bot's verification tier — unverified · verified · official — is a signed claim inside its sealed-sender certificate, checked offline by every client, and a human account cannot fake bot-ness.

Who signs that claim matters. The certificate is signed by the relay, so the relay is precisely the party that could mint a false tier; the offline check defends against everyone else. And every bot bootstraps as unverified: there is no application, review or process today that moves a bot to verified or official. The profile card served over the web is always rendered unverified for exactly this reason.

Without varnish

What we promise, and what we don't

The same accounting the rest of this site uses, applied to bot traffic. Amber is unfinished work; green is something the server sees and always will.

Data	The relay	How exactly
Message text to your bot	does not see	sealed on device; the relay stores ciphertext
Files, images, voice notes	does not see	encrypted with the same session key as the text
Inline keyboards, callback payloads	does not see	they ride inside the encrypted message body
Your bot's private keys	never holds	generated on your host; the relay only ever saw a hash commitment
Phone number, email	does not exist	never collected at registration — not for people, not for bots
Google services	not involved	delivery is the app's own persistent WebSocket, no FCM
Who talks to your bot	can determine	the stored sender field is NULL on a sealed send, but the sender certificate travels readable by the relay in every build shipped today, and routing hints exist. The encrypted-certificate work is written and proven; it is not enabled on the deployed relay
The sender, at rest	not erased everywhere	the routing marker is purged only when a read receipt arrives — a delivery receipt does not clear it, and with read receipts switched off it survives the message’s whole retention. Copies outside the message row have their own lifetimes
Your bot's public profile	sees	name, description, command menu and avatar are stored in the clear, by design — they are discovery data shown before any chat exists
Connection IP	sees	unavoidable for any server. Host behind a VPN or Tor if that matters
When an account is online	partly	presence can be switched off; last-seen is coarsened to a minute

The five things to design around

• Content is always end-to-end encrypted. There is no non-encrypted path to a bot. The server-visible cloud-bot model was rejected on purpose.
• The operator reads what's sent. Stated above, and shown to every user in-app. Design for it: don't ask for secrets you don't need.
• The relay sees interaction metadata. It can observe that an account talks to your bot, and today it can work out which account. We minimize what is kept, but we do not hide it, and we will not claim the relay is blind to it.
• You hold the keys. Signet never generates or stores your bot's identity keys. Losing them means burning the bot and re-minting — not "recovering" it.
• Nobody outside has audited this. No external security review has ever been done on this code. The internal audits live in the repository, findings included.

Do not tell your users the relay cannot see who talks to your bot. That sentence is false on the relay that is running right now. There is a first-contact gate in the code intended to stop unsolicited messages, but it ships in shadow mode — it counts what it would have dropped and drops nothing — and it only ever binds accounts that opted into a contacts-only inbox, which is not the default. Assume a bot can reach anyone whose account id it knows, and say so if you are asked.