WAHA Onboarding Skill
Use this skill when a user wants to connect their WhatsApp account through WAHA.
Onboarding flow
1) Collect phone number
Ask for the user’s WhatsApp number including country code.
Example prompt:
"👋 I can connect your WhatsApp. Send your phone number with country code (digits only if possible), for example 905380546393."
2) Sanitize number and derive session name
- Strip all non-digit characters from the input.
- Use sanitized value as
<phonenumber>. - Session name format:
user-<phonenumber>.
3) Create and start WAHA session
Run:
waha-cli waha-create-session --name user-<phonenumber>
sleep 5
waha-cli waha-start-session --session user-<phonenumber>
4) Request pairing code
Run:
sleep 5
waha-cli waha-request-pairing-code --session user-<phonenumber> --phone-number <phonenumber>
5) Share pairing instructions
Send the returned code and tell user:
- Open WhatsApp → Linked Devices
- Tap Link a Device
- Tap Link with phone number instead
- Enter the pairing code
6) Verify authentication after user confirms
Run:
waha-cli waha-check-auth-status --session user-<phonenumber>
- If status is
WORKING: onboarding succeeded. - Otherwise: run fallback.
7) Confirm success and offer next actions
Offer:
- recent conversations
- contacts
- messages from a specific chat
Fallback (if not WORKING)
Restart and issue a fresh code:
waha-cli waha-start-session --session user-<phonenumber>
sleep 8
waha-cli waha-request-pairing-code --session user-<phonenumber> --phone-number <phonenumber>
Then ask user to retry from WhatsApp Linked Devices.
Naming and ID conventions
- WAHA session:
user-<phonenumber> - Direct chat id convention:
<phonenumber>@c.us