Loslegen
So funktioniert Samy
Die Begriffe und das Zusammenspiel: dein Tool, Packlet, Schlüssel, Aufrufe hin und Webhook zurück.
Diese Seite erklärt die Begriffe, die in der ganzen Doku vorkommen, und wie die Teile zusammenspielen. Code gibt es hier keinen.
Die Begriffe
| Begriff | Bedeutung |
|---|---|
| Dein Tool | Dein Code: ein Skript, ein Server, ein Cronjob, ein KI-Agent. Er läuft bei dir, nicht bei Samy. |
| Packlet | Die Verbindung zwischen einem deiner Tools und Samy. Du legst es in der App an. Es hat einen Namen, einen Avatar, eine Art und einen Schlüssel. |
| Kanal | So erscheint ein Packlet in der App: als Eintrag im Tab Kanäle oder als Kachel im Tab Apps. |
| Kanal-Art | Kanal („Mir Bescheid geben“) oder App („Eigene App bauen“). Du wählst sie beim Verbinden. Danach steht sie fest. |
| Antworten erlauben | Schalter für Kanäle: Du schreibst deinem Tool, es antwortet. Lässt sich jederzeit umlegen. |
| Schlüssel | Das Passwort deines Packlets, beginnt mit samy_. Mit ihm meldet sich dein Tool bei Samy an. |
| Webhook-URL | Die Adresse deines Tools, an die Samy meldet, was du in der App tust. |
Faustregel: Ein Tool, ein Packlet. So hat jedes seinen eigenen Kanal, und du kannst einen Schlüssel tauschen, ohne dass die anderen Tools ausfallen.
Zwei Richtungen
Hin: Dein Tool ruft Samy. Dein Tool schickt einen HTTP-Aufruf mit dem Schlüssel. Samy speichert, zeigt es im Kanal und schickt einen Push. Dafür braucht dein Tool nur ausgehendes Internet. Es muss nicht erreichbar sein.
Zurück: Samy ruft dein Tool. Tippst du einen Knopf, legst einen Schalter in einer Nachricht um oder schreibst in einem Kanal mit Antworten, schickt Samy ein Ereignis an die Webhook-URL deines Packlets. Dafür muss dein Tool unter einer öffentlichen https-Adresse erreichbar sein.
Die Richtung zurück ist freiwillig. Ein Kanal, der nur meldet, braucht sie nicht. Knöpfe, Elemente und Antworten leben davon.
Eine App geht einen dritten Weg: Sie ist deine eigene Webseite. Was du dort tippst, schickt die Seite direkt an deinen Server. Samy sagt ihm über ein Session-Token, wer die Seite öffnet.
Hinweis: Ohne Webhook-URL speichert Samy deine Eingaben und zeigt sie in der App, aber dein Tool erfährt nichts davon. Es wird auch nichts nachgeliefert, wenn du die Adresse später einträgst.
Was jede Art kann
| Kanal | Kanal mit Antworten | App | |
|---|---|---|---|
| Wo in der App | Tab Kanäle | Tab Kanäle | Tab Apps, als Kachel |
Dein Tool schickt Nachrichten (POST /v1/push) | ja | ja, als Antworten | ja, sie kommen nur als Push |
| Du schreibst deinem Tool | – | ja | – |
Dein Tool zeigt eine eigene Webseite (PUT /v1/ui) | – | – | ja |
| Knöpfe und Elemente in Nachrichten | ja | ja | – |
| Braucht einen Webhook | nur für Knöpfe und Elemente | ja | nein, die Seite spricht mit deinem Server |
Eine App zeigt keine Nachrichten, nur ihre Seite. Schickt sie trotzdem eine Nachricht, kommt die als Push, und die Kachel zeigt einen Zähler.
Knopf oder Button
Beides lässt dich dein Tool vom Handy aus bedienen. Der Unterschied:
| Knopf | Button | |
|---|---|---|
| Wo | unter einer Nachricht, Feld buttons | Element in einer Nachricht, Feld elements |
| Wie oft | einmal. Danach zeigt die Nachricht, was du gewählt hast. | beliebig oft |
| Gut für | eine Antwort auf eine Frage: „Freigeben“, „Ablehnen“ | eine Aktion, die du wiederholst: „Neu starten“, „Cache leeren“ |
| Ereignis am Webhook | button | ui |
Der Button ist eines von sechs Elementen. Die anderen sind Text, Schalter, Eingabefeld, Diagramm und Tabelle. Du hängst sie an eine Nachricht.
Was Samy speichert
- Nachrichten bleiben im Kanal, bis du sie löschst. Langes Drücken auf eine Nachricht löscht sie. Dein Tool erfährt davon nichts.
- Werte von Schaltern und Eingabefeldern in Nachrichten speichert Samy selbst. Dein Tool muss sie nicht zurückschicken.
- Der Schlüssel wird nie im Klartext gespeichert. Mehr dazu unter Schlüssel und Sicherheit.
- Das Protokoll in den Einstellungen jedes Packlets zeigt die letzten Aufrufe deines Tools und die Webhook-Aufrufe an dein Tool.
Wie es weitergeht
- Mit dem Feed anfangen: Nachricht senden.
- Die Richtung zurück einrichten: Webhook einrichten.