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": "…" }.
| Methode | Parameter | Ergebnis (result) |
|---|---|---|
me | keine | username, 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) |
updates | after (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. |
setWebhook | url (nur https://, höchstens 512 Zeichen) | secret (neu bei jedem Aufruf; das alte ist sofort ungültig). Zugestellt werden Ereignisse ab diesem Zeitpunkt. |
deleteWebhook | keine | true. Danach funktioniert updates wieder. |
send | chat (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. |
sendMedia | multipart/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 |
edit | chat, mid, text (optional, 1 bis 4000 Zeichen), buttons (optional); mindestens eines von beiden. Siehe Bearbeiten. | true |
delete | chat, mids (Liste mit 1 bis 100 Nachrichten-IDs) | { "deleted": <Anzahl> } |
react | chat, mid, emoji (eines von ❤️ 👍 😂 😮 😢 🔥, oder null zum Entfernen) | true |
typing | chat, action (typing, recording oder uploading) | true. Siehe Tippt …. |
chatInfo | chat | Im 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). |
members | chat (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). |
leave | chat (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). |
answerButton | button_id (aus dem button-Ereignis), text (optional, höchstens 200 Zeichen), alert (optional, true/false) | true. Einmal pro Knopfdruck, höchstens 15 Minuten danach. |
sendPoll | chat, 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 |
closePoll | chat, mid der eigenen Umfrage | true. Ein zweiter Aufruf für dieselbe Umfrage ist erlaubt und ändert nichts. |
file | file_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. |
setCommands | commands: 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 /. |
setProfile | name (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 willst | true |
answerInline | inline_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. |
checkWebAppData | init (die Startdaten, die Deine Mini-App bekommen hat) | { bot, user, lang, theme, at }, plus name, falls bekannt |
endChat | chat (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). |
setE2e | box_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 }. |
setHosted | keine | Immer 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:
data(1 bis 64 Zeichen): ein Rückruf. Tippt jemand den Knopf, bekommst Du einbutton-Ereignis mit diesem Wert.url: ein Link. Nurhttps://, höchstens 512 Zeichen, ohne Benutzername und Passwort, ohne Leerraum und ohne unsichtbare Zeichen, Host nur aus ASCII-Zeichen (Umlaute im Host schreibst Du alsxn--…). Die App fragt vor dem Öffnen nach und zeigt den Host gross an.inline(0 bis 64 Zeichen): ein Inline-Wechsel-Knopf. Tippt jemand ihn, setzt die App im aktuellen Chat@DeinBot <Vorgabe>ins Eingabefeld. Es öffnet sich kein Chat-Wähler. Siehe Inline-Modus.webapp: ein Mini-App-Knopf, der Deine Mini-App öffnet. Nur im Einzelchat (in Gruppen und Räumen400 unsupported_chat), und die Adresse muss dieselbe Herkunft haben wie dieminiappDeines Bots (gleiches Schema, gleicher Host, gleicher Port), sonst400 bad_buttons.
Ä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."}'
- Jeder Knopfdruck lässt sich nur einmal beantworten und höchstens 15 Minuten lang. Danach:
404 button_expired. - Knöpfe unter Nachrichten, die älter als 48 Stunden sind, lösen kein
button-Ereignis mehr aus: solche Knopfdrücke werden ignoriert. - Die App wartet höchstens 15 Sekunden auf die Antwort. Dann endet der Ladekreis ohne Fehlermeldung.
- Es zählen nur
data-Werte, die Du selbst gesendet hast und die in der aktuellen Fassung der Nachricht stehen. Erfundene oder überholte Rückrufe und Link-Knöpfe erzeugen kein Ereignis.
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..." } }
| kind | Erlaubte Typen (Content-Type des Teils file) |
|---|---|
photo | image/jpeg, image/png, image/webp, image/gif; der Inhalt muss zum Typ passen |
video | video/mp4, video/quicktime |
voice | audio/mp4, audio/m4a, audio/aac, audio/mpeg, audio/ogg, audio/webm |
file | beliebiger Typ (höchstens 120 Zeichen); der Dateiname ist Pflicht (höchstens 200 Zeichen, eine Zeile, ohne unsichtbare Zeichen) |
- Höchstens 20 MB pro Datei (sonst
413 too_large). Zusätzlich gilt das Tageskontingent von 600 MB pro Bot und Tag (sonst429 quota). - Falscher Typ, nicht passender Inhalt, fehlende Datei oder fehlender Dateiname:
400 bad_media. Dann entstehen weder eine Nachricht noch eine gespeicherte Datei. captionist der Bildtext (höchstens 1024 Zeichen, sonstbad_caption).buttonskommt als JSON-Text, mit denselben Regeln wie beisend.- HideChat verschlüsselt die Datei wie die App. Auf dem Server liegt sie höchstens 7 Tage. Mit
deletelöschst Du die Nachricht samt Datei sofort, solange sie höchstens 48 Stunden alt ist; danach läuft die Datei nach 7 Tagen von selbst ab. Bearbeiten lassen sich Medien nicht (not_editable).
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
edit: nur eigene Textnachrichten (gesendet mitsend) im selben Chat, höchstens 48 Stunden alt. Gibtext,buttonsoder beides an. Ohnetextbleibt der Text; ohnebuttonswerden die Knöpfe entfernt ("buttons": []und"buttons": nullebenso). Einkeyboard-Feld gibt es nicht. Medien und Umfragen sind nicht bearbeitbar (400 not_editable).delete: löscht bis zu 100 eigene Nachrichten im Chat (höchstens 48 Stunden alt) bei der Person, ohne Hinweis «gelöscht». Ist keine dermidseine eigene Nachricht, kommt404 no_message.react: eine Reaktion aus ❤️ 👍 😂 😮 😢 🔥 auf eine Nachricht im Chat;"emoji": nullentfernt Deine Reaktion. Eine ungültigemidgibt400 bad_mid.- Nachrichten von Personen kannst Du nicht ändern. Dafür bekommst Du die Ereignisse
edited,deletedundreaction, wenn eine Person ihre Nachricht bearbeitet, löscht oder darauf reagiert.
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
- Die Person tippt
@DeinBotund einen Suchbegriff. Die App wartet 400 Millisekunden nach dem letzten Tastendruck, damit nicht jeder Buchstabe eine Anfrage auslöst. Schon@DeinBotmit 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.» - Du bekommst ein
inline_query-Ereignis:{ "type": "inline_query", "from": "marcel", "query": "wetter bern", "offset": "", "inline_id": "…" }. Das Ereignis enthält nur Person, Suchbegriff,offsetundinline_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. - 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
- Höchstens 20 Ergebnisse pro Antwort. Jedes hat
id(1 bis 64 Zeichen, eindeutig in der Antwort),title(1 bis 64 Zeichen),text(der Text der Nachricht, höchstens 4000 Zeichen) und optionaldescription(höchstens 120 Zeichen). - Ergebnisse sind nur Text: keine Vorschaubilder (sie würden beim Laden die IP-Adresse der Person an Dich weitergeben) und keine Knöpfe.
next_offset(optional, höchstens 64 Zeichen): Gibt esnext_offset, zeigt die App am Ende der Liste den Knopf «Mehr laden». Tippt die Person darauf, schickt die App eine neue Anfrage mit diesem Wert alsoffsetund hängt die neuen Ergebnisse an. Ohnenext_offsetist die Liste zu Ende.- Das Limit für Anfragen gilt pro Person: 2 pro Sekunde (kurzzeitig bis 5). Dazu kommt ein eigener Eimer für Eingehendes von 30 pro Sekunde pro Bot. Er ist vom Sendelimit Deines Bots getrennt: Anfragen und
webapp_dataverbrauchen Deine 30 Sendungen pro Sekunde nicht, und Deine Sendungen blockieren sie nicht. Darüber hinaus wird eine Anfrage still verworfen.
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
- Knopf «App öffnen»: Ist
miniappgesetzt, zeigt die App im Chat mit Deinem Bot neben dem Befehlsmenü den Knopf «App öffnen». - Mini-App-Knopf: Unter einer Nachricht hängst Du einen Knopf
{ "text": "Bestellen", "webapp": "https://shop.example.com/app" }an. Solche Knöpfe gibt es nur im Einzelchat, weil die Antwort einer Person zugeordnet sein muss. Die Adresse des Knopfs muss dieselbe Herkunft haben wieminiapp(Schema, Host und Port); sonst antwortet die Schnittstelle mit400 bad_buttons.
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
- Einbetten erlauben. Deine Seite darf das Einbetten nicht verbieten: kein
X-Frame-Options: DENY(oderSAMEORIGIN) und keine einschränkendeContent-Security-Policy: frame-ancestors. Sonst bleibt das Fenster in der Web-Version leer. Auf dem Handy spielt das keine Rolle. - Navigation. Führt ein Link zu einer anderen Herkunft, fragt die App nach und öffnet ihn im System-Browser. In der Web-Version kann die Seite im
iframeselbst navigieren und Pop-ups öffnen (allow-popups), ohne dass HideChat nachfragt. - Keine fremden Frames einbetten. Auf iOS blockiert die App fremde Unterframes. Auf sehr alten Android-WebViews könnten eingebettete fremde
iframes Nachrichten an die Brücke schicken. Binde deshalb keine fremdeniframes in Deine Mini-App ein. - Datenschutz. Die App lädt die Seite direkt von Deinem Server: Du siehst IP-Adresse und Geräteangaben der Person, und Deine Datenschutzerklärung gilt (siehe Bot-Nutzungsbedingungen).
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?
- Gruppe: ein Admin der Gruppe, in der App unter «Bot hinzufügen» (mit Rückfrage und Hinweis). Dein Bot bekommt dann das Ereignis
added_to_group. Bots sind in Gruppen nie Admins und können niemanden hinzufügen oder entfernen. - Raum oder Kanal: ein Raum-Admin mit dem Recht «Bots». Er nimmt den Bot als normales Mitglied oder als Admin auf (in einem Kanal und in Räumen mit «nur Admins schreiben» darf nur ein Admin-Bot posten). Auch als Admin hat ein Bot-Konto keine Verwaltungsrechte: Es kann schreiben, aber nicht moderieren, sperren oder Einstellungen ändern.
- Beim Hinzufügen bekommen alle Mitglieder einen Hinweis, dass Dein Bot Befehle und Erwähnungen mitliest und Du als Betreiber diese lesen kannst. Aktuelle App-Versionen zeigen ihn ausserdem dauerhaft in der Gruppen- oder Raum-Info, und Nachrichten des Bots tragen dort das Abzeichen «Bot»; ältere App-Versionen zeigen nur den Hinweis beim Hinzufügen.
- Mit
memberssiehst Du, wer dabei ist (in Gruppen alle Mitglieder mit Admin-Angabe, in Kanälen die Abonnenten nur als Admin). Die Mitglieder werden in der Datenschutzerklärung darüber informiert; frag nur ab, was Dein Bot wirklich braucht.
Chat-IDs und Feld from
Das Feld chat (in Ereignissen und in Deinen Aufrufen) hat drei Formen:
| Form | Chat-Art |
|---|---|
marcel | Einzelchat 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?
| Methode | Einzelchat | Gruppe | Raum / Kanal |
|---|---|---|---|
send | ja | ja, ohne keyboard | ja, ohne keyboard und buttons; mit topic |
sendMedia | ja | ja | nein |
sendPoll, closePoll | ja | ja | ja (anonym) |
edit, delete, react | ja | ja | ja (edit ohne buttons) |
typing | ja | nein | nein |
chatInfo | ja (nach Start) | ja | ja |
members, leave | nein | ja | ja |
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:
- Befehle ohne Ziel (
/wetter) oder mit Ziel auf Deinen Bot (/wetter@wetterbot). - Erwähnungen (
@wetterbotim Text, nicht als Teil eines Wortes oder einer E-Mail-Adresse). - Antworten auf Nachrichten Deines Bots.
- Stimmen bei Umfragen Deines Bots, nur in Gruppen. In Räumen und Kanälen bleiben Umfragen anonym, dort gibt es kein
vote-Ereignis. - 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
- Themen: In Räumen mit Themen trägt das Ereignis
topic(Nummer des Themas; fehlt bei «Allgemein»). Mitsendgibst Dutopicselbst an. Ohnetopic, aber mitreply_to, landet Deine Antwort im Thema des beantworteten Beitrags. Ein unbekanntes Thema gibt400 bad_topic, ein geschlossenes403 topic_closed. - Raum-Regeln gelten auch für Bots: «nur Admins schreiben» (
403 admins_only), Stummschaltung (403 muted), Langsam-Modus (429 too_fastmitretry_after), Sperrliste (400 blocked_content). Wurde der Raum gelöscht, gibt es410 room_removed. Fehlt dem Bot ein Recht (zum Beispielmembersin einem Kanal als Nicht-Admin):403 forbidden.
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
- Höchstens 5 Bots pro Gruppe und pro Raum.
- Höchstens 200 Gruppen und 200 Räume pro Bot; darüber wird der Bot nicht mehr aufgenommen.
- Höchstens 20 Sendungen pro Minute pro Gruppe oder Raum (kurzzeitig bis 5 hintereinander). Sie zählen zusätzlich zu den 30 Sendungen pro Sekunde des Bots. Darüber:
429 too_fastmitretry_after.chatInfo,membersundleavezählen nicht. - Pro Person, die den Bot hinzufügt: höchstens 10 Aufnahmen pro Stunde.
- Eine Gruppennachricht wird einzeln für jedes Mitglied verschlüsselt und in Paketen zu 50 zugestellt; in grossen Gruppen kommt sie deshalb nicht bei allen im selben Augenblick an.
Bekannte Grenzen in Gruppen
- Hat ein Mitglied Deinen Bot blockiert, bekommt es für Gruppennachrichten Deines Bots unter Umständen trotzdem eine Mitteilung; der Inhalt wird auf seinem Gerät verworfen und nicht angezeigt.
- Erstellt ein Mitglied neue Schlüssel (neue 12 Wörter), kann es die Nachrichten Deines Bots in dieser Gruppe erst wieder lesen, wenn ein Admin die Gruppenangaben das nächste Mal verschickt (zum Beispiel beim Hinzufügen oder Entfernen eines Mitglieds).
- Entfernt ein Admin mit einer älteren App-Version Deinen Bot, kommt
removed_from_groupunter Umständen erst, wenn Dein Bot wieder in die Gruppe schreibt: Dann schickt ihm die App eines Admins mit aktueller Version die neuen Angaben.
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.
| type | Wann | Zusätzliche Felder |
|---|---|---|
start | Eine Person tippt auf «Starten» (auch nach einem Stopp) | param: Wert aus dem Link …/b/<bot>?start=<wert>, falls vorhanden und gültig |
stop | Eine Person stoppt den Bot (nur, wenn sie ihn vorher gestartet hatte) | keine. Danach kannst Du ihr nicht mehr schreiben, bis sie wieder startet. |
message | Eine Person schreibt einen normalen Text | text (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) |
command | Der Text beginnt mit /, zum Beispiel /wetter Bern | command (klein geschrieben, ohne /: wetter), args (Rest des Textes, Bern), text (voller Text), mid, reply_to (falls vorhanden) |
button | Eine Person tippt einen Rückruf-Knopf Deiner Nachricht | mid (Deine Nachricht), data, button_id (für answerButton) |
edited | Eine Person bearbeitet eine ihrer Nachrichten | mid, text (neuer Text) |
deleted | Eine Person löscht Nachrichten für beide | mids (Liste) |
reaction | Eine Person reagiert auf eine Nachricht | mid, emoji (null = Reaktion entfernt) |
inline_query | Eine Person tippt @DeinBot mit einem Suchbegriff (Inline-Modus an; auch ohne Start, ohne Chat) | from, query, offset, inline_id (für answerInline) |
webapp_data | Eine Mini-App schickt mit sendData Daten (nur von Personen, die den Bot gestartet haben) | chat, data (höchstens 4096 Zeichen) |
vote | Eine 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_group | Der Bot wurde in eine Gruppe (g:<id>) oder einen Raum/Kanal (s:<id>) aufgenommen | from (wer ihn hinzugefügt hat), title, chat_type (group, room, channel) |
removed_from_group | Der Bot ist nicht mehr Mitglied | from (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
- Die Adresse muss mit
https://beginnen. Nicht erlaubt sindlocalhost, interne Namen (.local,.internal, Namen ohne Punkt), IP-Adressen aus privaten oder lokalen Bereichen und Adressen mit Benutzername oder Passwort. Dann antwortetsetWebhookmitbad_webhook. - HideChat schickt jedes Ereignis einzeln als
POSTmit JSON (Aufbau wie oben, mitid) und dem KopfX-HideChat-Signature. Die Ereignisse kommen der Reihe nach. - Antworte innerhalb von 10 Sekunden mit einem Status 200 bis 299. Alles andere (auch Weiterleitungen, Fehler und Zeitüberschreitung) zählt als Fehlschlag.
- Bei einem Fehlschlag versucht HideChat es nach 10 Sekunden, 1 Minute, 5 Minuten, 30 Minuten und 2 Stunden erneut. Danach wird das Ereignis verworfen. Solange ein Ereignis wiederholt wird, warten die folgenden.
- Du kannst Ereignisse mit gleicher
idmehrfach bekommen. Verarbeite sie am besten so, dass doppelte Zustellung nichts kaputt macht.
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.
| Status | error | Bedeutung |
|---|---|---|
| 401 | unauthorized | Schlü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 |
| 404 | not_found | Diese Methode gibt es nicht |
| 405 | method_not_allowed | Die Methode verlangt POST |
| 400 | bad_json | Der Inhalt ist kein JSON-Objekt |
| 413 | too_large | Der JSON-Inhalt ist grösser als 100 000 Zeichen, oder die Datei bei sendMedia ist grösser als 20 MB |
| 400 | bad_after | after ist keine Zahl ab 0 |
| 400 | bad_wait | wait liegt nicht zwischen 0 und 30 |
| 409 | webhook_active | Ein Webhook ist gesetzt; erst deleteWebhook aufrufen |
| 400 | bad_webhook | Webhook-Adresse ungültig (kein https://, lokale oder private Adresse, zu lang) |
| 400 | bad_chat | chat ist weder ein Benutzername (Einzelchat) noch g:<Gruppen-ID> noch s:<Raum-ID> |
| 400 | bad_text | text fehlt, ist leer oder länger als 4000 Zeichen |
| 400 | bad_reply | reply_to ist keine gültige Nachrichten-ID |
| 403 | not_started | Die Person hat den Bot nicht gestartet oder wieder gestoppt (gilt für jede Methode, die an eine Person geht) |
| 429 | too_fast | Zu viele Nachrichten, file-Abrufe oder gleichzeitig wartende updates-Anfragen. Warte retry_after Sekunden (steht zusätzlich in der Antwort) |
| 404 | no_user | Dieses Konto gibt es nicht (mehr) oder es ist gesperrt |
| 404 | no_bot | Diesen Bot gibt es nicht |
| 400 | bad_name | name fehlt oder ist länger als 40 Zeichen |
| 409 | reserved_name | name enthält ein reserviertes Wort (hidechat, support, official, offiziell, admin, werkstatt, gross oder klein geschrieben) |
| 400 | bad_about | about ist länger als 300 Zeichen |
| 400 | bad_welcome | welcome ist länger als 500 Zeichen |
| 400 | bad_commands | commands ist keine gültige Liste (höchstens 30, Regeln siehe setCommands, keine doppelten Namen) |
| 400 | bad_buttons | buttons 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) |
| 400 | bad_keyboard | keyboard ungültig (Reihen, Beschriftungen, hint höchstens 64 Zeichen, once true/false) |
| 404 | no_message | Die Nachricht gibt es nicht: nur eigene Nachrichten in diesem Chat, höchstens 48 Stunden alt (bei closePoll: nur eigene Umfragen) |
| 400 | not_editable | Nur Textnachrichten (send) lassen sich bearbeiten, keine Medien oder Umfragen |
| 400 | bad_edit | edit braucht text oder buttons |
| 400 | bad_reaction | emoji ist keines von ❤️ 👍 😂 😮 😢 🔥 und nicht null |
| 400 | bad_mids | mids ist keine Liste mit 1 bis 100 Nachrichten-IDs |
| 400 | bad_mid | mid ist keine gültige Nachrichten-ID |
| 404 | button_expired | Der Knopfdruck ist unbekannt, schon beantwortet oder älter als 15 Minuten |
| 400 | bad_answer | answerButton: text länger als 200 Zeichen oder alert nicht true/false |
| 400 | bad_action | action ist nicht typing, recording oder uploading |
| 400 | unsupported_chat | Die 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) |
| 403 | not_member | Der Bot ist nicht (mehr) Mitglied dieser Gruppe oder dieses Raums: entfernt, selbst gegangen (leave) oder nie aufgenommen |
| 403 | admins_only | Raum: In diesem Kanal oder dieser Gruppe dürfen nur Admins schreiben (ein Raum-Admin kann den Bot als Admin hinzufügen) |
| 403 | muted | Raum: Der Bot ist dort vorübergehend stummgeschaltet |
| 400 | bad_topic | Raum: topic ist keine Nummer eines bestehenden Themas (0 = Allgemein) |
| 403 | topic_closed | Raum: Das Thema ist geschlossen |
| 410 | room_removed | Den Raum oder Kanal gibt es nicht mehr |
| 400 | blocked_content | Raum: Der Inhalt enthält gesperrte Begriffe |
| 403 | forbidden | Raum: Dafür fehlt dem Bot das Recht, zum Beispiel members in einem Kanal nur als Admin |
| 400 | bad_groups | setProfile: groups ist nicht true oder false |
| 403 | inline_off | answerInline: Der Inline-Modus des Bots ist aus |
| 410 | inline_expired | answerInline: Die Anfrage ist schon beantwortet oder älter als 30 Sekunden |
| 400 | bad_results | answerInline: results oder next_offset ungültig |
| 400 | bad_inline | setProfile: inline ist kein Platzhalter von 1 bis 64 Zeichen (einzeilig) und nicht null; answerInline: unbekannte inline_id |
| 400 | bad_miniapp | setProfile: 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 |
| 400 | bad_webapp_data | checkWebAppData: Startdaten ungültig, falsch signiert oder für einen anderen Bot |
| 400 | webapp_expired | checkWebAppData: Startdaten sind älter als 24 Stunden |
| 400 | bad_privacy | setProfile: privacy ist keine gültige https-Adresse (höchstens 512 Zeichen, ohne Zugangsdaten) und nicht null |
| 400 | bad_category | Verzeichnis: Kategorie unbekannt (erlaubt: werkzeuge, nachrichten, unterhaltung, spiele, lernen, firmen, sonstiges) |
| 400 | need_about | Verzeichnis: Der Bot braucht zuerst eine Beschreibung |
| 400 | need_privacy | Verzeichnis: Der Bot braucht zuerst einen Link zur Datenschutzerklärung (privacy) |
| 409 | already_pending | Verzeichnis: Der Bot ist schon eingereicht und wird geprüft |
| 403 | banned | Verzeichnis: Ein gesperrter Bot kann nicht eingereicht werden |
| 409 | not_pending | Verzeichnis (Team): Der Bot ist nicht in Prüfung |
| 409 | not_listed | Verzeichnis (Team): Der Bot steht nicht im Verzeichnis |
| 403 | own_bot | Bewertung: Den eigenen Bot kann man nicht bewerten |
| 400 | bad_stars | Bewertung: stars muss eine ganze Zahl von 0 bis 5 sein |
| 400 | bad_poll | Umfrage 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) |
| 400 | bad_media | sendMedia: 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 |
| 400 | bad_caption | caption ist länger als 1024 Zeichen |
| 429 | quota | Das Tageskontingent für Medien (600 MB pro Tag) ist aufgebraucht |
| 404 | no_file | file: unbekannte file_id oder älter als 7 Tage |
| 500 | bot_secret_missing | Der Server ist nicht vollständig eingerichtet. Versuche es später, sonst melde Dich beim Support |
| 409 | e2e_mode | Im 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 |
| 409 | builder_on | setE2e: Schalte zuerst den Baukasten aus. Er geht nur im gehosteten Modus |
| 409 | in_groups | setE2e: Der Bot ist noch in privaten Gruppen. Verlass sie zuerst mit leave; Ende-zu-Ende-Bots können noch nicht in Gruppen |
| 400 | bad_keys | setE2e: box_pub und sign_pub müssen je 32 Byte (Base64) sein, verschieden und nicht die bisherigen Schlüssel des Bots |
| 400 | bad_proof | setE2e: proof ist nicht die Ed25519-Signatur von hidechat-bot-e2e:<bot>:<box_pub>:<sign_pub> mit dem neuen Signierschlüssel |
| 403 | official_bot | setE2e: Offizielle Bots bleiben gehostet. Ein gesperrter Bot bekommt 403 banned |
| 403 | owner_only | setHosted: Zurück auf gehostet stellst Du als Besitzer in «Meine Bots» oder mit /modus <bot> gehostet in der Bot-Werkstatt um |
| 400 | use_sdk | App («Meine Bots»): Ende-zu-Ende schaltest Du mit dem SDK ein, Dein Programm erzeugt die Schlüssel. Kommt auch, wenn der Antrag abgelaufen ist |
| 409 | no_pending | App («Meine Bots»): Der Fingerabdruck passt nicht zum offenen Antrag (er wurde inzwischen ersetzt). Neu laden und noch einmal vergleichen |
| – | not_e2e | SDK: 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) |
| 503 | unavailable | Unerwarteter Fehler auf dem Server. Versuche es nach einigen Sekunden erneut |
Limits
| Was | Grenze |
|---|---|
| Bots pro Konto | 20, mit aktivem HideChat Plus 100 |
| Gruppen und Räume | Hö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 |
| Senden | 30 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-Anfragen | 2 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-Apps | Adresse 512 Zeichen; Startdaten 24 Stunden gültig; sendData höchstens 4096 Zeichen und einmal pro Öffnen. Siehe Mini-Apps |
| Dateien abrufen | file zählt zum Limit von 30 pro Sekunde pro Bot (nicht pro Chat). Darüber: 429 too_fast mit retry_after |
| Ereignisse | 24 Stunden aufbewahrt; updates liefert höchstens 100 pro Antwort |
| Long-Polling | wait höchstens 30 Sekunden; höchstens 10 gleichzeitig wartende Anfragen pro Bot (weitere mit wait bekommen 429 too_fast mit retry_after) |
| Webhook | 10 Sekunden Zeit pro Zustellung; Wiederholungen nach 10 Sekunden, 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, danach verworfen |
| Medien | Hö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 Tastatur | Höchstens 8 Reihen mit je 4; Beschriftung 40 Zeichen; data 64 Zeichen; url 512 Zeichen; hint 64 Zeichen |
| Umfragen | Frage 300 Zeichen; 2 bis 10 Antworten zu je 100 Zeichen |
| Bearbeiten und Löschen | Nur eigene Nachrichten, höchstens 48 Stunden alt; Löschen bis 100 Nachrichten pro Aufruf |
| Knopf-Antwort | Einmal 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) |
| Texte | Gesendet bis 4000 Zeichen; empfangen bis 16 000 Zeichen |
| Baukasten | 50 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 |
| Profil | Name 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.
Links zu Deinem Bot
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
- Öffne Einstellungen → Meine Bots, tippe auf Deinen Bot und dann bei der Karte «Baukasten» auf «Baukasten öffnen». Schalte «Baukasten verwenden» ein, fülle die Abschnitte aus und tippe auf «Speichern». Die Antworten auf Deine Formulare siehst Du im Abschnitt «Eingänge».
- In der Bot-Werkstatt:
/baukasten <bot>zeigt, ob er an ist,/baukasten <bot> anund/baukasten <bot> ausschalten ihn um. Einschalten geht nur, wenn schon etwas eingerichtet ist. Die Einrichtung selbst geschieht nur in der App. - Ist der Starttext leer, nimmt der Baukasten den Willkommenstext des Profils (
setProfile, Feldwelcome). - Den Baukasten gibt es nur im gehosteten Modus, nicht im Ende-zu-Ende-Modus. In «Meine Bots» steht dann: «Der Baukasten geht nur im gehosteten Modus.»
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
startsendet den Starttext mit allen Antworten, die einen «Knopf im Menü» haben (2 pro Reihe, höchstens 16 Knöpfe)./menuzeigt das Menü erneut,/abbrechenbricht ein Formular ab.- Freier Text löst die erste Antwort (in der Reihenfolge der Liste) aus, deren Stichwort als ganzes Wort oder Wortfolge vorkommt; gross und klein ist egal. Ein Befehl
/<befehl>löst die erste Antwort mit diesem Befehl aus. Passt nichts, kommt «Wenn nichts passt» (falls gesetzt), sonst «Das habe ich nicht verstanden.» mit dem Menü. - Eine Antwort ist entweder ein Text oder ein Formular. Im Formular gilt jeder Text als Antwort auf die aktuelle Frage (1 bis 1000 Zeichen); danach kommt der Dankestext. Ein unfertiges Formular verfällt nach 30 Minuten.
- Medien, Umfrage-Stimmen, Bearbeiten, Löschen, Reaktionen und Mini-App-Daten beantwortet der Baukasten nicht.
- Befehlsliste: Beim Speichern mit eingeschaltetem Baukasten setzt HideChat die Befehle Deines Bots selbst: jede Antwort mit einem Befehl (Erklärung: der Knopf-Text, sonst die ersten 80 Zeichen der Antwort, sonst der Formular-Titel), dazu
menu(wenn es Menü-Knöpfe gibt) undabbrechen(wenn es Formulare gibt). Eine frühere Liste wird dabei ersetzt; beim Ausschalten bleibt sie stehen.
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
- Der HideChat-Server ruft die Feed-Adresse alle 30 Minuten ab und postet höchstens 3 neue Einträge pro Abruf (älteste zuerst) als Titel und Link in den gewählten Kanal oder Raum.
- Der erste Abruf nach dem Hinzufügen markiert alle vorhandenen Einträge nur als gesehen und postet nichts. Ändert sich die Adresse, zählt das als neuer Feed.
- Nur
https://, mit denselben Adressregeln wie beim Webhook (keinelocalhost- oder privaten IP-Adressen, keine Weiterleitungen). Antwort höchstens 1 MB, Zeitlimit 10 Sekunden. Fehler stehen beim Feed (zum Beispiel «nicht erreichbar» oder «kein gültiger Feed»).
Grenzen
| Was | Grenze |
|---|---|
| Starttext / «Wenn nichts passt» | 2000 / 500 Zeichen |
| Antworten | Hö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 |
| Formulare | Höchstens 10; Titel 60 Zeichen; 1 bis 10 Fragen zu je 300 Zeichen; Dankestext 500 Zeichen; Antwort der Person bis 1000 Zeichen |
| Geplante Beiträge | Höchstens 20; Text 2000 Zeichen |
| Feeds | Höchstens 5; Abruf alle 30 Minuten, höchstens 3 Einträge pro Abruf |
| Gesamtgrösse | Die Einrichtung darf höchstens 60 000 Zeichen gross sein |
| Formular-Antworten | 30 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
| Funktion | Im Ende-zu-Ende-Modus |
|---|---|
| Text, Befehle, Antworten, Start mit Startwert | Geht; der Inhalt steckt nur im verschlüsselten Umschlag (auch der Startwert). |
Knöpfe, Antwort-Tastatur, answerButton | Geht; 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, file | Geht; das SDK verschlüsselt und entschlüsselt die Dateien selbst. Das Tageskontingent von 600 MB gilt weiter. |
Umfragen, Stimmen, closePoll | Geht; die Stimmen prüft das SDK. |
| Bearbeiten, Löschen, Reaktionen | Geht. |
| Inline-Modus | Geht; eine Antwort je Anfrage innert 30 Sekunden. |
| Mini-Apps | Geht; 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/Blockieren | Bleibt 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, Bewertungen | Bleibt 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). |
| Baukasten | Geht 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 Bots | Bleiben 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:
- Antrag durch das Programm.
registerruftsetE2emit 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. - 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
- Die Schlüsseldatei (
hidechat-keys.json) und der Ordner.hidechat-botgehören nie in Git, nie in einen Chat und nie in ein Backup, auf das andere Zugriff haben. Trag beide in.gitignoreein und gib die Datei über eine Umgebungsvariable (HIDECHAT_KEYS) an. - Wer die Schlüsseldatei hat, kann alle Nachrichten an Deinen Bot lesen. Ist sie bekannt geworden, erzeuge sofort neue Schlüssel (
keys,register, bestätigen) und stell in der Werkstatt einen neuen Bot-Schlüssel aus. - Verlust: HideChat hat keine Kopie. Ist die Datei weg, erzeugst Du neue Schlüssel und beantragst sie wie oben. Nachrichten, die an die alten Schlüssel geschickt wurden und noch nicht geöffnet sind, bleiben dann unlesbar.
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
- Zurück auf gehostet stellst nur Du als Besitzer um: in «Meine Bots» (Karte «Betriebsart», «Auf gehostet umstellen») oder in der Werkstatt mit
/modus <bot> gehostet./modus <bot>zeigt den aktuellen Modus und einen offenen Antrag. Über die Schnittstelle geht es nicht:setHostedantwortet mit403 owner_only, sonst könnte ein gestohlener Bot-Schlüssel wieder mitlesen. Beim Zurückstellen erzeugt HideChat neue Schlüssel für den Bot; das laufende Programm endet mitrekeyedund muss danach im gehosteten Modus laufen. - Noch nicht abgeholte Ereignisse gehen beim Umschalten verloren, in beide Richtungen. Hol sie vorher ab. Beim Wechsel nach Ende-zu-Ende löscht HideChat alle Klartext-Reste beim Bot (Ereignisse, Dateien, gemerkte Nachrichten). Formular-Antworten aus dem Baukasten («Eingänge») aus der gehosteten Zeit bleiben bis zu 30 Tage gespeichert oder bis Du sie löschst.
- Personen sehen nach dem Umschalten beim nächsten Öffnen des Bot-Chats einen Hinweis («Dieser Bot ist jetzt Ende-zu-Ende verschlüsselt. …» bzw. «Dieser Bot läuft jetzt über HideChat. …») und dass sich die Sicherheitsnummer geändert hat.
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
- Medien-Kontingent: Das SDK lädt eine Datei verschlüsselt hoch, bevor das Relay die Zustellung prüft. Die 600 MB pro Tag zählen deshalb auch, wenn die Zustellung abgelehnt wird (zum Beispiel
not_started); die Datei wird dann gleich wieder gelöscht. - Nach einer Entsperrung kann das Relay noch bis zu 30 Sekunden
bot_unavailablemelden. - Personen ohne Start: Der Server stellt Nachrichten Deines Bots nur zu, wenn die Person ihn gestartet und nicht gestoppt oder blockiert hat (Ausnahme: die Antwort auf eine Inline-Anfrage innert 30 Sekunden). Ein Bot kann seine Reichweite mit
endChatverkleinern, nie vergrössern. - Im Ende-zu-Ende-Modus zählt das SDK die Ereignisnummern (
id) selbst. Raum-Ereignisse holt es nebenbei überupdatesab (abschalten mitrooms: false).
Fehler im Ende-zu-Ende-Modus
Was das Relay ablehnt, meldet das SDK als HideChatError mit diesen Codes:
| Code | Bedeutung |
|---|---|
not_started | Die Person hat den Bot nicht gestartet oder wieder gestoppt oder blockiert (Status 403) |
too_fast | Sendelimit erreicht (1 pro Sekunde und Chat, kurzzeitig 3; 30 pro Sekunde pro Bot); warte retry_after Sekunden (Status 429) |
button_expired | Kein offener Knopfdruck: schon beantwortet oder älter als 15 Minuten |
inline_expired | Keine offene Inline-Anfrage: schon beantwortet, älter als 30 Sekunden oder Inline-Modus aus |
not_e2e | Der 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_envelope | Der Umschlag ist ungültig (zum Beispiel an den Bot selbst oder ohne gültiges Art-Kennzeichen) |
no_user | Dieses Konto gibt es nicht (mehr) |
bot_unavailable | Der Bot ist gesperrt (nach einer Entsperrung noch bis zu 30 Sekunden) |
rekeyed | Die Verbindung wurde geschlossen (Code 4006), weil der Bot neue Schlüssel bekommen hat oder zurück auf gehostet steht |
banned, auth_failed | Der 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
- Öffne in der App Meine Bots und tippe bei Deinem Bot auf die Karte «Bot-Verzeichnis» → «Einreichen», oder schreib der Werkstatt
/verzeichnis <bot>und antworte mit der Zahl Deiner Kategorie (1 bis 7). Mit/verzeichnis <bot> zurueckziehennimmst Du den Bot wieder heraus. - Vorher braucht der Bot eine Beschreibung und einen Link zur Datenschutzerklärung. Den Link setzt Du im Feld «Link zur Datenschutzerklärung» in «Meine Bots», mit
/datenschutz <bot> <https-adresse>in der Werkstatt (ausstatt der Adresse entfernt ihn) oder persetProfilemit dem Feldprivacy. Ohne Beschreibung kommtneed_about, ohne Linkneed_privacy(siehe Fehler). - Kategorien: Werkzeuge, Nachrichten & Medien, Unterhaltung, Spiele, Lernen, Firmen & Dienste, Sonstiges. In der Schnittstelle heissen sie
werkzeuge,nachrichten,unterhaltung,spiele,lernen,firmen,sonstiges. - Der Stand steht in «Meine Bots»: «Nicht im Verzeichnis», «In Prüfung», «Im Verzeichnis» oder «Abgelehnt» mit Begründung. Das HideChat-Team prüft meist innert weniger Tage und meldet sich in der Bot-Werkstatt (wenn Du sie gestartet hast; sonst siehst Du den Stand in «Meine Bots»). Bei einer Ablehnung kannst Du nach der Korrektur erneut einreichen.
- Reichst Du einen schon gelisteten Bot erneut ein, ändert sich nur die Kategorie. Entfernst Du Beschreibung oder Datenschutz-Link, nimmt das den Bot aus dem Verzeichnis.
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»).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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. - 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.
- Löschen. Wenn Du Dein Konto löschst, werden auch Deine Bots gelöscht. Gelöschte Bot-Namen bleiben 30 Tage gesperrt.
- 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.
- Ä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.