# 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](https://packlets.app/docs/api-seiten.md#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](https://packlets.app/docs/nachrichten-elemente.md).

## 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](https://packlets.app/docs/sicherheit.md).
- **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](https://packlets.app/docs/senden.md).
- Die Richtung zurück einrichten: [Webhook einrichten](https://packlets.app/docs/webhook.md).