# How Packlets works

The terms and how they fit together: your tool, packlet, key, calls in and the webhook back.

This page explains the terms used throughout the docs and how the pieces fit together. There's no code here.

## The terms

| Term | Meaning |
|---|---|
| **Your tool** | Your code: a script, a server, a cron job, an AI agent. It runs on your side, not at Packlets. |
| **Packlet** | The connection between one of your tools and Packlets. You create it in the app. It has a name, an avatar, a type and a key. |
| **Channel** | How a packlet appears in the app: as an entry in the **Channels** tab or as a tile in the **Apps** tab. |
| **Channel type** | Channel ("Messages") or app ("Your own app"). You choose it when connecting. After that it's fixed. |
| **Allow replies** | Switch for channels: you write to your tool, and it replies. Can be flipped at any time. |
| **Key** | Your packlet's password, starts with `pk_`. Your tool uses it to sign in to Packlets. |
| **Service** | Another tool that sends to the same channel, with its own key and its own name. See [Several services in one channel](https://packlets.app/en/docs/dienste.md). |
| **Webhook URL** | The address of your tool, where Packlets reports what you do in the app. |

Rule of thumb: one tool, one packlet. That way each has its own channel, and you can swap a key without the other tools going down.

## Two directions

**There: your tool calls Packlets.** Your tool makes an HTTP call with the key. Packlets saves it, shows it in the channel and sends a push. For this, your tool only needs outgoing internet. It doesn't have to be reachable.

**Back: Packlets calls your tool.** When you tap a button, flip a switch in a message or write in a channel with replies, Packlets sends an event to your packlet's webhook URL. For this, your tool must be reachable at a public `https` address.

The way back is optional. A channel that only reports doesn't need it. Buttons, elements and replies depend on it.

An app takes a third path: it's your own web page. What you tap there, the page sends straight to your server. Packlets tells your server who is opening the page using a [session token](https://packlets.app/en/docs/api-seiten.md#session-token).

> **Note:** Without a webhook URL, Packlets saves your input and shows it in the app, but your tool doesn't learn about it. Nothing is delivered later either if you add the address afterwards.

## What each type can do

| | Channel | Channel with replies | App |
|---|---|---|---|
| Where in the app | Channels tab | Channels tab | Apps tab, as a tile |
| Your tool sends messages (`POST /v1/push`) | yes | yes, as replies | yes, as [notifications](https://packlets.app/en/docs/apps.md#6-send-notifications): push and bell |
| You write to your tool | – | yes | – |
| Your tool shows its own web page (`PUT /v1/ui`) | – | – | yes |
| Buttons and elements in messages | yes | yes | – |
| Several [services](https://packlets.app/en/docs/dienste.md) | yes | yes | – |
| Needs a webhook | only for buttons and elements | yes | no, the page talks to your server |

An app shows only its page on its surface. When your server sends a message, it arrives as a push, the tile shows a counter, and at the top right of the app it appears under the bell. More under [Send notifications](https://packlets.app/en/docs/apps.md#6-send-notifications).

## Button or button element

Both let you control your tool from your phone. The difference:

| | Button | Button element |
|---|---|---|
| Where | below a message, field `buttons` | element in a message, field `elements` |
| How often | once. Afterwards the message shows what you chose. | as often as you like |
| Good for | an answer to a question: "Approve", "Reject" | an action you repeat: "Restart", "Clear cache" |
| Event at the webhook | `button` | `ui` |

The button element is one of six **elements**. The others are text, switch, input field, chart and table. You attach them to a [message](https://packlets.app/en/docs/nachrichten-elemente.md).

## What Packlets stores

- **Messages** stay in the channel until you delete them. Long-pressing a message deletes it. Your tool isn't told.
- **Values** of switches and input fields in messages are stored by Packlets itself. Your tool doesn't have to send them back.
- **The key** is never stored in plain text. More under [Keys and security](https://packlets.app/en/docs/sicherheit.md).
- **The activity log** in each packlet's settings shows your tool's latest calls and the webhook calls to your tool.

## Where to go next

- Start with the feed: [Send a message](https://packlets.app/en/docs/senden.md).
- Set up the way back: [Set up a webhook](https://packlets.app/en/docs/webhook.md).
