Your WhatsApp chats, search and contacts in the panel, through Wisp
palupdated 2026-11-16IntegrationIn pal's registryMenu bar: Unread2 deep links
In pal's registry: the button shows it in pal, which asks before installing; the command does the same from a terminal. This page can't see what your pal has installed.






What it does
Your WhatsApp chats in the panel through Wisp, your self-hosted inbox: recent chats with the unread ones first, search over your whole history, and the people you write to. It uses the Wisp extension's server and token. Reading is always on; sending and reacting only if you turn it on.
- Chats newest first, unread on top, with the latest message, who sent it and the unread count
enteropens the chat in WhatsApp,cmd+entermarks it read; the side pane shows the last twenty messages- Search across your whole history with Wisp's search, with who said it, where and when
- Contacts: the people you write to, by name or number: open a chat, copy the number or a vCard
- A bar item counting unread chats, hidden at zero and red while a direct chat waits;
spacein its popover reads a chat,iignores it until the next message without the blue ticks - Sending, replying and reacting stay off until you turn them on; everything goes through your own Wisp server
Palettes 4
-
Chats
chatsliveEvery chat, unread first then newest first, with the picture, the newest message and who sent it, the unread count, the time; the pane is the last twenty messages as a conversation.
- ↵Open the chat (a group opens WhatsApp at the top)
- ⌘↵Mark as read (Mark as unread on a read chat)
- ⌘⇧RSend a message typed in the bar (send on)
- ⌘⇧EReact to the latest message (send on)
- ⌘⇧OOpen in the web client
- ⌘CCopy the number (the name of a group)
-
Unread
unreadliveOnly the chats with something unread, direct messages then groups; the same rows and keys as Chats.
- ↵Open the chat
- ⌘↵Mark as read
- ⌘⇧RSend a message typed in the bar (send on)
- ⌘⇧EReact to the latest message (send on)
- ⌘⇧OOpen in the web client
- ⌘CCopy the number (the name of a group)
-
Search WhatsApp
searchinputWisp's search over every WhatsApp message back to the first chat (its operators too: from:, after:, has:): the matching line, who said it where, and when.
- ↵Open the chat
- ⌘CCopy the message
- ⌘⇧OOpen the chat in the web client
-
Contacts
contactsinputThe people you write to on WhatsApp, as Wisp knows them: the most recent first, or the best matches for a name or a number; open a chat, copy the number, copy a vCard.
- ↵Open a chat with the contact
- ⌘CCopy the number
- ⌘⇧CCopy as a vCard
- ⌘⇧OOpen the chat in the web client
Actions
- Open chatIn the desktop app (whatsapp://send?phone=) or the web client; a group opens WhatsApp at the top.↵
- Mark as readMark as unread on a read chat; works on marked rows too.⌘↵
- Send a messageThe text typed in the bar (the row's argument), a Reply choice quoting the latest message; a form when picked without it; send on only.⌘⇧R
- React to the latest messageOne of WhatsApp's six quick reactions, or remove yours; send on only.⌘⇧E
- Open in the web client⌘⇧O
- Copy numberCopy name on a group.⌘C
- Copy messageOn a search hit.⌘C
- Copy as vCardOn a contact.⌘⇧C
- Open Wisp settingsOn a hint row: the Wisp extension's settings, whose server and token WhatsApp uses.
Links 2
WhatsApp answers these pal:// routes from a web page, a script or a keybind; pal call is the same route from a terminal. A link from a page asks first unless you trust the extension. How links work.
-
Open a chat
openpal call whatsapp/open chat=<chat>chat*A chat id (…@c.us, …@lid, …@g.us), a phone number, or a name from the chats or the contacts
-
Search the archive
searchpal call whatsapp/search q=<q>q*Words from any message
Settings
Extension, [extensions.whatsapp]
sendOff (the default) leaves WhatsApp read and mark-read only: no message field, no reply, no reaction, whatever the token could do. On adds Send a message (the text typed in the bar, or a form) and React to a chat row and the reply field to the bar popover; nothing is sent without your text.
openauto opens the desktop app when it is installed (macOS) and the web client otherwise. A group has no link of its own, so it opens WhatsApp at the top either way. One of auto, app, web.
Defaults shown. Change them in pal's settings window or in the config file.
The README
Everything WhatsApp does, key by key, from the extension's own README.md
Your WhatsApp chats in the panel, through Wisp, your self-hosted inbox
that holds the WhatsApp account live with its history: the chats by recency with the newest message and who sent it, the unread
ones at the root and counted on the bar, a search over every message,
the people you write to with their numbers. It needs the Wisp extension
(requires) and uses its server and token; it has none of its own.
Reading and marking read are always on; sending, replying and reacting
only where you turn send on, and then only as a form you submit.
| palette | id | kind | what Enter does |
|---|---|---|---|
| Chats | whatsapp-chats |
live, lazy, primary | opens the chat in the app or the web client |
| Unread | whatsapp-unread |
live, lazy | the same, over the unread chats only |
| Search WhatsApp | whatsapp-search |
input | opens the hit's chat |
| Contacts | whatsapp-contacts |
input | opens a chat with the person |
Chats lists the conversations of Wisp's WhatsApp account (the first
one turned on; direct chats and groups, broadcasts and channels left
out), the unread ones first, then newest first. A row is the picture (or
the initial on a tile; a group without one takes the group glyph), the
name, the newest message on one line (in a group with who wrote it), a
group tag, the unread count in green, and how long ago. For the unread
chats the newest messages are fetched so the line and the sender are
right; for the rest Wisp's own preview stands. The pane (⌘I, or rest
on the row) is the last twenty messages as a conversation: the sender in
bold ("You" for yours) with the time, a photo or a sticker drawn inline,
a voice message with its transcript when Wisp made one, other media named
in brackets; then the chat's facts (kind, unread, the phone, when the
newest message came) and a link into the web client.
| action | shortcut | notes |
|---|---|---|
| Open chat | Enter |
whatsapp://send?phone= in the desktop app, https://web.whatsapp.com/send?phone= on the web, per open. A group has no link of its own on either, so it opens WhatsApp at the top and the HUD says so |
| Mark as read / Mark as unread | ⌘Enter |
works on marked rows too |
| Send a message | ⌘⇧R |
send on. The message is the row's typed argument: with the cursor on the chat, Tab into the Message field in the bar (and a Reply choice that quotes the chat's latest incoming message, when the listing knows one), ⌘⇧R sends; Enter on the row still opens the chat. A pick without the values (pal run, a hotkey) is a form: the text, and a box to quote |
| React to the latest message | ⌘⇧E |
send on. WhatsApp's six quick reactions, or remove yours |
| Open in the web client | ⌘⇧O |
|
| Copy number / Copy name | ⌘C |
the number as +905...; a group's name; marked chats one per line |
Unread is the same rows over the chats with something unread, direct
messages first then groups, so the root carries them; "Nothing unread"
when there are none. Search WhatsApp sends what you type to Wisp's
search with in:whatsapp (words match as prefixes, accents and Turkish
letters folded, its operators work: from:, after:, has:), a
keystroke waiting 300 ms for the next; a row is the matching line, who
said it where, and when; Enter opens the chat, ⌘C copies the message,
the pane is the chat's conversation. Contacts is Wisp's people with a
WhatsApp identity: the most recent with nothing typed, the best matches
for a name or a number otherwise; Enter opens a chat, ⌘C copies the
number, ⌘⇧C copies a vCard 3.0 (FN and TEL). Marked rows copy
together, one per line (several vCards make one .vcf); opening stays
one chat, since WhatsApp shows one at a time.
The bar item
whatsapp/unread: the number of unread chats as the badge, hidden at
zero and red while a direct chat is among them by its rules (quiet,
dm under Settings > Bar). A message updates it within a second: the
item listens to Wisp's event stream (/api/v1/events, the same reader
the Wisp extension uses) and refreshes on a message.new on the
WhatsApp account or an unread.changed that moved its unread. It also
refreshes every 30 s, when the panel shows, after a wake and when the
network is back (the stream reconnects then too), and after a mark read,
unread or send from a palette. The popover lists them, direct messages
then groups, each with the picture, the newest message and the time, and
a cursor the arrows move and a click sets: Enter opens the chat,
Space previews it (the latest messages, r, m and Enter still
working there), m marks it read, i ignores it until the next message
(out of the count and the popover, still unread on the phone: no blue
ticks, nothing sent), a every listed one, o opens WhatsApp (its hint
gives way to i over an unread row; the key still works), p the
Unread palette, ⌘⇧O the web client; with send on, r turns the
search row into a message field whose Enter sends to the focused chat.
With show = "always" under [bar.items."whatsapp/unread"]
(docs/config.md) the glyph stays on the bar while nothing is unread,
muted, and the popover lists the recent chats instead.
What it reads, and what it writes
Everything goes to Wisp's v1 API with the Wisp extension's token as a
bearer; nothing else sees the chats. Read: GET /api/v1/accounts (once,
for the WhatsApp account), /conversations?view=all&account= (the list,
200 a page, three pages), /conversations/<id>/messages (the unread
chats' newest and the pane's twenty), /conversations/<id> (a chat the
list lacks), the pictures under /api/v1 at 64 px (560 for a photo in
the pane), /search, /people and /people/<id> (Contacts, and the
number of a chat whose messages carry none), and the event stream.
Written, always: POST /conversations/<id>/read and /unread (Mark as
read / unread). Written only with send on, each from a form you submit
or the popover's field on Enter: POST /conversations/<id>/messages
(with replyTo for a quoted reply), POST and DELETE /messages/<id>/react. With send off none of these is offered anywhere,
and a pick that asks anyway is refused with a toast naming the setting.
A token of scope client (Wisp's "App of yours") acts as you, on your
keystroke, through the account's send policy and undo delay; the
setting is the control here.
Setting up
Set up the Wisp extension (its server and a client token). Its
settings are the only ones this needs:
| key | type | default | what |
|---|---|---|---|
send |
boolean | false |
Send a message, React, the popover's reply field. |
open |
select | auto |
auto (the desktop app when installed on macOS, else the web client), app, web. |
Hint rows name the fix: Wisp not set up, unreachable at its url, the token refused (each with Open Wisp settings), no WhatsApp account in Wisp, the search failing (the status and Wisp's message).
Not shown: muted and pinned chats, a group's member count. A chat's picture is fetched among the newest 48 only; the rest keep the initial. A quoted message is not drawn in the pane, since Wisp's v1 messages do not carry what they quote.
Links
pal://whatsapp/open?chat=<id | phone | name>: Wisp's conversation id, a phone number or a WhatsApp id with one (...@s.whatsapp.net), or a name the chats or Wisp's people have (exact, then a prefix).pal://whatsapp/search?q=<words>: the search palette with the query typed.







