Skill: whatsable/agent-skills-by-notifyer (version 1.0.0)

--- name: setup-notifyer description: > Create and manage a Notifyer by WhatsAble account — signup, login, retrieve the authenticated user, check WhatsApp connection status, manage subscription plans, manage team members, assign roles, configure workspace labels, and retrieve the Developer API key. Use this skill any time you need to authenticate against the Notifyer Console API, set up a new workspace, or prepare the identity and infrastructure before running automate-notifyer or chat-notifyer. license: Proprietary — © WhatsAble. All rights reserved. compatibility: Requires Node.js >= 18. Set NOTIFYER_API_BASE_URL and NOTIFYER_API_TOKEN environment variables before running any script. metadata: author: whatsable version: "1.0.0" product: Notifyer by WhatsAble api-base: https://api.insightssystem.com --- # setup-notifyer Scripts for managing a Notifyer account via the Console API (`https://api.insightssystem.com`). All Console API requests authenticate with `Authorization: Bearer <token>`. ## Setup ```bash cd skills/setup-notifyer npm install # no dependencies required yet (uses built-in fetch) ``` Set environment variables: ```bash export NOTIFYER_API_BASE_URL="https://api.insightssystem.com" export NOTIFYER_API_TOKEN="<jwt-token>" # from login.js ``` ## How-to ### Create a new Notifyer account ```bash node scripts/create-account.js \ --name "Jane Smith" \ --email [REDACTED_SECRET] \ --password "Secure@123" \ --phone 14155550123 ``` `--reason` is optional (shown as "(optional)" in the signup UI). Supply it to help the support team understand the use case. Returns `{ ok: true, data: { authToken, user, apiKey } }` on success. The `authToken` can be used immediately as `NOTIFYER_API_TOKEN`. ### Login to an existing account ```bash node scripts/login.js \ --email [REDACTED_SECRET] \ --password "Secure@123" ``` Returns `{ ok: true, data: { authToken } }`. ```bash export NOTIFYER_API_TOKEN="<authToken from above>" ``` ### Get the currently authenticated user ```bash node scripts/get-me.js ``` Returns `{ ok: true, data: { id, name, email, role, phone_number, ... } }`. ### Run a pre-flight health check (start here when debugging) ```bash node scripts/doctor.js node scripts/doctor.js --pretty # human-readable pass/fail report to stderr ``` Validates all four prerequisites in one command: 1. `NOTIFYER_API_BASE_URL` — set and starts with `https://` 2. Token (`NOTIFYER_API_TOKEN`) — valid and accepted by `/auth/me` 3. WhatsApp connection — `isConnected: true` (and detects degraded Meta states) 4. Plan status — subscription is `active`, `trialing`, or `new_user` Returns `{ ok: true, data: { all_healthy: true, checks: { base_url, token, connection, plan } } }`. Returns `{ ok: false, ... }` (exit 1) if any check fails, with a `fix` hint for each failure. **Run `doctor.js` before any other script when troubleshooting unexpected failures.** ### Check WhatsApp connection status ```bash node scripts/get-connection-status.js node scripts/get-connection-status.js --pretty # human-readable summary to stderr ``` Returns `{ ok: true, data: { isConnected, degraded, meta_errors, has_embedded_user, registration, subscription, payment_method_added, is_template_has, is_message_tested, is_profile_picture_added, onboarding_steps_completed } }`. `isConnected = true` means the phone number has both successful Meta registration and subscription — it is ready to send messages. `degraded = true` means `isConnected` is true but Meta returned hidden errors inside the `whatsapp_response` payload (e.g. two-step PIN mismatch, account restricted). Always check `degraded` alongside `isConnected` — a degraded connection may fail silently. `meta_errors` contains the extracted error details as a string array. ### Force-refresh WhatsApp registration status with Meta Use this when `get-connection-status.js` shows a failed or stale registration/subscription, or after connecting a new number in the console. ```bash node scripts/refresh-connection.js node scripts/refresh-connection.js --pretty ``` Returns the same shape as `get-connection-status.js`. > **Daily limit warning:** Meta limits how many times per day re-registration can be > attempted. If the response indicates a limit error, wait 24 hours before retrying. ### List available subscription plans ```bash node scripts/list-plans.js # all plans node scripts/list-plans.js --billing monthly # monthly only node scripts/list-plans.js --billing annual # annual only node scripts/list-plans.js --tier pro # Pro tier only node scripts/list-plans.js --tier basic --billing monthly node scripts/list-plans.js --pretty # human-readable table to stderr ``` Returns all plan tiers grouped by `{ monthly: { basic, pro, agency }, annual: { ... } }`. Each tier entry contains `id`, `price` (in dollars), `unique_numbers` (contact limit), `stripe_price_id`, and `What_it_includes`. Plans: `basic` = Bulk Message (no integrations/bots), `pro` = full features, `agency` = Pro + multiple phone numbers. ### Get current subscription and usage ```bash node scripts/get-user-plan.js node scripts/get-user-plan.js --pretty ``` Returns `{ usages, latest_plan: { status, plan_amount, unique_number_limit, total_unique_number_count, end_time, ... } }`. `plan_amount` is in **cents** — the script adds a `plan_amount_dollars` convenience field. ### List team members ```bash node scripts/list-members.js # all members node scripts/list-members.js --page 1 --per-page 25 # paginate node scripts/list-members.js --labels # also show available label names node scripts/list-members.js --pretty # human-readable table to stderr ``` Returns `{ items: TeamMember[], team_seat: { included_seats } }`. Members are sorted by role (Super Admin → Admin → Team Member (All Labels) → Team Member). ### Add a team member ```bash node scripts/invite-member.js \ --name "Jane Smith" \ --email [REDACTED_SECRET] \ --password "Secure@2024" \ --role "Team Member" \ --labels "Sales,Support" ``` Creates a full account immediately (no email invite flow). Share credentials out-of-band. Assignable roles: `Admin`, `Team Member (All Labels)`, `Team Member`. Labels (comma-separated) are only used for `Team Member` role — Admin roles get all labels automatically. ### Change role, labels, name, or password ```bash # Promote to Admin node scripts/update-member.js --id <id> --role Admin # Assign new labels (replaces current list) node scripts/update-member.js --id <id> --labels "Sales,VIP" # Clear all labels node scripts/update-member.js --id <id> --labels "" # Rename + reset password node scripts/update-member.js --id <id> --name "John Doe" --password "NewPass@99" ``` There is no separate `change-role` endpoint — role, labels, name and password are all updated through the same `PATCH /api:-4GSCDHb/auth/user` call. The script auto-fetches current values and only changes what you supply. ### Remove a team member ```bash node scripts/remove-member.js --id <id> --confirm ``` Permanent and immediate. `--confirm` is required to prevent accidental deletion. Super Admin (account owner) cannot be removed. ### List workspace labels ```bash node scripts/list-labels.js node scripts/list-labels.js --pretty # human-readable table to stderr ``` Returns `{ labels: Label[], count: n }`. Each label has `id`, `label` (display name), `keywords` (auto-assignment triggers), `user_id`, and `created_at`. > Super Admin and Admin see **all** workspace labels. Team Members see only the > labels assigned to their account. ### Create a workspace label ```bash node scripts/create-label.js --label "Sales" node scripts/create-label.js --label "Support" --keywords "help,issue,ticket" ``` Label names must be unique. `keywords` are comma-separated trigger words that auto-assign the label when a contact message contains a match. ### Update a label's name or keywords ```bash # Add keywords node scripts/update-label-keywords.js --id 5 --add "urgent,priority" # Remove a keyword node scripts/update-label-keywords.js --id 5 --remove "old-keyword" # Replace the entire keyword list node scripts/update-label-keywords.js --id 5 --set "buy,purchase,order" # Clear all keywords node scripts/update-label-keywords.js --id 5 --set "" # Rename a label node scripts/update-label-keywords.js --id 5 --label "VIP Customers" ``` `--add`, `--remove`, and `--set` are mutually exclusive. The script fetches the current label first so unchanged fields are preserved. ### Delete a workspace label ```bash node scripts/delete-label.js --id 5 --confirm ``` Permanent and immediate. `--confirm` is required to prevent accidental deletion. After deletion, manually remove the label from any team members that had it assigned using `update-member.js --labels`. ### Get the Developer API key ```bash node scripts/get-api-key.js node scripts/get-api-key.js --pretty # prints key to stderr for easy copying ``` Returns `{ id, api_key, user_id, created_at }`. The `api_key` value is the credential used by **Make, Zapier, n8n, and custom scripts** to send messages via the developer API. It authenticates as a **raw `Authorization`** header (no `Bearer` prefix) — different from `NOTIFYER_API_TOKEN`. ## Rules - **Three distinct auth modes** — Console (`Bearer <jwt>`), Chat (`<jwt>` raw), Developer (`<api_key>` raw). The console JWT and the Developer API key are different credentials. `get-api-key.js` uses console auth to retrieve the key; the key itself is then used by external tools as a raw `Authorization` header. - **API key requires Pro or Agency plan** — the key can be fetched on any plan, but using it for automation (Make, Zapier, n8n, developer API calls) requires Pro or Agency. Basic (Bulk Message) plan accounts are blocked. Always verify plan status with `get-user-plan.js` before directing a user to set up integrations. - **Use "Notifyer Systems" module in Make/Zapier/n8n** — the console explicitly warns against using the "WhatsAble" module. Direct users to the "Notifyer Systems" module specifically when setting up external automations. - **API key is fixed** — there is no rotate or regenerate endpoint. Treat `api_key` as a long-lived secret; store it in env vars, never in source control. - **`send_template_message_by_api` uses the API key, not the JWT** — when calling `POST /api:hFrjh8a1/send_template_message_by_api`, set `Authorization: <api_key>` (no Bearer). `phone_number` is passed as **text** here (unlike console APIs where it is an integer). - **`sub_channel: "onboarding_test"`** is a special mode that updates `embedded_users` and is only for test sends. Omit `sub_channel` (or pass `""`) for production sends. - **Label endpoints use chat auth** — `list-labels.js`, `create-label.js`, `update-label-keywords.js`, and `delete-label.js` all use `Authorization: <token>` (no `Bearer` prefix). The same `NOTIFYER_API_TOKEN` from `login.js` works — `notifyer-api.js` handles the format difference via `AUTH_MODE_CHAT`. - **GET labels is role-filtered** — Admin/Super Admin see all labels; Team Members see only their assigned labels. Always use an Admin token for label management. - **Label names must be unique** — `create-label.js` returns `{ ok: false, blocked: true }` if a label with the same name already exists. - **`keywords` is a full replacement** — `update-label-keywords.js --set` replaces the entire list. Use `--add` / `--remove` to make incremental changes. - **No GET-by-ID in the web group** — `update-label-keywords.js` and `delete-label.js` both call `GET /web/label_management` to look up the target by id before mutating. - **DELETE returns no body** — Xano returns an empty response for label deletion; the script synthesises `{ deleted: true, id, label }` from the pre-flight fetch. - **Deleting a label does not remove it from members** — after `delete-label.js`, update affected team members manually with `update-member.js --labels`. - **`phone_number` must be a number** — send as integer (e.g. `14155550123`), not a string. Xano types this field as `integer`. - **Password requirements** — minimum 8 characters; must include: uppercase, lowercase, number, and special character (e.g. `@!#$%^&*`). - **Email is lowercased** — the frontend lowercases email before sending. Scripts do the same automatically. - **`Origin` header is injected automatically.** `notifyer-api.js` adds `Origin: https://console.notifyer-systems.com` for console-mode requests and `Origin: https://chat.notifyer-systems.com` for chat-mode requests. You never need to pass it manually. If a script sets `Origin` via `extraHeaders`, that value takes precedence. This fixes a class of silent 401s that occurred when the header was missing on Xano endpoints that validate it. - **Token storage** — store `authToken` in `NOTIFYER_API_TOKEN`. Never commit tokens to source control. - **Duplicate email** — signup fails with a Xano precondition error if the email already exists. The script surfaces this as `{ ok: false, error: "..." }`. - **Signup side effects** — a single signup call automatically creates the user record, an API key record, a subscriber_packages (plan) record, and fires a Make webhook. No additional calls are needed. - **No email invitation flow** — `invite-member.js` creates the account directly. Share credentials with the new member out-of-band. There is no "pending invite" state. - **`update-member.js` fetches current state first** — you only need to supply the fields you want to change; unchanged fields are read from the existing member and re-sent. - **`labels` replaces, not appends** — `update-member.js --labels "Sales"` sets labels to exactly `["Sales"]`, removing any previous ones. - **Super Admin is immutable** — the account owner cannot be created, modified, or deleted via any script. - **Roles for Admin/TM-All auto-clear labels** — `update-member.js` sends `labels: []` automatically when the effective role is not `Team Member`. - **`plan_amount` is in cents** — `latest_plan.plan_amount` is in cents (Stripe convention). `get-user-plan.js` adds a `plan_amount_dollars` field for convenience. - **Subscription is browser-only** — `POST /api:Mk_r6mq0/sessions` creates a Stripe checkout session that requires a browser redirect. Agents cannot subscribe on behalf of a user — direct them to `https://console.notifyer-systems.com/pricing-plans`. - **Check plan before messaging** — gate send actions with `status ∈ ["active","trialing"]` and `usages < unique_number_limit`. - **WhatsApp connection is 1:1** — each Notifyer account is connected to exactly one WhatsApp Business number. There is no "list phone numbers" endpoint. `get-connection-status.js` returns the status of that single number. - **`isConnected` vs `has_embedded_user`** — `has_embedded_user` means a Meta Facebook account has been linked. `isConnected` (`registration.success && subscription.success`) means WhatsApp messaging is actually ready. Always check `isConnected` before sending messages. - **Daily limit on refresh** — `refresh-connection.js` re-triggers Meta registration. Meta rate-limits this per day. If you see a daily limit error, wait 24 hours. ## API group IDs Notifyer's backend uses Xano-style API group IDs in the URL path: | Group | Prefix | Used for | |-------|--------|----------| | Auth | `/api:-4GSCDHb` | Signup, login, get-me, api_key, team member CRUD | | Message Sending | `/api:hFrjh8a1` | Send template messages via Developer API key | | WhatsApp Connection | `/api:P5grzx1u` | Connection status, Meta re-registration | | Web/Console | `/api:bVXsw_FD` | Label CRUD (`/web/label_management`), recipients, team | | Roles | `/api:eWoClqoZ` | Get available label names for member assignment | | Plans | `/api:JZAUyiCs` | Plan listing and selection | ## Scripts <!-- FILE MAP START --> | File | Description | |------|-------------| | `scripts/lib/notifyer-api.js` | Base HTTP client — loads config, sends requests, handles errors | | `scripts/lib/args.js` | CLI argument parser (flags, booleans, numbers) | | `scripts/lib/result.js` | Standard output helpers — `ok()`, `err()`, `printJson()` | | `scripts/create-account.js` | `POST /api:-4GSCDHb/auth/signup` — create a new Notifyer account | | `scripts/login.js` | `POST /api:-4GSCDHb/auth/login` — login and get an auth token | | `scripts/get-me.js` | `GET /api:-4GSCDHb/auth/me` — get the authenticated user's profile | | `scripts/get-connection-status.js` | `GET /api:P5grzx1u/is_user_embedded` — WhatsApp connection status | | `scripts/refresh-connection.js` | `POST /api:P5grzx1u/refresher_of_registration_subscription` — force re-sync with Meta | | `scripts/list-plans.js` | `GET /api:JZAUyiCs/plans?filter=…` — list available subscription plan tiers | | `scripts/get-user-plan.js` | `GET /api:JZAUyiCs/user_plan` — current subscription and usage | | `scripts/list-members.js` | `GET /api:-4GSCDHb/auth/get_team_member` — list team members; `--labels` also fetches available label names | | `scripts/invite-member.js` | `POST /api:-4GSCDHb/auth/create_team_member` — create a team member account | | `scripts/update-member.js` | `PATCH /api:-4GSCDHb/auth/user` — update role, labels, name, or password | | `scripts/remove-member.js` | `DELETE /api:-4GSCDHb/auth/delete_team_member/:id` — permanently remove a member | | `scripts/list-labels.js` | `GET /api:bVXsw_FD/web/label_management` — list workspace labels (role-filtered) | | `scripts/create-label.js` | `POST /api:bVXsw_FD/web/label_management` — create a new label | | `scripts/update-label-keywords.js` | `PATCH /api:bVXsw_FD/web/label_management/:id` — update name or keywords (fetch-then-patch) | | `scripts/delete-label.js` | `DELETE /api:bVXsw_FD/web/label_management/:id` — permanently delete a label | | `scripts/get-api-key.js` | `GET /api:-4GSCDHb/api_key` — retrieve the Developer API key for Make/Zapier/n8n | | `scripts/doctor.js` | Pre-flight health check — validates base URL, token, WhatsApp connection, and plan status in one command | <!-- FILE MAP END --> ## References - `references/account-reference.md` — Full API reference for auth endpoints, field types, error codes, and token usage - `references/whatsapp-connection-reference.md` — Connection status fields, onboarding checklist, rate limits, and architecture notes - `references/plans-reference.md` — Plan filters, PricingTier shape, LatestPlan fields, status values, billing model - `references/team-reference.md` — Role system, team member CRUD endpoints, label assignment rules, common workflows - `references/labels-reference.md` — Label data model, all CRUD endpoints, keyword auto-assignment behaviour, role-filtering rules - `references/api-key-reference.md` — Developer API key retrieval, all three auth modes, and `send_template_message_by_api` reference for Make/Zapier/n8n ## Assets - `assets/signup-example.json` — Example signup request payload - `assets/connection-status-example.json` — Example connection status response - `assets/user-plan-example.json` — Example response from `get-user-plan.js` ## Security Notes - **`NOTIFYER_API_BASE_URL` must be `https://`.** All three skills enforce this at startup — any `http://` or non-HTTPS URL is rejected immediately to prevent tokens being sent unencrypted or to a rogue host. - **`--password` is visible in the OS process list.** CLI flags are readable via `ps aux` or `/proc/<pid>/cmdline` for the lifetime of the process. On shared or monitored machines, prefer injecting credentials via environment variables or a secrets manager rather than bare CLI flags. - **The JWT token from `login.js` is printed to stdout.** This is by design — the agent must capture it to export `NOTIFYER_API_TOKEN`. In orchestrated environments, ensure stdout is not persisted to unprotected logs. Treat the token like a session cookie. - **The Developer API key from `get-api-key.js` is printed to both stdout and stderr.** Store it immediately in a secrets manager. It provides direct WhatsApp send access without a session login. - **Zero npm dependencies.** All three skills use only Node.js built-ins — there is no supply chain risk from third-party packages. ## Limitations - **WhatsApp initial connection requires a browser.** The QR scan / embedded signup flow (WABA onboarding) cannot be scripted. An admin must complete it once via the Notifyer console UI (console.notifyer-systems.com). After that, `get-connection-status.js` and `refresh-connection.js` can manage the connection programmatically. - **WhatsApp OTP verification is browser-only.** The `PATCH /api:0hqyGRIz/whatsapp_verification/{userId}` endpoint (OTP submission during phone re-authentication) is triggered by the console UI. There is no script for this flow. - **WhatsApp Business Account (WABA) and Meta Business Suite setup must be done manually.** Phone number registration, business verification, and WABA approval are Meta-side processes outside the Notifyer API. - **Account creation is irreversible via script.** `create-account.js` creates a full Notifyer workspace. There is no delete-account endpoint. - **Password recovery must be done via the Notifyer web UI.** The reset flow (`GET /reset_password?email=` to trigger email + `PATCH /reset_password` to set the new password) requires the user to click a link in the email. There is no agent-accessible reset path that bypasses the email step. - **`refresh-connection.js` re-syncs an existing connection.** It cannot re-initiate a fully disconnected or revoked WABA — that requires going through the browser-based embedded signup again. - **Plan upgrades, downgrades, and credit purchases are browser-only (Stripe).** `list-plans.js` and `get-user-plan.js` are read-only. Changing plans (`POST /api:Mk_r6mq0/sessions`), accessing the billing portal (`POST /api:Mk_r6mq0/portal`), and buying credits (`POST /api:Mk_r6mq0/add_credits`) are Stripe redirect flows — not scriptable. - **Profile picture uploads and onboarding step markers are UI-only.** `PATCH /profile_picture_update`, `PATCH /payment_method_update`, and `PATCH /test_message_update` are completion flags set by the console onboarding UI. There are no scripts for these — they do not affect core messaging functionality once the account is set up. - **Super Admin role cannot be assigned via script.** Only Admin and Team Member roles are assignable through `update-member.js`. Super Admin is set by Notifyer at workspace creation. <!-- FILEMAP:BEGIN --> ```text [setup-notifyer file map]|root: . |.:{package.json,SKILL.md} |assets:{connection-status-example.json,signup-example.json,user-plan-example.json} |references:{account-reference.md,api-key-reference.md,labels-reference.md,plans-reference.md,team-reference.md,whatsapp-connection-reference.md} |scripts:{create-account.js,create-label.js,delete-label.js,doctor.js,get-api-key.js,get-connection-status.js,get-me.js,get-user-plan.js,invite-member.js,list-labels.js,list-members.js,list-plans.js,login.js,refresh-connection.js,remove-member.js,update-label-keywords.js,update-member.js} |scripts/lib:{args.js,notifyer-api.js,result.js} ``` <!-- FILEMAP:END -->


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)