First command to run
Before debugging anything else:
It validates the most common root causes in one pass (base URL, token, connection, plan).
Authentication failures (HTTP 401 / 403)
Token expired or missing
Symptoms:
- Most scripts return 401
get-me.js fails
Fix:
Symptoms:
- Console scripts work, chat scripts fail (or vice versa)
What to know:
- Console uses
Authorization: Bearer <jwt>
- Chat uses
Authorization: <jwt> (raw)
The skills handle this automatically, but custom wrappers often get it wrong. See Auth & environment.
WhatsApp connection issues
isConnected: false
Run:
If the number was just connected in the UI, refresh:
If this is a first-time setup, you must complete the embedded signup / QR scan in the console UI. It is not scriptable.
degraded: true
This can mean Meta returned hidden errors that may cause silent send failures. Treat it as “not healthy” until resolved. Use the console UI to resolve Meta-side issues, then re-check status.
Plan blocks (features not available)
Symptoms:
- Developer API key exists but integrations/bots fail
- Bot creation fails due to missing OpenAI key/settings
Check:
Template issues
Template not usable yet
Templates must be APPROVED by Meta before use in automation/broadcasts.
Message send failures in chat
24-hour window is closed
If free text fails, check:
Fix: use a template send (send-template.js) until the recipient messages again.
Webhook issues
Wrong webhook type / id
- Dev webhook id is integer
- IO webhook id is a text UUID
Signature secret lost
If you created a webhook with --signature, the secret is shown only once. If you didn’t store it, create a new webhook and deprecate the old one.
