Bots für HideChat

Stand: 10. November 2026 · Schnittstelle Version 1 (Text, Befehle, Medien, Knöpfe, Tastaturen, Umfragen, Bearbeiten, Löschen, Reaktionen, Gruppen, Räume und Kanäle, Inline-Modus, Mini-Apps, Bot-Verzeichnis, Bewertungen und Statistik; neu: SDK für JavaScript und Python, Ende-zu-Ende-Modus)

Kurz gesagt: Du legst Deinen Bot im Chat mit @botwerkstatt an und bekommst einen Schlüssel. Mit dem Schlüssel holst Du Ereignisse ab (oder bekommst sie per Webhook) und schickst Antworten über eine einfache HTTPS-Schnittstelle mit JSON.

Wichtig zu wissen: Gehostete Bots können die Nachrichten lesen, die Personen ihnen schicken. In der App steht deshalb in jedem Bot-Chat: «Bot · Der Betreiber kann Nachrichten in diesem Chat lesen.» Das gilt auch für Dich als Betreiber: Gehe sorgfältig mit diesen Nachrichten um, siehe Bot-Nutzungsbedingungen.

Neu: Mit dem SDK für JavaScript und Python geht es schneller, und im Ende-zu-Ende-Modus kann HideChat die Nachrichten an Deinen Bot nicht mehr lesen. Dann steht im Bot-Chat: «Bot · Ende-zu-Ende verschlüsselt. Nur der Betreiber kann mitlesen, HideChat nicht.»

Einstieg in 5 Minuten

1. Bot anlegen

Öffne in der HideChat-App den Chat mit @botwerkstatt (Bot-Werkstatt, mit Haken «offiziell») und schreib /neuerbot. Die Werkstatt fragt Dich nach einem Anzeigenamen und einem Benutzernamen. Der Benutzername hat 3 bis 20 Zeichen (a–z, 0–9, _, .) und muss auf bot enden, zum Beispiel wetterbot. Namen mit hidechat, support, official, offiziell, admin oder werkstatt sind reserviert.

2. Schlüssel kopieren

Am Ende schickt Dir die Werkstatt Deinen Schlüssel. Er sieht so aus: hcbot_wetterbot_<43 Zeichen>. HideChat speichert nur einen Hash davon, ein verlorener Schlüssel lässt sich also nicht anzeigen. Mit /schluessel wetterbot stellt die Werkstatt einen neuen aus; der alte ist dann ungültig (spätestens nach 5 Sekunden). Die Nachricht mit dem Schlüssel löscht sich nach 24 Stunden selbst, kopier ihn also gleich. Behandle den Schlüssel wie ein Passwort: nie in Code-Repositories, nie in Chats, nie in einer Adresse. Er gehört in den Kopf Authorization (oder in eine Umgebungsvariable):

export HC_TOKEN="hcbot_wetterbot_..."

3. Wer bin ich? (me)

curl -s https://relay.hidechat.app/bot/v1/me \
  -H "Authorization: Bearer $HC_TOKEN"
{ "ok": true, "result": { "username": "wetterbot", "name": "Wetter", "about": "", "commands": [], "webhook": null, "link": "https://hidechat.app/b/wetterbot" } }

4. Ereignisse abholen (updates)

Öffne in der App Deinen Bot (Adresse https://hidechat.app/b/wetterbot) und tippe auf Starten. Erst dann kann Dein Bot dieser Person schreiben. Hole das Ereignis ab:

curl -s "https://relay.hidechat.app/bot/v1/updates?after=0&wait=25" \
  -H "Authorization: Bearer $HC_TOKEN"
{ "ok": true, "result": [
  { "id": 1, "type": "start", "chat": "marcel", "at": 1794470000000 }
] }

Mit wait (bis 30 Sekunden) wartet die Anfrage, bis ein Ereignis eintrifft. Merke Dir die höchste id und frage beim nächsten Mal mit after=<id> weiter.

5. Antworten (send)

curl -s https://relay.hidechat.app/bot/v1/send \
  -H "Authorization: Bearer $HC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chat":"marcel","text":"Hallo! Ich bin Dein Wetterbot."}'
{ "ok": true, "result": { "mid": "k3J9x..." } }

6. Lieber Webhook statt Abholen (setWebhook)

Wenn Dein Bot einen öffentlich erreichbaren HTTPS-Server hat, lass Dir die Ereignisse zustellen:

curl -s https://relay.hidechat.app/bot/v1/setWebhook \
  -H "Authorization: Bearer $HC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://bot.example.com/hidechat"}'
{ "ok": true, "result": { "secret": "..." } }

Das secret siehst Du nur in dieser Antwort. Speichere es sicher; Du brauchst es, um die Signatur zu prüfen.

Methoden

Alle Methoden liegen unter https://relay.hidechat.app/bot/v1/<methode>. Der Schlüssel steht im Kopf Authorization: Bearer hcbot_…. me, updates und file gehen mit GET (Parameter in der Adresse) oder POST (JSON), alle anderen nur mit POST und einem JSON-Objekt als Inhalt (höchstens 100 000 Zeichen). Ausnahme: sendMedia nimmt multipart/form-data (siehe Medien), und file liefert bei Erfolg die Datei selbst statt JSON. Jede Antwort ist JSON: { "ok": true, "result": … } oder { "ok": false, "error": "…", "hint": "…" }.

