Get started
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. |
| 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.
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: 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 | 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.
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.
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.
- 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.
- Set up the way back: Set up a webhook.