New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Self-hosted WhatsApp control for personal accounts via WAHA, with per-user profiles.

version
1.0.0
GitHub stars
32
View on GitHub

What it does

  • Adds 5 skills: send-message, message-new-number, create-group, leave-or-archive, and whatsapp-health for WAHA-linked accounts
  • Covers text and photo sends to contacts and groups, first messages to unknown numbers with contact saving, and group creation and management
  • Enforces one-at-a-time personal use and checks WhatsApp's capping and reach-out lock signals before risky sends
  • Designed for individuals or households running their own WAHA container and MCP server, with a per-user profile for each account

Personal WhatsApp via self-hosted WAHA: send, groups, health. Text and photos to contacts and groups, first message to a new number with the contact saved (placeholder name if unknown), create and manage groups, archive or leave chats, check the link for capping and reach-out locks. Per-user profiles, so one install serves several accounts.

Add marketplace

/plugin marketplace add danielrosehill/Claude-Code-Plugins

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install whatsapp-waha@danielrosehill

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Create or change a group

Read the account profile first: references/profile.md. Raw calls are <gateway_server>__waha_post / waha_get; {session} is the profile's session. Asking for the group is the approval. Membership is visible to everyone in it, so each participant must be certain: resolve as in send-message, ask about any name with several matches or none.

1. Participants

Each is <digits>@c.us; local 0… numbers get the profile's country_code. Run check_number on any new number and drop (and report) those not on WhatsApp. The owner is added automatically as admin.

Adding many people who don't have the owner's number looks like spam to WhatsApp. For strangers, prefer a 1:1 invite link with an intro (message-new-number) to adding them, and keep new numbers per creation small (under ~10).

2. Create

{"path": "/api/{session}/groups",
 "body": {"name": "<group name>", "participants": [{"id": "<n>@c.us"}]}}

Take the group id (…@g.us) from the response. Read back waha_get /api/{session}/groups/<gid>/participants and compare: someone whose privacy settings block being added will be missing; send them the link (step 4).

3. Opening message

Send the user's opening text (or a one-line hello saying what the group is for) with send-message to the group id, and verify.

4. Invite link

waha_get /api/{session}/groups/<gid>/invite-code → https://chat.whatsapp.com/<code>.

5. Change an existing group

DoMethod and pathBody
AddPOST /api/{session}/groups/<gid>/participants/add{"participants": [{"id": "…@c.us"}]}
RemovePOST …/participants/removesame
Promote / demote adminPOST …/admin/promote, …/admin/demotesame
RenamePUT /api/{session}/groups/<gid>/subject{"subject": "…"}
DescriptionPUT …/description{"description": "…"}

The owner must be admin. PUT needs a waha_put tool on the server; without one, tell the user to do it from the phone. Read the participant list back after every change and name removed people in the report.

Report

Group name and id, who's in, who got the link instead, first words of the opening message.


Endpoints per WAHA 2026.10 (Core, NOWEB) documentation. Creation and participant changes had not been exercised live when this was written (2026-11-17): the first real run should confirm them and update this line.

Readme

WhatsApp via WAHA

Agent skills for driving your own personal WhatsApp account through a self-hosted WAHA linked-device session exposed as an MCP server. Account-neutral: names, numbers, aliases and routes live in a per-user profile outside the plugin (references/profile.md), so the same skills serve several people's accounts, each with their own WAHA container and MCP server.

SkillDoes
send-messageText, quoted replies, photos and files to existing contacts and groups; read a chat; verify delivery by ack.
message-new-numberFirst message to a number you've never messaged: normalise local numbers, check it's on WhatsApp, intro line, text + photos, then save the contact (placeholder name if unknown).
create-groupNew group with contacts and/or new numbers, opening message, invite link for anyone who couldn't be added; add/remove/promote members.
leave-or-archiveArchive, unarchive or leave chats and groups; bulk tidy of dead groups with confirmation.
whatsapp-healthSession state, WhatsApp message capping and reach-out lock, version, container restarts, live reads.

Requirements

  • A WAHA instance (tested: 2026.10.1, Core tier, NOWEB engine) paired with your phone. Core runs one session per container: one container per account.
  • An MCP server in front of it providing session_status, send_chat_message, get_messages, list_chats, search_contacts, check_number, mark_seen, priority_chats, waha_get, waha_post (optionally waha_put, waha_delete). Its name is the tool prefix you put in the profile's gateway_server.
  • Optional: a contacts tool (e.g. a Google Contacts MCP) for saving new contacts, and a way to host a file at a temporary public URL for sending media.

Setup

Create ~/.claude-user-data/whatsapp-waha/profiles/<you>.md from the template in references/profile.md. Several profiles → the skills pick the account you name, else the default: true one.

Caution

WAHA is an unofficial WhatsApp client; WhatsApp's terms don't allow it and accounts can be banned, mostly for bulk or stranger messaging. The skills keep to one-at-a-time personal use and check WhatsApp's own throttling signals before risky sends.

History

Extracted 2026-11-17 from a private personal-WhatsApp plugin (send, new-number, group and health skills written and live-tested there the same day), depersonalised so a second household member could use the same skills with their own account.

License: MIT.

Details

Marketplace
danielrosehill/Claude-Code-Plugins
Source
danielrosehill/Claude-WhatsApp-WAHA-Plugin
Author
Daniel Rosehill
Category
Personal Productivity
License
MIT

More from danielrosehill/Claude-Code-Plugins

All 264

Similar to whatsapp-waha

More Productivity & Planning