MethodeParameterErgebnis (result)
mekeineusername, name, about, commands, webhook (Adresse oder null), link (https://hidechat.app/b/<botname>, siehe Links), mode (hosted oder e2e, siehe Ende-zu-Ende), inline (Platzhalter oder null), miniapp (Adresse oder null)
updatesafter (Zahl ab 0, Standard 0), wait (0 bis 30 Sekunden, Standard 0)Liste von Ereignissen mit id grösser als after, höchstens 100, älteste zuerst. Mit gesetztem Webhook: Fehler webhook_active.
setWebhookurl (nur https://, höchstens 512 Zeichen)secret (neu bei jedem Aufruf; das alte ist sofort ungültig). Zugestellt werden Ereignisse ab diesem Zeitpunkt.
deleteWebhookkeinetrue. Danach funktioniert updates wieder.
sendchat (Benutzername der Person, g:<id> oder s:<id>, siehe Gruppen), text (1 bis 4000 Zeichen), reply_to (optional, mid einer Nachricht), buttons (optional, siehe Knöpfe), keyboard (optional, Antwort-Tastatur), remove_keyboard (optional, true entfernt die Tastatur). null bei buttons oder keyboard gilt als weggelassen. In Räumen zusätzlich topic (Nummer des Themas, 0 = Allgemein).mid der gesendeten Nachricht (in Räumen die Beitragsnummer als Text). Im Einzelchat nur an Personen, die den Bot gestartet und nicht gestoppt haben.
sendMediamultipart/form-data mit chat, kind (photo, video, voice oder file), file (die Datei) und optional caption (höchstens 1024 Zeichen), reply_to, buttons (JSON-Text), w, h, dur (Zahlen ab 0: Breite und Höhe werden auf 1 bis 20 000 begrenzt, Dauer in Sekunden auf höchstens 86 400). Siehe Medien.mid der gesendeten Nachricht
editchat, mid, text (optional, 1 bis 4000 Zeichen), buttons (optional); mindestens eines von beiden. Siehe Bearbeiten.true
deletechat, mids (Liste mit 1 bis 100 Nachrichten-IDs){ "deleted": <Anzahl> }
reactchat, mid, emoji (eines von ❤️ 👍 😂 😮 😢 🔥, oder null zum Entfernen)true
typingchat, action (typing, recording oder uploading)true. Siehe Tippt ….
chatInfochatIm Einzelchat { chat, type: "private", username }, aber nur, wenn die Person den Bot gestartet hat (sonst 403 not_started). In Gruppen (g:<gid>) { chat, type: "group", title, members: <Anzahl>, admins: [Benutzernamen] }. In Räumen und Kanälen (s:<id>) { chat, type: "room" oder "channel", title, handle, members: <Anzahl>, role } (role ist die Rolle des Bots: Mitglied oder Admin).
memberschat (Gruppe oder Raum)Mitgliederliste [{ user, admin, bot }] (in Räumen höchstens die ersten 100; in einem Kanal nur, wenn der Bot dort Admin ist, sonst 403 forbidden). Im Einzelchat nicht vorhanden (400 unsupported_chat).
leavechat (Gruppe oder Raum)true. Der Bot verlässt die Gruppe oder den Raum, danach Ereignis removed_from_group ohne from. Im Einzelchat nicht vorhanden (400 unsupported_chat).
answerButtonbutton_id (aus dem button-Ereignis), text (optional, höchstens 200 Zeichen), alert (optional, true/false)true. Einmal pro Knopfdruck, höchstens 15 Minuten danach.
sendPollchat, question (1 bis 300 Zeichen), options (2 bis 10 Einträge zu je 1 bis 100 Zeichen); Frage und Antworten nicht nur aus Leerzeichen, multi (optional, true = mehrere Antworten)mid der Umfrage
closePollchat, mid der eigenen Umfragetrue. Ein zweiter Aufruf für dieselbe Umfrage ist erlaubt und ändert nichts.
filefile_id (aus dem Feld media eines message-Ereignisses)Die entschlüsselte Datei als Rohdaten (nicht JSON). Zählt zum Limit von 30 pro Sekunde pro Bot. Siehe Medien.
setCommandscommands: Liste von { "cmd": "wetter", "desc": "Wetter anzeigen" }; höchstens 30, cmd aus a–z, 0–9, _ (1 bis 32 Zeichen, ohne /), desc höchstens 80 Zeichen. Ersetzt die ganze Liste.true. Die Befehle erscheinen im Bot-Profil und als Vorschläge beim Tippen von /.
setProfilename (höchstens 40 Zeichen), about (höchstens 300), welcome (höchstens 500), groups (true/false: «In Gruppen erlaubt», siehe Gruppen), inline (Platzhalter von 1 bis 64 Zeichen oder null = Inline-Modus aus), miniapp (https-Adresse oder null), privacy (https-Adresse Deiner Datenschutzerklärung, höchstens 512 Zeichen, oder null; Pflicht fürs Bot-Verzeichnis); nur die Felder, die Du ändern willsttrue
answerInlineinline_id (aus dem inline_query-Ereignis), results (höchstens 20 Ergebnisse mit id, title, text, optional description), next_offset (optional, höchstens 64 Zeichen)true. Einmal pro Anfrage und nur innert 30 Sekunden; die Person bekommt die Ergebnisse, auch wenn sie den Bot nie gestartet hat.
checkWebAppDatainit (die Startdaten, die Deine Mini-App bekommen hat){ bot, user, lang, theme, at }, plus name, falls bekannt
endChatchat (Benutzername der Person)true. Die Person gilt danach als gestoppt (zählt als Stopp); Dein Bot kann ihr erst wieder schreiben, wenn sie ihn neu startet. Hat sie ihn nicht gestartet: true ohne Wirkung. Nur Einzelchats (sonst 400 unsupported_chat).
setE2ebox_pub, sign_pub (je 32 Byte, Base64), proof (Ed25519-Signatur von hidechat-bot-e2e:<bot>:<box_pub>:<sign_pub> mit dem neuen Signierschlüssel, Base64). Am einfachsten mit dem SDK (hidechat-bot register).{ mode: "pending", fingerprint }: Antrag auf den Ende-zu-Ende-Modus, wirksam erst nach Bestätigung durch den Besitzer in der App. Mit genau den schon bestätigten Schlüsseln: { mode: "e2e", fingerprint }.
setHostedkeineImmer 403 owner_only: Zurück auf gehostet stellt nur der Besitzer um, in «Meine Bots» oder mit /modus <bot> gehostet in der Bot-Werkstatt (siehe Ende-zu-Ende).

Der Benutzername, das Löschen und neue Schlüssel laufen über die Bot-Werkstatt, nicht über die Schnittstelle. Weitere Werkstatt-Befehle: /meinebots, /beschreibung, /willkommen, /befehle, /datenschutz, /verzeichnis, /statistik (siehe Bot-Verzeichnis), /baukasten (siehe Baukasten), /modus (Betriebsart, siehe Ende-zu-Ende), /loeschen (mit Rückfrage; der Benutzername bleibt danach 30 Tage gesperrt) und /abbrechen.

Knöpfe und Tastatur

Mit send (auch sendMedia und edit) hängst Du Knöpfe unter eine Nachricht. buttons ist eine Liste von Reihen, jede Reihe eine Liste von Knöpfen: höchstens 8 Reihen mit je 1 bis 4 Knöpfen. Jeder Knopf hat einen text (1 bis 40 Zeichen, eine Zeile, ohne unsichtbare Zeichen) und genau eines von:

Ältere App-Versionen: Apps vor dieser Aktualisierung kennen die Knopfarten webapp und inline nicht und zeigen die ganze Nachricht nur als Rückfalltext, sobald sie einen solchen Knopf enthält (ohne Medien, Umfrage, Tastatur und die übrigen Knöpfe). Schick Nachrichten mit webapp- oder inline-Knöpfen deshalb am besten in einer eigenen Nachricht, ohne Medien oder Umfrage. Neuere Apps lassen unbekannte oder ungültige einzelne Knöpfe weg und zeigen den Rest.

curl -s https://relay.hidechat.app/bot/v1/send \
  -H "Authorization: Bearer $HC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chat":"marcel","text":"Wie war Dein Tag?","buttons":[
        [{"text":"Gut","data":"gut"},{"text":"Mies","data":"mies"}],
        [{"text":"Mehr erfahren","url":"https://example.com/info"}]]}'

Auf einen Knopfdruck antworten. Der Druck kommt als button-Ereignis mit mid (Deine Nachricht), data und button_id. Antworte mit answerButton. Ohne text endet nur der Ladekreis in der App; mit text erscheint er kurz als Hinweis, mit alert: true als Dialog mit dem Namen Deines Bots als Titel.

curl -s https://relay.hidechat.app/bot/v1/answerButton \
  -H "Authorization: Bearer $HC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"button_id":"<button_id>","text":"Danke, gespeichert."}'

Antwort-Tastatur

Mit keyboard zeigt die App unter dem Eingabefeld Antwort-Knöpfe. Ein Tipp darauf schickt die Beschriftung als normale Textnachricht an Deinen Bot (Ereignis message, bei einem Text mit / am Anfang command).

"keyboard": { "rows": [["Pizza", "Pasta"], ["Salat"]], "once": true, "hint": "Wähle Dein Essen" }

rows: 1 bis 8 Reihen mit je 1 bis 4 Beschriftungen (1 bis 40 Zeichen, eine Zeile). once (optional): die Tastatur verschwindet nach der ersten Auswahl. hint (optional, höchstens 64 Zeichen, eine Zeile, ohne unsichtbare Zeichen): Platzhalter im Eingabefeld. Die Tastatur bleibt, bis Du eine neue sendest oder sie mit "remove_keyboard": true bei send entfernst ("keyboard": null gilt als weggelassen und entfernt sie nicht). edit hat kein keyboard-Feld und lässt die Tastatur unverändert.

Medien

sendMedia schickt ein Foto, Video, eine Sprachnachricht oder eine Datei. Die Anfrage ist multipart/form-data, am einfachsten mit curl -F:

curl -s https://relay.hidechat.app/bot/v1/sendMedia \
  -H "Authorization: Bearer $HC_TOKEN" \
  -F chat=marcel \
  -F kind=photo \
  -F caption="Dein Wetterbild" \
  -F "file=@wetter.png;type=image/png"
{ "ok": true, "result": { "mid": "k3J9x..." } }
kindErlaubte Typen (Content-Type des Teils file)
photoimage/jpeg, image/png, image/webp, image/gif; der Inhalt muss zum Typ passen
videovideo/mp4, video/quicktime
voiceaudio/mp4, audio/m4a, audio/aac, audio/mpeg, audio/ogg, audio/webm
filebeliebiger Typ (höchstens 120 Zeichen); der Dateiname ist Pflicht (höchstens 200 Zeichen, eine Zeile, ohne unsichtbare Zeichen)

Medien empfangen

Schickt eine Person Deinem Bot ein Foto, Video, eine Sprachnachricht oder eine Datei, bekommst Du ein message-Ereignis mit dem Feld media (text ist der Bildtext und kann leer sein):

{ "id": 12, "type": "message", "chat": "marcel", "at": 1794470123456, "text": "", "mid": "q8Hn...",
  "media": { "file_id": "Zk3...", "kind": "image", "mime": "image/jpeg", "size": 48213, "w": 1080, "h": 1920 } }

kind ist image, video, audio oder file; je nach Datei kommen name, w, h und dur dazu. Die Datei holst Du entschlüsselt mit file:

curl -s "https://relay.hidechat.app/bot/v1/file?file_id=Zk3..." \
  -H "Authorization: Bearer $HC_TOKEN" \
  -o foto.jpg

Die Antwort sind die Rohdaten der Datei mit ihrem Content-Type (und Content-Disposition: attachment). Bei einer unbekannten oder abgelaufenen file_id (älter als 7 Tage) bekommst Du 404 no_file als JSON.

Einmal ansehen: Medien, die eine Person im Modus «Einmal ansehen» schickt, nimmt ein Bot nicht entgegen. Die App bietet diesen Modus in Bot-Chats gar nicht an; solche Sendungen werden verworfen und erzeugen kein Ereignis.

Bearbeiten, Löschen, Reaktionen

curl -s https://relay.hidechat.app/bot/v1/edit \
  -H "Authorization: Bearer $HC_TOKEN" -H "Content-Type: application/json" \
  -d '{"chat":"marcel","mid":"k3J9x...","text":"Erledigt.","buttons":[]}'

Tippt …

typing zeigt in der App unter dem Namen Deines Bots «tippt …» (action: "typing"), «nimmt auf …» (recording) oder «sendet eine Datei …» (uploading). Die Anzeige hält 5 Sekunden oder bis zur nächsten Nachricht Deines Bots. Das Signal ist flüchtig und nur ein Versuch: HideChat speichert es nicht, löst keine Mitteilung aus und stellt es nur zu, wenn die Person gerade verbunden ist. Pro Chat gilt höchstens 1 Signal pro Sekunde; weitere Aufrufe antworten mit ok, senden aber nichts. Eine Person, die den Bot gestoppt hat, ist nicht erreichbar (403 not_started).

Umfragen

curl -s https://relay.hidechat.app/bot/v1/sendPoll \
  -H "Authorization: Bearer $HC_TOKEN" -H "Content-Type: application/json" \
  -d '{"chat":"marcel","question":"Was essen wir?","options":["Pizza","Pasta","Salat"],"multi":false}'

Die Person stimmt in der App ab. Du bekommst pro Stimme ein vote-Ereignis mit mid und choices (Positionen in options, ab 0). Eine leere Liste heisst: die Person hat ihre Stimme zurückgezogen. Das Ereignis enthält immer die ganze aktuelle Auswahl der Person, nicht nur die Änderung. Ungültige Stimmen (Position ausserhalb der Optionen, doppelte Positionen, mehrere Antworten bei Einfachauswahl, Stimmen zu geschlossenen oder fremden Umfragen) werden verworfen und erzeugen kein Ereignis.

Mit closePoll beendest Du die Umfrage (die App zeigt sie als geschlossen); danach kommen keine vote-Ereignisse mehr. Ein zweiter closePoll für dieselbe Umfrage ist in Ordnung. Umfragen sind nicht bearbeitbar.

Ältere App-Versionen

Jede Bot-Nachricht trägt zusätzlich einen lesbaren Text. Ältere App-Versionen zeigen Knöpfe als Text-Liste («▸ Gut», Link-Knöpfe als «▸ Mehr erfahren: https://…»), Tastaturen als «Antworten: Pizza · Pasta», Medien und Umfragen mit dem Hinweis «Zum Ansehen bzw. Abstimmen bitte HideChat aktualisieren». Sie wenden edit, delete und react von Bots nicht an, und die Person kann Knöpfe nicht antippen: Sie schickt den Knopftext dann als normale Nachricht. Behandle deshalb beides: den button-Rückruf und eine message mit dem Knopftext.

Inline-Modus

Mit dem Inline-Modus tippt eine Person in irgendeinem Chat @DeinBot Suchbegriff und wählt aus einer Ergebnisliste. Das gewählte Ergebnis geht als normale Nachricht der Person in den Chat, in dem sie getippt hat. Der Inline-Modus ist standardmässig aus. Schalte ihn mit setProfile ein: inline ist der Platzhalter, den die App im Eingabefeld zeigt (1 bis 64 Zeichen), und null schaltet ihn aus. In der Bot-Werkstatt geht es auch mit /inline <bot> <platzhalter> beziehungsweise /inline <bot> aus.

Ablauf

  1. Die Person tippt @DeinBot und einen Suchbegriff. Die App wartet 400 Millisekunden nach dem letzten Tastendruck, damit nicht jeder Buchstabe eine Anfrage auslöst. Schon @DeinBot mit Leerzeichen und leerem Suchbegriff schickt nach dieser kurzen Pause den Benutzernamen der Person und einen leeren Suchbegriff an Dich. Über der Liste steht: «Dein Suchbegriff geht an @DeinBot, nicht der Chat.»
  2. Du bekommst ein inline_query-Ereignis: { "type": "inline_query", "from": "marcel", "query": "wetter bern", "offset": "", "inline_id": "…" }. Das Ereignis enthält nur Person, Suchbegriff, offset und inline_id, keinen Chat, keine Chat-Art und keine Gruppe: Du erfährst nie, wo die Person tippt. Die Anfrage kommt auch von Personen, die Deinen Bot nie gestartet haben. Der Suchbegriff hat höchstens 256 Zeichen. Wie andere Ereignisse liegt eine Anfrage (Suchbegriff und Benutzername) höchstens 24 Stunden auf unserem Server, bis Du sie abholst. Die HideChat-App schickt keine Anfragen an einen Bot, den die Person blockiert hat.
  3. Antworte mit answerInline. Pro Anfrage geht das einmal und nur innert 30 Sekunden. Die App wartet höchstens 10 Sekunden auf die Antwort und verwirft ältere Antworten, sobald der Suchbegriff geändert wurde.
curl -s https://relay.hidechat.app/bot/v1/answerInline \
  -H "Authorization: Bearer $HC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inline_id":"<inline_id>","results":[
        {"id":"bern","title":"Bern","description":"Heute 14 Grad, sonnig","text":"Wetter in Bern: 14 Grad, sonnig"}],
       "next_offset":"20"}'

Ergebnisse und Grenzen

Die Marke «über @DeinBot»

Wählt die Person ein Ergebnis, steht in der Nachricht über dem Text «über @DeinBot». Diese Marke setzt die App der Person, die sendet, nicht HideChat: Sie ist ein Feld in der Nachricht, und die App setzt sie nur für ein tatsächlich von Deinem Bot geliefertes Ergebnis. Empfänger zeigen die Marke nur an, wenn der Name auf bot endet und gültig ist. Ältere App-Versionen zeigen nur den Text. Die Marke ist also ein Hinweis, kein Beweis, woher ein Text stammt.

Fehler bei answerInline: inline_off (Inline-Modus aus), bad_inline (unbekannte inline_id), inline_expired (schon beantwortet oder älter als 30 Sekunden), bad_results (Ergebnisse oder next_offset ungültig).

Mini-Apps

Eine Mini-App ist eine Webseite auf Deinem Server, die HideChat in einem Fenster innerhalb der App öffnet, zum Beispiel ein Formular, ein Warenkorb oder ein Spiel. Die Seite kann der Person Daten zeigen und eine Antwort an Deinen Bot schicken. Die Adresse legst Du mit setProfile fest (miniapp: https-Adresse, höchstens 512 Zeichen, ohne Zugangsdaten; null entfernt sie) oder in der Bot-Werkstatt mit /miniapp <bot> <https-adresse> beziehungsweise /miniapp <bot> aus. Die Adresse darf nicht auf hidechat.app oder eine Unteradresse davon zeigen (400 bad_miniapp). Empfehlung: Betreibe die Mini-App auf einer eigenen (Sub-)Domain, auf der keine anderen sensiblen Seiten liegen. Das Fenster kann jede Seite dieser Herkunft öffnen, nicht nur Deinen Startpfad.

Öffnen

Das Fenster zeigt oben «<Botname> · <Host>» und die Zeile «Webseite des Bot-Betreibers, nicht von HideChat». Die Mini-App bekommt keinen Zugriff auf Deine Chats oder Schlüssel und keine Rechte für Kamera, Mikrofon oder Standort. Fotos und Dateien bekommt die Seite nur, wenn die Person sie in der Seite selbst auswählt.

Startdaten

Beim Öffnen hängt die App die Startdaten als #hcInit=<init> an Deine Adresse an. Der Teil nach dem # geht nicht an Deinen Server mit; Du liest ihn im Browser aus location.hash. Die Startdaten sind signiert und enthalten: bot, user (Benutzername der Person; der Anzeigename wird nicht mitgeschickt, name ist derzeit nicht gesetzt), lang (Sprache, derzeit de), theme (immer dark), colors (bg, text, accent aus dem aktiven Design) und at (Zeitpunkt in Sekunden). Auf dem Handy steht ausserdem window.HideChat bereit:

window.HideChat = {
  init,           // die Startdaten als Text
  theme,          // "dark"
  colors,         // { bg, text, accent }
  sendData(text), // schickt text (höchstens 4096 Zeichen) an Deinen Bot und schliesst das Fenster
  close()         // schliesst das Fenster
}

Wichtig: Vertraue den Startdaten nie ungeprüft. Jeder kann #hcInit=… an Deine Adresse hängen. Prüfe sie auf Deinem Server mit checkWebAppData.

Startdaten prüfen (checkWebAppData)

Schick init von Deiner Seite an Deinen eigenen Server und von dort mit dem Bot-Schlüssel an HideChat. Der Schlüssel gehört nie in die Seite selbst.

curl -s https://relay.hidechat.app/bot/v1/checkWebAppData \
  -H "Authorization: Bearer $HC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"init":"<init>"}'
{ "ok": true, "result": { "bot": "wetterbot", "user": "marcel", "lang": "de", "theme": "dark", "at": 1794470000 } }
// Node.js, auf Deinem Server (HC_TOKEN aus der Umgebung)
async function pruefeStartdaten(init) {
  const r = await fetch("https://relay.hidechat.app/bot/v1/checkWebAppData", {
    method: "POST",
    headers: { Authorization: "Bearer " + process.env.HC_TOKEN, "Content-Type": "application/json" },
    body: JSON.stringify({ init }),
  });
  const j = await r.json();
  if (!j.ok) throw new Error(j.error); // bad_webapp_data oder webapp_expired
  return j.result; // { bot, user, name?, lang, theme, at }
}

Die Startdaten sind 24 Stunden gültig. Danach: 400 webapp_expired. Falsch signierte oder für einen anderen Bot ausgestellte Daten: 400 bad_webapp_data.

Daten an den Bot schicken (sendData)

HideChat.sendData(text) schickt höchstens 4096 Zeichen an Deinen Bot, einmal pro Öffnen. Danach schliesst sich das Fenster. Du bekommst ein webapp_data-Ereignis mit chat (Benutzername der Person) und data. Es kommt nur von Personen, die den Bot gestartet haben. Das Limit ist dasselbe wie bei Inline-Anfragen (2 pro Sekunde und Person, kurzzeitig bis 5). Prüfe data auf Deinem Server wie jede Eingabe: Die Seite läuft auf dem Gerät der Person und lässt sich verändern.

Im Web (hidechat.app)

In der Web-Version zeigt HideChat Deine Seite in einem iframe mit sandbox="allow-scripts allow-forms allow-same-origin allow-popups". Dort kann die App window.HideChat nicht selbst setzen. Deine Seite liest die Startdaten aus location.hash und schickt sendData und close als Nachricht an window.parent:

window.parent.postMessage({ hc: 'sendData', data: 'Bestellung 42' }, '*');
window.parent.postMessage({ hc: 'close' }, '*');

Den Rest übernimmt dieser Baustein. Setz ihn in den <head> Deiner Seite: Auf dem Handy, wo window.HideChat schon da ist, tut er nichts; im Web legt er window.HideChat mit denselben Feldern und Methoden an.

<script>
(function () {
  if (window.HideChat) return; // in der App-Version mit eingebauter Brücke schon da
  var m = /[#&]hcInit=([^&]*)/.exec(location.hash);
  var init = m ? decodeURIComponent(m[1]) : '';
  var sent = false;
  var info = {};
  try {
    var b = init.split('.')[0].replace(/-/g, '+').replace(/_/g, '/');
    info = JSON.parse(decodeURIComponent(escape(atob(b + '==='.slice((b.length + 3) % 4)))));
  } catch (e) {}
  window.HideChat = {
    init: init,
    theme: info.theme || 'dark',
    colors: info.colors || {},
    sendData: function (text) {
      if (sent || typeof text !== 'string' || !text || text.length > 4096) return false;
      sent = true;
      window.parent.postMessage({ hc: 'sendData', data: text }, '*');
      return true;
    },
    close: function () { window.parent.postMessage({ hc: 'close' }, '*'); }
  };
})();
</script>

Regeln für Deine Seite

Gruppen, Räume und Kanäle

Dein Bot kann nicht nur mit einzelnen Personen schreiben, sondern auch in Gruppen (Ende-zu-Ende-verschlüsselt, privat) sowie in Räumen und Kanälen (nicht Ende-zu-Ende-verschlüsselt). Das ist neu: Ältere App-Versionen zeigen Bot-Nachrichten in Gruppen unter Umständen nicht an, zum Beispiel wenn die Person schon einen Einzelchat mit dem Bot hat. Nach einem Update der App erscheinen sie.

Erlaubnis: «In Gruppen erlaubt»

Ein neuer Bot ist nicht für Gruppen und Räume freigegeben. Du schaltest das selbst ein: in der App unter «Meine Bots» (Schalter «In Gruppen und Räumen erlaubt»), im Chat mit der Werkstatt mit /gruppen <bot> an (und aus) oder per Schnittstelle mit setProfile und "groups": true (alles ausser true/false gibt 400 bad_groups). Ohne Erlaubnis lässt sich der Bot nicht hinzufügen; versucht es jemand trotzdem, wird er nicht aufgenommen und bekommt kein Ereignis. Das Systemkonto botwerkstatt kommt nie in Gruppen.

Wer fügt den Bot hinzu?

Chat-IDs und Feld from

Das Feld chat (in Ereignissen und in Deinen Aufrufen) hat drei Formen:

FormChat-Art
marcelEinzelchat mit einer Person (Benutzername)
g:<gid>Gruppe
s:<raum-id>Raum oder Kanal

Alles andere gibt 400 bad_chat. Ereignisse aus Gruppen und Räumen tragen zusätzlich from: den Benutzernamen der Person, die geschrieben oder gedrückt hat. Antworte immer an den chat des Ereignisses. from fehlt bei removed_from_group, wenn der Bot selbst gegangen ist oder ein Raum aufgelöst wurde, und bei Beiträgen über einen alten Raum-Zugang (siehe unten).

Welche Methode in welcher Chat-Art?

MethodeEinzelchatGruppeRaum / Kanal
sendjaja, ohne keyboardja, ohne keyboard und buttons; mit topic
sendMediajajanein
sendPoll, closePolljajaja (anonym)
edit, delete, reactjajaja (edit ohne buttons)
typingjaneinnein
chatInfoja (nach Start)jaja
members, leaveneinjaja

Wo es eine Methode oder eine Angabe in dieser Chat-Art nicht gibt, antwortet die Schnittstelle mit 400 unsupported_chat. Ist der Bot nicht (mehr) Mitglied, gibt es 403 not_member. answerButton funktioniert immer mit der button_id des Ereignisses; in Gruppen sieht die Antwort nur die Person, die gedrückt hat. In Räumen sind mid, reply_to und die Nummern in mids die Beitragsnummern.

Datenschutz-Modus: was Dein Bot in Gruppen und Räumen sieht

Ein Bot liest nicht mit. HideChat leitet ihm in Gruppen und Räumen nur das weiter, was ihn betrifft:

  1. Befehle ohne Ziel (/wetter) oder mit Ziel auf Deinen Bot (/wetter@wetterbot).
  2. Erwähnungen (@wetterbot im Text, nicht als Teil eines Wortes oder einer E-Mail-Adresse).
  3. Antworten auf Nachrichten Deines Bots.
  4. Stimmen bei Umfragen Deines Bots, nur in Gruppen. In Räumen und Kanälen bleiben Umfragen anonym, dort gibt es kein vote-Ereignis.
  5. Knopfdrücke auf Knöpfe Deines Bots.

Alles andere kommt nie bei Deinem Bot an: andere Nachrichten, Bearbeitungen, Löschungen und Reaktionen der Mitglieder. Du kannst diesen Modus nicht abschalten.

Antworten auf Nachrichten Deines Bots und Stimmen bei seinen Umfragen zählen nur, solange seine Nachricht höchstens 48 Stunden alt ist; danach werden sie ignoriert (Befehle und Erwähnungen kommen weiter an).

Befehle mit Ziel. Ein Befehl am Textanfang darf @bot direkt hinter dem Namen tragen. Gilt das Ziel Deinem Bot (Gross- und Kleinschreibung egal, ein Satzpunkt am Ende gehört nicht zum Namen), bekommst Du ein command-Ereignis mit command: "wetter" und args ohne das Ziel. Gilt es einem anderen Bot, bekommst Du es nur, wenn der Text Dich zusätzlich erwähnt, und dann als message. Die App schlägt bei mehreren Bots in einer Gruppe genau diese Form vor.

Themen und Raum-Regeln

Raum-Zugänge (einfach)

Die älteren «Zugänge zum automatischen Posten (einfach)» in der Raum-Info (Schlüssel hcb_…) bleiben unverändert gültig: Sie schreiben nur Beiträge in genau diesen Raum, ohne Bot-Konto und ohne Hinweis an die Mitglieder. Neu sehen Bot-Konten im selben Raum solche Beiträge nach denselben Regeln wie alle anderen; das Ereignis hat kein from, dafür via: "hcb" (ein Skript, keine Person). Willst Du in einem Raum auch lesen und antworten, nimm ein Bot-Konto.

Ereignisse zur Mitgliedschaft

Wird Dein Bot aufgenommen, bekommst Du added_to_group; wird er entfernt, geht er selbst (leave) oder wird der Raum gelöscht oder aufgelöst, removed_from_group. Felder siehe Ereignisse. Danach antwortet jede Methode für diesen Chat mit 403 not_member.

Limits in Gruppen und Räumen

Bekannte Grenzen in Gruppen

Ereignisse

Jedes Ereignis ist ein JSON-Objekt. Diese Felder haben alle: id (fortlaufende Zahl), type, chat (Benutzername der Person, g:<id> oder s:<id>; an diesen Wert schickst Du Antworten mit send) und at (Zeitpunkt in Millisekunden seit 1970). Ereignisse werden 24 Stunden aufbewahrt. Nachrichten von Personen, die den Bot nicht gestartet haben oder wieder gestoppt haben, erzeugen kein Ereignis.

typeWannZusätzliche Felder
startEine Person tippt auf «Starten» (auch nach einem Stopp)param: Wert aus dem Link …/b/<bot>?start=<wert>, falls vorhanden und gültig
stopEine Person stoppt den Bot (nur, wenn sie ihn vorher gestartet hatte)keine. Danach kannst Du ihr nicht mehr schreiben, bis sie wieder startet.
messageEine Person schreibt einen normalen Texttext (bis 16 000 Zeichen), mid (ID der Nachricht, für reply_to), reply_to (mid der Nachricht, auf die die Person antwortet, falls vorhanden); bei Fotos, Videos, Sprachnachrichten und Dateien zusätzlich media (text ist dann der Bildtext und kann leer sein)
commandDer Text beginnt mit /, zum Beispiel /wetter Berncommand (klein geschrieben, ohne /: wetter), args (Rest des Textes, Bern), text (voller Text), mid, reply_to (falls vorhanden)
buttonEine Person tippt einen Rückruf-Knopf Deiner Nachrichtmid (Deine Nachricht), data, button_id (für answerButton)
editedEine Person bearbeitet eine ihrer Nachrichtenmid, text (neuer Text)
deletedEine Person löscht Nachrichten für beidemids (Liste)
reactionEine Person reagiert auf eine Nachrichtmid, emoji (null = Reaktion entfernt)
inline_queryEine Person tippt @DeinBot mit einem Suchbegriff (Inline-Modus an; auch ohne Start, ohne Chat)from, query, offset, inline_id (für answerInline)
webapp_dataEine Mini-App schickt mit sendData Daten (nur von Personen, die den Bot gestartet haben)chat, data (höchstens 4096 Zeichen)
voteEine Person stimmt bei Deiner Umfrage ab oder zieht ihre Stimme zurück (Einzelchat und Gruppen; in Räumen und Kanälen bleiben Umfragen anonym, dort gibt es kein vote)mid, choices (Positionen ab 0; [] = zurückgezogen)
added_to_groupDer Bot wurde in eine Gruppe (g:<id>) oder einen Raum/Kanal (s:<id>) aufgenommenfrom (wer ihn hinzugefügt hat), title, chat_type (group, room, channel)
removed_from_groupDer Bot ist nicht mehr Mitgliedfrom (wer ihn entfernt oder den Raum gelöscht hat; fehlt, wenn der Bot selbst gegangen ist oder der Raum aufgelöst wurde, weil der letzte Mensch gegangen ist), reason: "deleted" (Raum gelöscht oder aufgelöst)
{ "id": 7, "type": "command", "chat": "marcel", "at": 1794470123456,
  "text": "/wetter Bern", "command": "wetter", "args": "Bern", "mid": "q8Hn..." }

In Gruppen und Räumen tragen message, command und button zusätzlich from (Benutzername der Person); in Gruppen auch vote. Welche Ereignisse überhaupt ankommen, regelt der Datenschutz-Modus: in Gruppen und Räumen gibt es kein edited, deleted und reaction. Nachrichten von Personen, die den Bot nie gestartet haben, kommen dort an, ohne dass ein Start nötig ist. In Räumen ist mid die Beitragsnummer; in Räumen mit Themen steht topic (Nummer des Themas, fehlt bei «Allgemein»). Beiträge über einen alten Raum-Zugang (hcb_) kommen ohne from, dafür mit via: "hcb" (ein Skript, keine Person). Antwortet Dein Bot mit reply_to ohne topic, landet die Antwort im Thema des beantworteten Beitrags.

Das Feld media enthält file_id, kind (image, video, audio, file), mime, size und je nach Datei name, w, h, dur. Die Schlüssel der Datei erhältst Du nie; Du holst sie mit file. Medien im Modus «Einmal ansehen» kommen nicht an. Gesendete Texte haben höchstens 4000 Zeichen.

Webhook

Webhook-Signatur prüfen

Jede Zustellung trägt den Kopf X-HideChat-Signature: sha256=<hex>. Der Wert ist der HMAC-SHA256 des unveränderten Rohinhalts (die Bytes des Inhalts, bevor Du sie als JSON liest) mit Deinem secret aus setWebhook als Schlüssel, als kleingeschriebene Hex-Zeichen. Rechne ihn selbst aus und vergleiche in konstanter Zeit. Lehne Anfragen mit falscher oder fehlender Signatur ab.

JavaScript (Node.js)

import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.HC_WEBHOOK_SECRET;

function signaturOk(rohinhalt, kopf) {
  const erwartet = Buffer.from("sha256=" + createHmac("sha256", SECRET).update(rohinhalt).digest("hex"));
  const erhalten = Buffer.from(kopf ?? "");
  return erwartet.length === erhalten.length && timingSafeEqual(erwartet, erhalten);
}

createServer((req, res) => {
  const teile = [];
  req.on("data", (t) => teile.push(t));
  req.on("end", () => {
    const roh = Buffer.concat(teile); // Rohbytes, nicht neu serialisiert
    if (!signaturOk(roh, req.headers["x-hidechat-signature"])) {
      res.writeHead(401).end();
      return;
    }
    const ereignis = JSON.parse(roh.toString("utf8"));
    console.log(ereignis.type, ereignis.chat, ereignis.text);
    res.writeHead(200).end("ok");
  });
}).listen(3000);

Python

import hashlib
import hmac
import os

from flask import Flask, request

SECRET = os.environ["HC_WEBHOOK_SECRET"].encode()
app = Flask(__name__)


def signatur_ok(rohinhalt: bytes, kopf: str) -> bool:
    erwartet = "sha256=" + hmac.new(SECRET, rohinhalt, hashlib.sha256).hexdigest()
    return hmac.compare_digest(erwartet.encode(), (kopf or "").encode())


@app.post("/hidechat")
def webhook():
    roh = request.get_data()  # Rohbytes, nicht request.json
    if not signatur_ok(roh, request.headers.get("X-HideChat-Signature")):
        return "", 401
    ereignis = request.get_json(force=True)
    print(ereignis["type"], ereignis["chat"], ereignis.get("text"))
    return "ok"

Fehler

Bei einem Fehler ist ok gleich false, error ein fester Code und hint ein erklärender Satz. Verlass Dich im Programm auf error und den HTTP-Status, nicht auf hint.

StatuserrorBedeutung
401unauthorizedSchlüssel fehlt, ist falsch oder abgelaufen (nach einem neuen Schlüssel), oder der Bot ist gesperrt oder gelöscht. Ein neuer Schlüssel, eine Sperre oder eine Löschung wirkt spätestens nach 5 Sekunden
404not_foundDiese Methode gibt es nicht
405method_not_allowedDie Methode verlangt POST
400bad_jsonDer Inhalt ist kein JSON-Objekt
413too_largeDer JSON-Inhalt ist grösser als 100 000 Zeichen, oder die Datei bei sendMedia ist grösser als 20 MB
400bad_afterafter ist keine Zahl ab 0
400bad_waitwait liegt nicht zwischen 0 und 30
409webhook_activeEin Webhook ist gesetzt; erst deleteWebhook aufrufen
400bad_webhookWebhook-Adresse ungültig (kein https://, lokale oder private Adresse, zu lang)
400bad_chatchat ist weder ein Benutzername (Einzelchat) noch g:<Gruppen-ID> noch s:<Raum-ID>
400bad_texttext fehlt, ist leer oder länger als 4000 Zeichen
400bad_replyreply_to ist keine gültige Nachrichten-ID
403not_startedDie Person hat den Bot nicht gestartet oder wieder gestoppt (gilt für jede Methode, die an eine Person geht)
429too_fastZu viele Nachrichten, file-Abrufe oder gleichzeitig wartende updates-Anfragen. Warte retry_after Sekunden (steht zusätzlich in der Antwort)
404no_userDieses Konto gibt es nicht (mehr) oder es ist gesperrt
404no_botDiesen Bot gibt es nicht
400bad_namename fehlt oder ist länger als 40 Zeichen
409reserved_namename enthält ein reserviertes Wort (hidechat, support, official, offiziell, admin, werkstatt, gross oder klein geschrieben)
400bad_aboutabout ist länger als 300 Zeichen
400bad_welcomewelcome ist länger als 500 Zeichen
400bad_commandscommands ist keine gültige Liste (höchstens 30, Regeln siehe setCommands, keine doppelten Namen)
400bad_buttonsbuttons ungültig: mehr als 8 Reihen oder 4 Knöpfe pro Reihe, Text nicht 1 bis 40 Zeichen in einer Zeile, nicht genau eines von data (1 bis 64 Zeichen), url (nur https://, höchstens 512, ohne Zugangsdaten), inline (höchstens 64 Zeichen) und webapp (nur mit gesetzter miniapp und gleicher Herkunft)
400bad_keyboardkeyboard ungültig (Reihen, Beschriftungen, hint höchstens 64 Zeichen, once true/false)
404no_messageDie Nachricht gibt es nicht: nur eigene Nachrichten in diesem Chat, höchstens 48 Stunden alt (bei closePoll: nur eigene Umfragen)
400not_editableNur Textnachrichten (send) lassen sich bearbeiten, keine Medien oder Umfragen
400bad_editedit braucht text oder buttons
400bad_reactionemoji ist keines von ❤️ 👍 😂 😮 😢 🔥 und nicht null
400bad_midsmids ist keine Liste mit 1 bis 100 Nachrichten-IDs
400bad_midmid ist keine gültige Nachrichten-ID
404button_expiredDer Knopfdruck ist unbekannt, schon beantwortet oder älter als 15 Minuten
400bad_answeranswerButton: text länger als 200 Zeichen oder alert nicht true/false
400bad_actionaction ist nicht typing, recording oder uploading
400unsupported_chatDie Methode oder die Angabe gibt es für diese Chat-Art nicht, zum Beispiel typing in Gruppen und Räumen, keyboard in Gruppen, buttons in Räumen, members im Einzelchat (siehe Tabelle)
403not_memberDer Bot ist nicht (mehr) Mitglied dieser Gruppe oder dieses Raums: entfernt, selbst gegangen (leave) oder nie aufgenommen
403admins_onlyRaum: In diesem Kanal oder dieser Gruppe dürfen nur Admins schreiben (ein Raum-Admin kann den Bot als Admin hinzufügen)
403mutedRaum: Der Bot ist dort vorübergehend stummgeschaltet
400bad_topicRaum: topic ist keine Nummer eines bestehenden Themas (0 = Allgemein)
403topic_closedRaum: Das Thema ist geschlossen
410room_removedDen Raum oder Kanal gibt es nicht mehr
400blocked_contentRaum: Der Inhalt enthält gesperrte Begriffe
403forbiddenRaum: Dafür fehlt dem Bot das Recht, zum Beispiel members in einem Kanal nur als Admin
400bad_groupssetProfile: groups ist nicht true oder false
403inline_offanswerInline: Der Inline-Modus des Bots ist aus
410inline_expiredanswerInline: Die Anfrage ist schon beantwortet oder älter als 30 Sekunden
400bad_resultsanswerInline: results oder next_offset ungültig
400bad_inlinesetProfile: inline ist kein Platzhalter von 1 bis 64 Zeichen (einzeilig) und nicht null; answerInline: unbekannte inline_id
400bad_miniappsetProfile: miniapp ist keine gültige Adresse (https, höchstens 512 Zeichen, ohne Zugangsdaten) und nicht null. Ein webapp-Knopf mit anderer Herkunft ist dagegen bad_buttons
400bad_webapp_datacheckWebAppData: Startdaten ungültig, falsch signiert oder für einen anderen Bot
400webapp_expiredcheckWebAppData: Startdaten sind älter als 24 Stunden
400bad_privacysetProfile: privacy ist keine gültige https-Adresse (höchstens 512 Zeichen, ohne Zugangsdaten) und nicht null
400bad_categoryVerzeichnis: Kategorie unbekannt (erlaubt: werkzeuge, nachrichten, unterhaltung, spiele, lernen, firmen, sonstiges)
400need_aboutVerzeichnis: Der Bot braucht zuerst eine Beschreibung
400need_privacyVerzeichnis: Der Bot braucht zuerst einen Link zur Datenschutzerklärung (privacy)
409already_pendingVerzeichnis: Der Bot ist schon eingereicht und wird geprüft
403bannedVerzeichnis: Ein gesperrter Bot kann nicht eingereicht werden
409not_pendingVerzeichnis (Team): Der Bot ist nicht in Prüfung
409not_listedVerzeichnis (Team): Der Bot steht nicht im Verzeichnis
403own_botBewertung: Den eigenen Bot kann man nicht bewerten
400bad_starsBewertung: stars muss eine ganze Zahl von 0 bis 5 sein
400bad_pollUmfrage ungültig (question 1 bis 300 Zeichen, options 2 bis 10 Einträge zu je 1 bis 100 Zeichen, nicht nur Leerzeichen, multi true/false)
400bad_mediasendMedia: kein multipart/form-data, Datei fehlt oder ist unlesbar, unbekanntes kind, Typ nicht erlaubt oder passt nicht zum Inhalt, Dateiname fehlt bei file oder enthält Zeilenumbrüche, Steuerzeichen oder unsichtbare Zeichen, w/h/dur keine Zahl
400bad_captioncaption ist länger als 1024 Zeichen
429quotaDas Tageskontingent für Medien (600 MB pro Tag) ist aufgebraucht
404no_filefile: unbekannte file_id oder älter als 7 Tage
500bot_secret_missingDer Server ist nicht vollständig eingerichtet. Versuche es später, sonst melde Dich beim Support
409e2e_modeIm Ende-zu-Ende-Modus sendet Dein Programm Einzelchat-Nachrichten selbst über das SDK; die Methode gilt dann nur für Räume und Kanäle (s:…). Ebenso: Baukasten einschalten im Ende-zu-Ende-Modus
409builder_onsetE2e: Schalte zuerst den Baukasten aus. Er geht nur im gehosteten Modus
409in_groupssetE2e: Der Bot ist noch in privaten Gruppen. Verlass sie zuerst mit leave; Ende-zu-Ende-Bots können noch nicht in Gruppen
400bad_keyssetE2e: box_pub und sign_pub müssen je 32 Byte (Base64) sein, verschieden und nicht die bisherigen Schlüssel des Bots
400bad_proofsetE2e: proof ist nicht die Ed25519-Signatur von hidechat-bot-e2e:<bot>:<box_pub>:<sign_pub> mit dem neuen Signierschlüssel
403official_botsetE2e: Offizielle Bots bleiben gehostet. Ein gesperrter Bot bekommt 403 banned
403owner_onlysetHosted: Zurück auf gehostet stellst Du als Besitzer in «Meine Bots» oder mit /modus <bot> gehostet in der Bot-Werkstatt um
400use_sdkApp («Meine Bots»): Ende-zu-Ende schaltest Du mit dem SDK ein, Dein Programm erzeugt die Schlüssel. Kommt auch, wenn der Antrag abgelaufen ist
409no_pendingApp («Meine Bots»): Der Fingerabdruck passt nicht zum offenen Antrag (er wurde inzwischen ersetzt). Neu laden und noch einmal vergleichen
–not_e2eSDK: Der Bot läuft (noch) nicht Ende-zu-Ende oder die Schlüsseldatei passt nicht; den Antrag in «Meine Bots» bestätigen. Weitere Codes des Relays: not_started, too_fast, button_expired, inline_expired, bad_envelope, no_user, bot_unavailable, rekeyed (siehe Ende-zu-Ende)
503unavailableUnerwarteter Fehler auf dem Server. Versuche es nach einigen Sekunden erneut

Limits

WasGrenze
Bots pro Konto20, mit aktivem HideChat Plus 100
Gruppen und RäumeHöchstens 5 Bots pro Gruppe/Raum; 200 Gruppen und 200 Räume pro Bot; 20 Sendungen pro Minute pro Gruppe/Raum (Burst 5), zusätzlich zu den 30 pro Sekunde; 10 Aufnahmen pro Stunde und hinzufügender Person. Siehe Gruppen
Senden30 Sendungen pro Sekunde pro Bot; 1 Sendung pro Sekunde pro Chat (kurzzeitig bis 3 hintereinander); gilt für send, sendMedia, sendPoll, edit, delete, react und das erste closePoll einer Umfrage (ein wiederholtes closePoll zählt nicht). Darüber: 429 too_fast mit retry_after
Inline-Anfragen2 pro Sekunde pro Person (kurzzeitig bis 5), zusätzlich ein eigener Eimer von 30 pro Sekunde pro Bot, getrennt vom Sendelimit (Anfragen und webapp_data verbrauchen die 30 Sendungen pro Sekunde nicht); gilt auch für webapp_data (sendData). Darüber: still verworfen. answerInline: einmal pro Anfrage, innert 30 Sekunden; höchstens 20 Ergebnisse, id und title 64, description 120, text 4000, next_offset 64 Zeichen; Suchbegriff 256 Zeichen. Siehe Inline-Modus
Mini-AppsAdresse 512 Zeichen; Startdaten 24 Stunden gültig; sendData höchstens 4096 Zeichen und einmal pro Öffnen. Siehe Mini-Apps
Dateien abrufenfile zählt zum Limit von 30 pro Sekunde pro Bot (nicht pro Chat). Darüber: 429 too_fast mit retry_after
Ereignisse24 Stunden aufbewahrt; updates liefert höchstens 100 pro Antwort
Long-Pollingwait höchstens 30 Sekunden; höchstens 10 gleichzeitig wartende Anfragen pro Bot (weitere mit wait bekommen 429 too_fast mit retry_after)
Webhook10 Sekunden Zeit pro Zustellung; Wiederholungen nach 10 Sekunden, 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, danach verworfen
MedienHöchstens 20 MB pro Datei; 600 MB pro Bot und Tag (429 quota); Bildtext bis 1024 Zeichen; auf dem Server höchstens 7 Tage aufbewahrt
Knöpfe und TastaturHöchstens 8 Reihen mit je 4; Beschriftung 40 Zeichen; data 64 Zeichen; url 512 Zeichen; hint 64 Zeichen
UmfragenFrage 300 Zeichen; 2 bis 10 Antworten zu je 100 Zeichen
Bearbeiten und LöschenNur eigene Nachrichten, höchstens 48 Stunden alt; Löschen bis 100 Nachrichten pro Aufruf
Knopf-AntwortEinmal pro Knopfdruck, höchstens 15 Minuten danach; die App wartet 15 Sekunden
«Tippt …»Höchstens 1 Signal pro Sekunde und Chat; Anzeige 5 Sekunden. Jedes gesendete Signal zählt zu den 30 pro Sekunde des Bots; ist dieses Limit erschöpft, wird das Signal still verworfen (Antwort ok)
TexteGesendet bis 4000 Zeichen; empfangen bis 16 000 Zeichen
Baukasten50 Antworten, 10 Formulare, 20 geplante Beiträge, 5 Feeds, 60 000 Zeichen; Feed-Abruf alle 30 Minuten (höchstens 3 Einträge, 1 MB); Formular-Antworten 30 Tage. Siehe Baukasten
ProfilName 40, Beschreibung 300, Willkommenstext 500 Zeichen; 30 Befehle, Beschreibung je Befehl 80 Zeichen

Die Zahlen sind Startwerte und können sich ändern. Wir kündigen Änderungen an dieser Stelle an.

Teile https://hidechat.app/b/<botname>. Das öffnet die App beim Profil Deines Bots mit dem Knopf «Starten». Mit ?start=<wert> hängst Du einen Wert an (1 bis 64 Zeichen aus A–Z, a–z, 0–9, _, -), der im start-Ereignis als param ankommt, zum Beispiel https://hidechat.app/b/wetterbot?start=bern. So erkennst Du, woher jemand kommt. Ohne HideChat öffnet der Link die Web-Version. me liefert den Link im Feld link.

QR-Code: Auf dem Profil Deines Bots und unter «Meine Bots» zeigt die App den Link als QR-Code («Bot-Link»), auf Wunsch mit Startwert (Feld «Startwert (optional)»). Er wird auf dem Gerät erzeugt, es ist kein externer Dienst beteiligt. Wer HideChat noch nicht hat, registriert sich zuerst; der Startwert bleibt erhalten und kommt danach im start-Ereignis an.

Baukasten ohne Programmierung

Wenn Du keinen eigenen Server betreiben willst, richtest Du den Bot in der App ein. Der Baukasten kann: einen Starttext mit Menü-Knöpfen senden, Antworten auf Knöpfe, Befehle (/preise) und Stichwörter geben, Formulare mit bis zu 10 Fragen abfragen, Beiträge planen (einmalig, täglich oder wöchentlich) und RSS-/Atom-Feeds in einen Kanal oder Raum posten.

Einrichten

Wichtig: Baukasten und Dein Server schliessen sich aus

Solange der Baukasten an ist, gehen Nachrichten an den Baukasten und nicht an Deinen Server: Ereignisse aus Einzelchats (message, command, start, stop, button und die übrigen) erreichen weder updates noch Deinen Webhook; es kommen dort also keine neuen Ereignisse an. Ereignisse aus Gruppen, Räumen und dem Inline-Modus werden verworfen; der Baukasten antwortet nur im Einzelchat. Das Senden über die Schnittstelle (send usw.) mit Deinem Schlüssel funktioniert weiterhin. Schaltest Du den Baukasten aus, bleibt die Einrichtung gespeichert, und Ereignisse gehen wieder an Deinen Server.

Wie der Baukasten antwortet

Formular-Antworten

Die Antworten speichert HideChat beim Bot (nicht auf Deinem Server) und zeigt sie Dir in der App unter «Eingänge»; zusätzlich schickt Dir die Bot-Werkstatt eine Nachricht «Neue Antwort auf …» (sofern Du sie gestartet hast). Sie werden 30 Tage aufbewahrt und danach gelöscht; Du kannst sie auch einzeln oder alle entfernen. Kopiere, was Du länger brauchst, in Dein eigenes System. Frag nichts ab, wofür Du keine Datenschutzerklärung hast (siehe Bot-Nutzungsbedingungen).

Geplante Beiträge

Ein Beitrag geht in einen Kanal oder Raum, in dem der Bot Mitglied ist (sonst bad_room; in Kanälen muss er Admin sein). Geprüft wird das beim Speichern nur für neue Beiträge und Feeds und für solche, deren Kanal oder Raum Du geändert hast; wurde der Bot später entfernt, lassen sich die übrigen Einstellungen weiter speichern, und der Beitrag zeigt den Fehler. Du wählst entweder einen Zeitpunkt in der Zukunft («Einmal am») oder eine Wiederholung («Täglich um», «Wöchentlich am»). Die Uhrzeit gilt in der Zeitzone Deines Geräts, auch mit Sommerzeit. Klappt ein Beitrag nicht (zum Beispiel weil der Bot entfernt wurde), steht der Fehler beim Beitrag; wiederholte Beiträge versuchen es beim nächsten Termin wieder.

RSS- und Atom-Feeds

Grenzen

WasGrenze
Starttext / «Wenn nichts passt»2000 / 500 Zeichen
AntwortenHöchstens 50; Knopf-Text 40 Zeichen (einzeilig); Befehl 1 bis 32 Zeichen aus a–z, 0–9, _ (nicht start, menu, abbrechen; je Bot eindeutig); höchstens 10 Stichwörter zu je 1 bis 40 Zeichen; Antworttext 2000 Zeichen
FormulareHöchstens 10; Titel 60 Zeichen; 1 bis 10 Fragen zu je 300 Zeichen; Dankestext 500 Zeichen; Antwort der Person bis 1000 Zeichen
Geplante BeiträgeHöchstens 20; Text 2000 Zeichen
FeedsHöchstens 5; Abruf alle 30 Minuten, höchstens 3 Einträge pro Abruf
GesamtgrösseDie Einrichtung darf höchstens 60 000 Zeichen gross sein
Formular-Antworten30 Tage aufbewahrt, höchstens 1000 je Bot (die ältesten fallen weg); in der App die neuesten 100. Pro Person höchstens 5 abgeschlossene Formulare pro Stunde, darüber wird die Antwort nicht gespeichert. Nachrichten der Bot-Werkstatt «Neue Antwort auf …» höchstens 20 pro Stunde und Bot, danach einmal ein Hinweis auf «Eingänge»

Fehlerhafte Eingaben meldet der Server mit bad_builder (und dem Feld, zum Beispiel items.3.reply); einen Kanal oder Raum, in dem der Bot nicht Mitglied ist, mit bad_room. Die Antworten des Baukastens zählen nicht zum Sendelimit Deines Bots. Begrenzt wird stattdessen, was Personen dem Baukasten schicken: 2 Nachrichten pro Sekunde pro Person (kurzzeitig bis 5) und zusammen 30 pro Sekunde pro Bot (derselbe Eimer wie für Inline-Anfragen und webapp_data). Was darüber hinausgeht, wird still verworfen.

SDK für JavaScript und Python

Statt die Schnittstelle selbst anzusprechen, nimmst Du das Paket hidechat-bot: für Node.js ab Version 20 (mit TypeScript-Typen) und für Python ab 3.10 (asyncio). Beide können dasselbe: Ereignisse abholen oder per Webhook empfangen, alle Methoden mit denselben Feldern und Fehlercodes, und den Ende-zu-Ende-Modus. Das Paket auf npm und PyPI folgt; bis dahin installierst Du es direkt von hidechat.app.

Herunterladen und installieren

# JavaScript
npm install https://hidechat.app/entwickler/sdk/hidechat-bot-0.1.0.tgz

# Python
pip install https://hidechat.app/entwickler/sdk/hidechat_bot-0.1.0-py3-none-any.whl

Dateien und Prüfsummen: hidechat-bot-0.1.0.tgz, hidechat_bot-0.1.0-py3-none-any.whl, SHA256SUMS. Wer die Dateien zuerst herunterlädt, prüft sie im selben Ordner mit sha256sum -c SHA256SUMS (macOS: shasum -a 256 -c SHA256SUMS) und installiert danach die lokale Datei. Abhängigkeiten: in JavaScript nur tweetnacl und ws, in Python nur PyNaCl und websockets.

Echo-Bot in 15 Zeilen

Der Bot-Schlüssel kommt aus der Umgebungsvariable HIDECHAT_BOT_TOKEN, nie aus dem Code.

// echo.mjs – starten mit: HIDECHAT_BOT_TOKEN=… node echo.mjs
import { createBot } from "hidechat-bot";

const bot = createBot({ mode: "hosted", token: process.env.HIDECHAT_BOT_TOKEN });

bot.command("start", (ev) => bot.send(ev.chat, "Hallo! Schick mir etwas, ich schicke es zurück."));

bot.on("message", (ev) =>
  ev.media ? bot.send(ev.chat, "Danke für die Datei.") : bot.send(ev.chat, ev.text),
);

bot.onError((e) => console.error(e));

await bot.start(); // läuft, bis Du das Programm beendest
# echo.py – starten mit: HIDECHAT_BOT_TOKEN=… python echo.py
import os
from hidechat_bot import create_bot

bot = create_bot("hosted", os.environ["HIDECHAT_BOT_TOKEN"])

@bot.command("start")
async def start(ev):
    await bot.send(ev["chat"], "Hallo! Schick mir etwas, ich schicke es zurück.")

@bot.on("message")
async def echo(ev):
    await bot.send(ev["chat"], "Danke für die Datei." if ev.get("media") else ev["text"])

bot.run()  # läuft, bis Du Strg+C drückst

Ereignisse haben genau die Felder aus Ereignisse; command("start") gilt auch für den Start über einen Link mit Startwert (ev.param). Die Methoden heissen wie in der Schnittstelle, in Python in snake_case (answer_button statt answerButton). Fehler kommen als HideChatError mit code, status, hint und bei too_fast der Wartezeit; nach too_fast wiederholt das SDK einmal von selbst. Ein Ereignis gilt erst als erledigt, wenn alle Handler fertig sind; Fehler in Handlern gehen an onError (on_error), der Bot läuft weiter.

Webhook mit dem SDK

Mit gesetztem Webhook prüft das SDK die Signatur für Dich: verifyWebhook(rohinhalt, kopf, geheimnis) bzw. verify_webhook(rohinhalt, kopf, geheimnis) rechnet den HMAC über die Rohbytes und vergleicht in konstanter Zeit.

import http from "node:http";
import { verifyWebhook } from "hidechat-bot";

http.createServer((req, res) => {
  const teile = [];
  req.on("data", (t) => teile.push(t));
  req.on("end", () => {
    const roh = Buffer.concat(teile);
    if (!verifyWebhook(roh, req.headers["x-hidechat-signature"], process.env.HIDECHAT_WEBHOOK_SECRET)) return res.writeHead(401).end();
    const ereignis = JSON.parse(roh.toString("utf8"));
    res.writeHead(200).end("ok"); // langsame Arbeit danach erledigen, HideChat wartet höchstens 10 Sekunden
  });
}).listen(8080);
from hidechat_bot import verify_webhook

if not verify_webhook(roh, kopf, os.environ["HIDECHAT_WEBHOOK_SECRET"]):  # roh = Bytes des Inhalts
    ...  # mit 401 antworten

Noch einfacher: bot.webhookHandler(geheimnis) ist ein fertiger Handler für node:http, in Python ist bot.webhook_app(geheimnis) eine ASGI-Anwendung (z. B. für uvicorn). Beide prüfen die Signatur, verteilen das Ereignis an Deine Handler und antworten erst danach mit 200.

Ende-zu-Ende-Modus

Im gehosteten Modus öffnet HideChat die Nachrichten an Deinen Bot und gibt sie über die Schnittstelle an Dein Programm weiter. Im Ende-zu-Ende-Modus hat Dein Programm eigene Schlüssel und verbindet sich wie eine App mit dem Relay: Nachrichten zwischen Personen und Deinem Bot sind dann für HideChat nicht lesbar. Personen sehen im Bot-Chat: «Bot · Ende-zu-Ende verschlüsselt. Nur der Betreiber kann mitlesen, HideChat nicht.» Den Modus gibt es nur mit dem SDK (das Programm erzeugt die Schlüssel und öffnet und versiegelt jede Nachricht selbst).

Was der Modus schützt und was nicht

FunktionIm Ende-zu-Ende-Modus
Text, Befehle, Antworten, Start mit StartwertGeht; der Inhalt steckt nur im verschlüsselten Umschlag (auch der Startwert).
Knöpfe, Antwort-Tastatur, answerButtonGeht; das SDK prüft die Knopfdrücke gegen die eigenen gesendeten Nachrichten (48 Stunden). HideChat erlaubt je Knopfdruck genau eine Antwort innert 15 Minuten.
Medien senden und empfangen, fileGeht; das SDK verschlüsselt und entschlüsselt die Dateien selbst. Das Tageskontingent von 600 MB gilt weiter.
Umfragen, Stimmen, closePollGeht; die Stimmen prüft das SDK.
Bearbeiten, Löschen, ReaktionenGeht.
Inline-ModusGeht; eine Antwort je Anfrage innert 30 Sekunden.
Mini-AppsGeht; die Startdaten signiert weiterhin HideChat (checkWebAppData), sendData kommt verschlüsselt an.
«Tippt …» (typing)Geht weiter über die Schnittstelle (ein Signal ohne Inhalt).
Räume und Kanäle (s:…)Geht über die Schnittstelle wie bisher. Räume und Kanäle sind nie Ende-zu-Ende verschlüsselt; HideChat kann diese Beiträge lesen.
Statistik, Auto-Sperre, Start/Stopp/BlockierenBleibt bei HideChat. Wer den Bot nicht gestartet hat (oder ihn gestoppt oder blockiert hat), bekommt weiterhin keine Nachrichten von ihm; das prüft der Server.
Melden, Sperren, Verzeichnis, BewertungenBleibt wie bisher. Eine Meldung enthält, was die meldende Person mitschickt.
Private Gruppen (g:…)Geht nicht. Ende-zu-Ende-Bots können noch nicht in Gruppen (Methoden antworten mit unsupported_chat, die App bietet solche Bots für Gruppen nicht an). Vor dem Umschalten muss der Bot alle privaten Gruppen verlassen (in_groups).
BaukastenGeht nicht (er läuft bei HideChat und muss die Nachrichten lesen). Vor dem Umschalten ausschalten (builder_on); im Ende-zu-Ende-Modus lässt er sich nicht einschalten (e2e_mode).
Bot-Werkstatt und andere offizielle BotsBleiben gehostet (official_bot).

Die Methoden send, sendMedia, sendPoll, closePoll, edit, delete, react, answerButton, answerInline und file der Schnittstelle antworten im Ende-zu-Ende-Modus für Einzelchats mit 409 e2e_mode; das SDK erledigt sie über das Relay. Für Räume und Kanäle gelten sie weiter.

Schlüssel erzeugen und Ende-zu-Ende beantragen

export HIDECHAT_BOT_TOKEN=…                  # Bot-Schlüssel
npx hidechat-bot keys hidechat-keys.json      # neue Schlüssel (überschreibt nie eine Datei)
npx hidechat-bot register hidechat-keys.json  # Antrag, zeigt den Fingerabdruck

# Python: python -m hidechat_bot keys hidechat-keys.json, dann python -m hidechat_bot register hidechat-keys.json

Das Umschalten geht in zwei Schritten, damit ein gestohlener Bot-Schlüssel allein Deine Chats nicht übernehmen kann:

  1. Antrag durch das Programm. register ruft setE2e mit den öffentlichen Schlüsseln und einem Beweis auf, dass das Programm die geheimen besitzt. Antwort: { "mode": "pending", "fingerprint": "a1b2 c3d4 e5f6 0718" }. Der Fingerabdruck sind die ersten 16 Hex-Zeichen von SHA-256 über <box_pub>:<sign_pub> (beide Schlüssel als Base64-Text), in Vierergruppen. Am Bot ändert sich noch nichts. Die Bot-Werkstatt meldet Dir den Antrag (höchstens 3 solche Mitteilungen pro Bot in 24 Stunden). Ein neuer Antrag ersetzt den alten; ein Antrag gilt 24 Stunden.
  2. Bestätigung durch Dich als Besitzer. In der HideChat-App unter Einstellungen → Meine Bots → @<bot> → Betriebsart steht der Antrag mit Fingerabdruck. Vergleiche ihn mit der Anzeige Deines Programms und tippe auf «Bestätigen». Warst Du es nicht, tippe auf «Ablehnen» und stell in der Werkstatt einen neuen Bot-Schlüssel aus.

Erst nach der Bestätigung läuft der Bot Ende-zu-Ende. Vorher endet start() mit dem Fehler not_e2e. Dann startest Du das Programm im neuen Modus:

const bot = createBot({ mode: "e2e", token: process.env.HIDECHAT_BOT_TOKEN, keys: process.env.HIDECHAT_KEYS });
bot = create_bot("e2e", os.environ["HIDECHAT_BOT_TOKEN"], os.environ["HIDECHAT_KEYS"])

Die Handler bleiben gleich. Das SDK speichert seinen Zustand (Geräte-Kennung, gesendete Nachrichten für Knöpfe und Umfragen, Schlüssel eingehender Dateien) im Ordner .hidechat-bot; lösche ihn nicht, sonst kommen wartende Nachrichten nicht mehr an. Jede Nachricht wird erst nach Deinen Handlern quittiert und kommt nach einem Absturz noch einmal, doppelte überspringt das SDK.

Schlüssel sicher aufbewahren

Schlüsselwechsel

Neue Schlüssel für einen Ende-zu-Ende-Bot beantragst Du genauso (keys in eine neue Datei, register, in der App bestätigen); auch hier gilt der Antrag erst nach Deiner Bestätigung. Das laufende Programm endet danach mit rekeyed. Wichtig: Sobald Du einen Wechsel bestätigst (neue Schlüssel oder Umschalten der Betriebsart), verwirft HideChat alle Nachrichten, die beim Relay noch auf Dein Programm warten. Lass Dein Programm darum vor dem Bestätigen laufen, bis es alles abgeholt hat. Starte es danach mit den neuen Schlüsseln und gib etwa 7 Tage lang die alte Datei als previousKeys (Python previous_keys) mit: Das hilft nur bei Nachrichten, die Personen nach dem Wechsel schicken, solange ihre App noch die alten Schlüssel gespeichert hat; schon wartende Nachrichten holt es nicht zurück. Kann das Programm eine Nachricht nicht öffnen, bittet es die Person (höchstens einmal in 24 Stunden): «Dieser Bot hat neue Schlüssel bekommen. Bitte schick Deine letzte Nachricht noch einmal.» Die App holt sich dabei die neuen Schlüssel.

Zurück auf gehostet und was mit alten Ereignissen passiert

Ein Programm je Bot

Lass je Bot genau ein Programm gleichzeitig laufen, mit einem eigenen Zustandsordner. Zwei Programme mit derselben Schlüsseldatei würden sich die Nachrichten teilen oder doppelt beantworten. Für einen Umzug: altes Programm beenden, Schlüsseldatei und Zustandsordner mitnehmen, neues starten.

Was HideChat weiterhin sieht

Damit Start, Stopp und Blockieren auch im Ende-zu-Ende-Modus beim Server durchgesetzt werden, trägt jeder Umschlag an oder von einem Bot ein unverschlüsseltes Art-Kennzeichen bk: start, stop, block, inline, button, msg, quiet, group von Personen und msg, quiet, answer, inline vom Bot. HideChat sieht dadurch, wer Deinen Bot startet, stoppt oder blockiert, wann und wie viele Nachrichten fliessen, dass jemand eine Inline-Anfrage stellt oder einen Knopf drückt, und die Grösse der Umschläge und Dateien, aber keinen Inhalt (keinen Text, keinen Suchbegriff, keinen Knopf-Wert, keine Datei). Dein Programm bekommt dasselbe Kennzeichen mit. Ältere App-Versionen setzen kein bk: Von Personen, die den Bot gestartet haben, kommt ihre Nachricht trotzdem an; den Stopp einer älteren App erkennt das SDK am Inhalt und meldet ihn mit endChat selbst. Knopfdrücke und Inline-Anfragen aus älteren App-Versionen behandelt der Server wie normale Nachrichten (sie kommen also nur von Personen an, die den Bot gestartet haben): Dein Programm bekommt das Ereignis zwar, answerButton bzw. answerInline enden dann aber mit button_expired bzw. inline_expired. Bitte solche Personen, HideChat zu aktualisieren. Die Beiträge in Räumen und Kanälen, Startdaten von Mini-Apps (beim Prüfen mit checkWebAppData) und Meldungen sieht HideChat wie im gehosteten Modus.

Gut zu wissen

Fehler im Ende-zu-Ende-Modus

Was das Relay ablehnt, meldet das SDK als HideChatError mit diesen Codes:

CodeBedeutung
not_startedDie Person hat den Bot nicht gestartet oder wieder gestoppt oder blockiert (Status 403)
too_fastSendelimit erreicht (1 pro Sekunde und Chat, kurzzeitig 3; 30 pro Sekunde pro Bot); warte retry_after Sekunden (Status 429)
button_expiredKein offener Knopfdruck: schon beantwortet oder älter als 15 Minuten
inline_expiredKeine offene Inline-Anfrage: schon beantwortet, älter als 30 Sekunden oder Inline-Modus aus
not_e2eDer Bot läuft (noch) nicht Ende-zu-Ende oder die Schlüsseldatei passt nicht zu den bestätigten Schlüsseln: Antrag in «Meine Bots» bestätigen
bad_envelopeDer Umschlag ist ungültig (zum Beispiel an den Bot selbst oder ohne gültiges Art-Kennzeichen)
no_userDieses Konto gibt es nicht (mehr)
bot_unavailableDer Bot ist gesperrt (nach einer Entsperrung noch bis zu 30 Sekunden)
rekeyedDie Verbindung wurde geschlossen (Code 4006), weil der Bot neue Schlüssel bekommen hat oder zurück auf gehostet steht
banned, auth_failedDer Bot ist gesperrt (4004) bzw. die Anmeldung am Relay ist gescheitert (4001)

Bot-Verzeichnis, Bewertungen und Statistik

In der App unter Kanäle → Bots können Personen Bots entdecken: mit Suche, Kategorie-Chips und Sortierung nach «Beliebt», «Neu» oder «Geprüft». Aufgenommen wird nur, wer eingereicht hat und von HideChat geprüft wurde.

Einreichen

Prüfkriterien und Haken «geprüft»

Wir prüfen, ob der Bot das tut, was die Beschreibung sagt, ob die Datenschutzerklärung erreichbar ist und zum Bot passt, ob der Name nicht täuscht und ob er die Bot-Nutzungsbedingungen einhält. Wer die Prüfung besteht, kann zusätzlich den Haken «geprüft» bekommen. Den vergibt nur HideChat nach einer Kontrolle; er ist etwas anderes als das blaue Häkchen für verifizierte Personen. Offizielle Bots von HideChat tragen «offiziell».

Bewertungen

Personen, die Deinen Bot gestartet haben, können ihn mit 1 bis 5 Sternen bewerten (nicht Du selbst als Betreiber). Pro Person gibt es eine Bewertung; sie lässt sich ändern oder entfernen. Öffentlich sichtbar sind nur der Durchschnitt und die Anzahl, und erst ab 3 Bewertungen. Niemand sieht, wer wie bewertet hat, auch Du nicht. Löscht eine Person ihr Konto, verschwindet ihre Bewertung; löschst Du den Bot, verschwinden alle seine Bewertungen.

Statistik für Betreiber

Mit /statistik <bot> oder in «Meine Bots» (Karte «Statistik») siehst Du: Nutzer gesamt, aktiv in 7 Tagen, aktuell gestartet, Nachrichten rein und raus pro Tag (30 Tage), Starts, Stopps, Blockierungen, Meldungen (gesamt und offen) und die Bewertung. HideChat führt dafür Tageszähler pro Bot (90 Tage) und pro Person den Zeitpunkt des letzten Kontakts. Du bekommst nur Zahlen, keine Namen und keine Inhalte. Blockieren zählt getrennt vom Stoppen.

Automatische Sperre

Melden viele verschiedene Personen einen Bot innert kurzer Zeit oder blockieren ihn an einem Tag auffallend viele, sperrt ihn HideChat automatisch. Wenn Du die Bot-Werkstatt gestartet hast, informiert sie Dich; sonst siehst Du die Sperre in «Meine Bots». Hältst Du die Sperre für einen Fehler, schreib an support@hidechat.app. HideChat sieht sich jede automatische Sperre an und kann sie aufheben. Das gilt nicht für geprüfte und offizielle Bots. Die genauen Schwellen nennen wir nicht.

Bot-Nutzungsbedingungen

Diese Bedingungen gelten zusätzlich zu den Nutzungsbedingungen und der Datenschutzerklärung für alle, die einen Bot für HideChat betreiben («Betreiber»).

  1. Verantwortung. Du bist für Deinen Bot, seine Antworten und alle Inhalte, die er verbreitet, selbst verantwortlich. Das gilt auch für Dienste, die Dein Bot im Hintergrund nutzt.
  2. Datenschutz. Du erhältst über Deinen Bot Nachrichten und Benutzernamen von Personen. Verwende sie nur für den Zweck des Bots, schütze sie angemessen und gib sie nicht ohne Rechtsgrundlage weiter. Du bist Verantwortliche oder Verantwortlicher für diese Daten. Für die Aufnahme ins Bot-Verzeichnis ist eine eigene Datenschutzerklärung Pflicht, die Du im Bot-Profil verlinkst.
  3. Ehrliche Kennzeichnung. Gib Deinen Bot nicht als Mensch aus, verwende keine Namen, die zu einer Verwechslung mit HideChat oder dem HideChat-Team führen, und umgehe die Kennzeichnung «Bot» nicht.
  4. Nur auf Wunsch. Schreibe nur Personen, die Deinen Bot gestartet haben, und höre auf, wenn sie ihn stoppen oder blockieren. Versuche nicht, diese Sperren zu umgehen.
  5. Verboten sind Spam, Betrug und Täuschung, Schadsoftware, Belästigung, Hassrede, Inhalte, die Minderjährige gefährden oder sexualisieren, rechtswidrige Inhalte, das Sammeln von Zugangsdaten und Zahlungsdaten unter falschem Vorwand sowie das Überlasten oder Aushorchen der Schnittstelle.
  6. Schlüssel. Halte Deinen Schlüssel, das Webhook-Geheimnis und im Ende-zu-Ende-Modus die Schlüsseldatei Deines Programms geheim. Wird einer bekannt, stelle in der Bot-Werkstatt sofort einen neuen aus. Du haftest für Handlungen, die mit Deinem Schlüssel ausgeführt werden.
  7. Sperre. Wir dürfen Bots, Schlüssel und Konten bei Verstössen, vielen Meldungen oder Blockierungen, bei Gefahr für andere oder aus rechtlichen Gründen jederzeit sperren oder löschen, ohne Vorankündigung, wenn es dringend ist. Gesperrte Bots antworten auf der Schnittstelle mit 401.
  8. Verfügbarkeit. Die Schnittstelle wird ohne Gewähr bereitgestellt und kann sich ändern oder Ausfälle haben. Soweit gesetzlich zulässig, haften wir nur für Vorsatz und grobe Fahrlässigkeit.
  9. Löschen. Wenn Du Dein Konto löschst, werden auch Deine Bots gelöscht. Gelöschte Bot-Namen bleiben 30 Tage gesperrt.
  10. Verzeichnis und Bewertungen. Deine Angaben im Verzeichnis (Name, Beschreibung, Kategorie, Datenschutz-Link) müssen stimmen. Kaufe oder erfinde keine Bewertungen, bewerte Deinen eigenen Bot nicht über Zweitkonten, bitte nicht gegen Belohnung um gute Bewertungen und beeinflusse die Bewertungen anderer Bots nicht. Wer das tut, kann aus dem Verzeichnis entfernt und gesperrt werden. Den Haken «geprüft» vergibt nur HideChat und kann ihn wieder entziehen.
  11. Änderungen. Wir können diese Bedingungen anpassen. Wesentliche Änderungen kündigen wir hier und in der Bot-Werkstatt an. Es gilt das in den Nutzungsbedingungen genannte Recht.

Fragen oder Missbrauch melden: support@hidechat.app

In short (English)

Create a bot by chatting with @botwerkstatt in the HideChat app and copy the key (hcbot_<bot>_<secret>). Call https://relay.hidechat.app/bot/v1/<method> with Authorization: Bearer <key>. Methods: me, updates (after, wait up to 30 s), setWebhook, deleteWebhook, send (chat, text, reply_to, buttons, keyboard, remove_keyboard), sendMedia (multipart, up to 20 MB), sendPoll, closePoll, edit (own text messages, 48 h), delete (own messages, 48 h; also removes the file), react, typing, answerButton (once per press, 15 min), file (download media sent to the bot; counts towards 30 per second per bot), setCommands, setProfile (incl. groups, inline, miniapp), chatInfo, members, leave, answerInline, checkWebAppData. Chats: username (one-to-one), g:<gid> (group), s:<room-id> (room or channel); bots must be allowed in groups first (off by default). In groups and rooms a bot only receives commands, mentions, replies to its messages, votes on its own group polls and presses on its buttons, never other messages. Events (message incl. media, command, start, stop, button, edited, deleted, reaction, vote, added_to_group, removed_from_group, inline_query, webapp_data) are kept for 24 hours. Older app versions show buttons, keyboards, media and polls as plain text and do not apply edit/delete/react from bots; a message with a webapp or inline button is shown entirely as fallback text by app versions before this update, so send such buttons in their own message. Inline queries (search term and username) are kept like other events for at most 24 h until you fetch them, and typing @yourbot already sends the username and an empty search term after a short pause. Webhooks must be https:// and carry X-HideChat-Signature: sha256=<hex>, an HMAC-SHA256 of the raw body; verify it with a constant-time comparison. Retries after 10 s, 1 min, 5 min, 30 min and 2 h. Limits: 30 sends per second per bot, 1 per second per chat (burst 3), 20 per minute per group or room (burst 5), 5 bots per group or room, 200 groups and 200 rooms per bot, 20 bots per account (100 with Plus). Inline mode: after setProfile inline, a user can type @yourbot query in any chat; you get inline_query (from, query, offset, inline_id, never the chat) and answer once within 30 s with answerInline (up to 20 text-only results; text up to 4000 characters, id/title up to 64, description up to 120, next_offset up to 64). The «via @bot» mark is set by the sender's app. 2 queries per second per person (burst 5), plus a separate incoming bucket of 30 per second per bot that does not use up your send limit. Mini apps: set miniapp (https URL, not hidechat.app; serve it from its own (sub)domain without other sensitive pages, since the window may open any page of that origin); the app gives the page no access to chats, keys, camera, microphone or location, and files or photos only if the person picks them in the page; start data holds username, language and theme colours (no display name); webapp buttons work in one-to-one chats only and need the same origin; the page gets #hcInit=<init> and, on the phone, window.HideChat (init, theme, colors, sendData, close). In the web version it runs in a sandboxed iframe, must post {hc:'sendData', data} or {hc:'close'} to window.parent (snippet above) and must allow being framed. Verify the start data on your server with checkWebAppData (valid 24 h). The page loads directly from your server, so you see the user's IP address. Hosted bots can read the messages and media sent to them (view-once media is not accepted by bots; files expire after 7 days); the app says so in every bot chat. Bot operators are responsible for their bot, must respect users' privacy, may only write to users who started the bot, and may be banned for abuse. Builder: instead of running a server you can set up a bot in the app (Settings → My bots → your bot → Builder; in the workshop /baukasten <bot> an or aus switches it). It sends a start text with menu buttons, answers to buttons, commands and keywords, runs forms (up to 10 questions) and posts scheduled messages and RSS/Atom feed items to a channel or room. While the builder is on, one-to-one events do not reach updates or your webhook (they go to the builder only), group, room and inline events are dropped, and sending through the API still works. Limits: 50 answers, 10 forms, 20 scheduled posts, 5 feeds, 60,000 characters in total. Feeds are fetched by our server every 30 minutes, https only with the webhook address rules, at most 1 MB, at most 3 new items per fetch; the first fetch only marks existing items as seen. Form answers are stored with the bot for 30 days and shown to the owner in the app and by the workshop; unfinished forms expire after 30 minutes. The builder sets the bot's command list itself when saved. Bot directory: owners submit a bot (category 1–7) via «Meine Bots» or /verzeichnis <bot> in the workshop; it needs a description and a privacy-policy link (setProfile field privacy, or /datenschutz). HideChat reviews it, usually within a few days, and may give it the «geprüft» (checked) badge, which is not the blue tick for verified people. Ratings: 1–5 stars from people who started the bot (not the owner), one per person, shown publicly only as average and count from 3 ratings; nobody sees who rated. Owners see statistics (/statistik): numbers only, no names or contents. Bots that get many reports or blocks are banned automatically and can be reviewed by us; buying or faking ratings is forbidden. SDK: the package hidechat-bot for Node.js 20+ (TypeScript types) and Python 3.10+ wraps all methods with the same field names and error codes, verifies webhooks (verifyWebhook / verify_webhook) and supports both modes. Install it from https://hidechat.app/entwickler/sdk/hidechat-bot-0.1.0.tgz (npm) or https://hidechat.app/entwickler/sdk/hidechat_bot-0.1.0-py3-none-any.whl (pip) and check SHA256SUMS; npm and PyPI packages will follow. End-to-end mode: your program creates its own keys (hidechat-bot keys), requests the switch (hidechat-bot register, method setE2e, answer pending with a fingerprint = first 16 hex characters of SHA-256 over <box_pub>:<sign_pub>), and the owner confirms it in the app (Settings → My bots → bot → Mode) after comparing the fingerprint. Then HideChat cannot read one-to-one messages with the bot; the app shows «Bot · Ende-zu-Ende verschlüsselt. Nur der Betreiber kann mitlesen, HideChat nicht.» Only the owner can switch back to hosted (app or /modus <bot> gehostet; setHosted returns 403 owner_only). Not available in end-to-end mode: private groups, the builder and official bots; rooms and channels are never end-to-end encrypted and keep using the API. Events not yet fetched are lost when switching. Keep the key file and the .hidechat-bot state folder out of Git; losing the key file means new keys, and unopened messages to the old keys stay unreadable. Confirming a key change or a mode switch discards all messages still waiting at the relay for your program, so let it fetch everything first. After a key change pass the old file as previousKeys for about 7 days; this only helps with messages people send afterwards from apps that still have the old keys cached. With older app versions, button presses and inline queries are treated as normal messages (so they only arrive from people who started the bot), and answerButton and answerInline return button_expired or inline_expired; ask those users to update. Run one program per bot. HideChat still sees an unencrypted kind tag (bk) on every envelope to or from the bot (start, stop, block, message, button press, inline query, answer), so it knows who starts, stops or blocks the bot and when and how many messages flow, but no content. Media uploads count towards the 600 MB daily quota even if delivery is refused. Contact: support@hidechat.app.