Get started

How Packlets works

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

Open as Markdown

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

The terms

TermMeaning
Your toolYour code: a script, a server, a cron job, an AI agent. It runs on your side, not at Packlets.
PackletThe 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.
ChannelHow a packlet appears in the app: as an entry in the Channels tab or as a tile in the Apps tab.
Channel typeChannel ("Messages") or app ("Your own app"). You choose it when connecting. After that it's fixed.
Allow repliesSwitch for channels: you write to your tool, and it replies. Can be flipped at any time.
KeyYour packlet's password, starts with pk_. Your tool uses it to sign in to Packlets.
ServiceAnother tool that sends to the same channel, with its own key and its own name. See Several services in one channel.
Webhook URLThe 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

On your sideYour toolScript, server, Raspberry Pi or cron job
POST /v1/pushWebhook
In betweenPackletsstores the message and sends the push
PushTap, toggle, type
In your pocketYour phoneChannel in the app, push on the lock screen

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

ChannelChannel with repliesApp
Where in the appChannels tabChannels tabApps tab, as a tile
Your tool sends messages (POST /v1/push)yesyes, as repliesyes, 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 messagesyesyes–
Several servicesyesyes–
Needs a webhookonly for buttons and elementsyesno, 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:

ButtonButton element
Wherebelow a message, field buttonselement in a message, field elements
How oftenonce. Afterwards the message shows what you chose.as often as you like
Good foran answer to a question: "Approve", "Reject"an action you repeat: "Restart", "Clear cache"
Event at the webhookbuttonui

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