
whatsapp-waha
Self-hosted WhatsApp control for personal accounts via WAHA, with per-user profiles.
- version
- 1.0.0
- GitHub stars
- 32
What it does
- Adds 5 skills:
send-message,message-new-number,create-group,leave-or-archive, andwhatsapp-healthfor 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-PluginsRun it inside Claude Code once, then install the plugin below.
Install
/plugin install whatsapp-waha@danielrosehillRun it inside Claude Code after adding the marketplace.
Files
Discovered from sourceCreate 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
| Do | Method and path | Body |
|---|---|---|
| Add | POST /api/{session}/groups/<gid>/participants/add | {"participants": [{"id": "…@c.us"}]} |
| Remove | POST …/participants/remove | same |
| Promote / demote admin | POST …/admin/promote, …/admin/demote | same |
| Rename | PUT /api/{session}/groups/<gid>/subject | {"subject": "…"} |
| Description | PUT …/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.
| Skill | Does |
|---|---|
send-message | Text, quoted replies, photos and files to existing contacts and groups; read a chat; verify delivery by ack. |
message-new-number | First 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-group | New group with contacts and/or new numbers, opening message, invite link for anyone who couldn't be added; add/remove/promote members. |
leave-or-archive | Archive, unarchive or leave chats and groups; bulk tidy of dead groups with confirmation. |
whatsapp-health | Session 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(optionallywaha_put,waha_delete). Its name is the tool prefix you put in the profile'sgateway_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- workspace-foundationalv1.0.4
- writing-editingv1.0.0
- zigbee-home-maintenancev1.0.0
- adb-opsv1.4.0
- agent-browsersv0.5.0
- agent-deconflictionv1.0.0
- agent-exchangev1.0.1
- agent-ready-websitev1.0.0
- agentic-dev-workflowsv0.6.1
- ai-attributionv0.1.0
- ai-engineeringv1.0.0
- ai-evalv0.13.0
- ai-model-researchv1.4.0
- ai-toolsv1.0.0
- ai-video-producerv1.4.1
- air-quality-toolkitv1.0.0
- aliexpress-israel-skillsv1.14.0
- aliexpress-shopperv0.1.0
- amazonv2.2.0
- anonymisation-assistantv0.1.0
- audio-editingv1.0.0
- audio-productionv1.11.3
- audio-voice-idv0.1.0
- avp-music-videov0.1.0
Similar to whatsapp-waha
More Productivity & Planning
code-reviewanthropics/claude-code156.1K starsAutomated code review for pull requests using multiple specialized agents with confidence-based scoring to filter false positives
cavemanJuliusBrussee/caveman121.1K starsTalk like caveman. Cut filler. Keep technical details explicit.
career-opscareer-ops-hq/career-ops83.4K starsOpen-source AI job search that runs locally in your AI coding CLI: scan job portals, evaluate listings into a structured A-H report with a 1-5 score, tailor you
ruflo-autopilotruvnet/ruflo82.2K starsAutonomous /loop-driven task completion with learning, prediction, and progress tracking
ppt-masterhugohe3/ppt-master78K starsGenerate natively editable PPTX from PDF / DOCX / URL / Markdown — real DrawingML shapes, text boxes, charts, and animations. Note: run `pip install -r requirem
moletw93/Mole75.4K starsDrive the Mole CLI (mo) safely: find what uses disk space, preview cleanup with --dry-run, uninstall apps, and read system health and cleanup history.