The catalogue/WhatsApp
app.whatsapp
Send and receive WhatsApp messages, manage sessions, and share media via WAHA
Version2.0.0
Categorycommunication
AuthApp agent
Tools28
Transportstdio
LicenceMIT
01
What it does
The app, in its own words.
Send and receive WhatsApp messages via WAHA (WhatsApp HTTP API). Manage sessions, send text/media, and handle incoming messages. Account linking is always done with a numeric pairing code (request-pairing-code) — QR authentication is not supported.
02
Tools
28 tools the agent can call.
Every one is declared with typed parameters and returns structured results, so the host can render them instead of narrating them.
- check-numberCheck if a phone number has WhatsApp and get its chat ID.
- delete-profile-pictureDelete the profile picture of the current WhatsApp account.
- download-mediaDownload media (image, audio, video, document) from a WhatsApp message. Fetches the message by ID to get the media URL, then downloads the file and saves it to the specified output path. Requires the message to have hasMedia: true.
- get-chat-labelsGet all labels assigned to a specific WhatsApp chat. Returns an array of label objects with id, name, color, and colorHex. Only available in WhatsApp Business accounts.
- get-chatsList all WhatsApp chats (conversations) in a session.
- get-contact-profile-pictureGet the profile picture URL of a WhatsApp contact.
- get-contactsGet all contacts from a WhatsApp session.
- get-labelsList all labels available in a WhatsApp Business session. Labels are used to organize chats. Only available in WhatsApp Business accounts.
- get-messagesGet recent messages from a WhatsApp chat.
- get-profileGet the profile of the current WhatsApp account (name, picture URL, status/About text, etc.).
- get-unread-chatsReturn chats that have unread messages, ordered by unread count (desc). Supports pagination.
- health-checkInternal health check tool. Verifies WAHA connectivity and lists active sessions.
- mark-unreadMark a WhatsApp chat as unread (shows the blue dot indicator).
- put-chat-labelsSet (replace) the labels assigned to a WhatsApp chat. You must provide the FULL list of labels to assign — any labels not included will be removed. Pass an empty array to remove all labels. Only available in WhatsApp Business accounts.
- reactionSend or remove a reaction (emoji) to a WhatsApp message.
- read-messagesMark messages in a WhatsApp chat as read. If no message IDs are provided, marks all messages in the chat as read.
- request-pairing-codeRequest a numeric pairing code to link a WhatsApp session. This is the ONLY supported way to authenticate/link a session in Teros. The session must be in SCAN_QR_CODE state — WAHA's "waiting to be linked" state (if not, it will be stopped and restarted automatically). Returns an 8-digit code like "XXXX-YYYY" to enter in WhatsApp > Linked Devices > Link with phone number.
- search-chatsSearch WhatsApp chats by name or phone number. Filters client-side over the full chat list.
- search-contactsSearch contacts by name or phone number. Returns matches ordered by most recent interaction first (top 5), then remaining matches up to limit.
- send-documentSend a document or file (PDF, DOCX, XLSX, etc.) to a WhatsApp chat from a public URL or a local /workspace/ path.
- send-imageSend an image to a WhatsApp chat from a public URL.
- send-textSend a WhatsApp text message to a phone number or group.
- session-statusGet the status of a WhatsApp session. Status can be: WORKING, SCAN_QR_CODE, STARTING, STOPPED, FAILED. SCAN_QR_CODE means the session is waiting to be linked — use request-pairing-code (authentication is always done with a pairing code, never QR).
- set-profile-nameChange the display name of the current WhatsApp profile.
- set-profile-pictureSet the profile picture of the current WhatsApp account from a public image URL.
- set-profile-statusChange the "About" status text of the current WhatsApp profile.
- start-sessionStart a WhatsApp session. Creates it if it does not exist. If the session is in FAILED state, it will be stopped and restarted automatically. After starting, use request-pairing-code to link the device — authentication is always done with a pairing code (QR is not supported).
- stop-sessionStop a WhatsApp session without deleting it. The session can be restarted later with start-session.
03
Auth and permissions
What it asks for.
Declared in the manifest, in advance. The app cannot reach anything it did not ask for here.
System secrets
WAHA_API_KEY
Reading further
The manifest and the source for WhatsApp live in the monorepo, alongside the other apps.