Skip to main content
Use this page when an endpoint fails but the server is running.

​
First checks

Run these in order: 
curl http://localhost:1337/server/ok
curl -H "token: YOUR_TOKEN" http://localhost:1337/session/status
curl -H "token: YOUR_TOKEN" http://localhost:1337/webhook
If /server/ok fails, debug process, port, firewall, or reverse proxy first. If /session/status fails, debug token and session state before testing messages.

​
Unauthorized

WaGo did not find the session token in the database or cache. Fix:
  • Send token as a header.
  • Check for whitespace in the token.
  • Confirm the token exists with GET /session/all using admintoken.
  • If needed, create it with POST /session/init.

​
No session

The token exists, but no active WhatsApp client is loaded for it. Fix: 
curl -X POST http://localhost:1337/session/connect \
  -H "Content-Type: application/json" \
  -H "token: YOUR_TOKEN" \
  -d '{"Subscribe":["All"],"Immediate":true,"Phone":""}'
Then check /session/status.

​
Already Logged in when requesting QR

The token is already linked to WhatsApp. You do not need to scan again. Use /session/status to confirm the session, or /session/logout if you intentionally want to unlink and scan again.

​
Messages do not send

Check:
  • Session is connected and logged in.
  • Phone is a valid phone number or JID.
  • Required fields match exact case.
  • Media payload is a valid data URL when required.
  • The connected WhatsApp account is not rate limited.
  • The target user exists on WhatsApp.
Use /user/check before sending to new phone numbers.

​
Media upload fails

Common causes:
  • Wrong data URL prefix.
  • Base64 string is truncated.
  • Reverse proxy request size limit is too small.
  • WaGo cannot download a URL used by /send/mediaurl.
  • Media type is not supported by WhatsApp for that message type.
For documents, the current document handler expects: 
data:application/octet-stream;base64,

​
Webhooks do not arrive

Check:
  • /webhook returns the expected URL.
  • /session/connect subscribed to the event type.
  • Your webhook URL is reachable from the WaGo server.
  • Your receiver returns 2xx quickly.
  • Your reverse proxy allows the request body size.
Use ["All"] during debugging, then reduce subscriptions in production.

​
Call works but browser audio does not

Check:
  • Browser page is HTTPS.
  • User granted microphone permission.
  • Call is active and tracked in /call/status.
  • WebRTC offer uses sendrecv.
  • Browser set WaGo’s SDP answer as remote description.
  • Network does not require TURN relay.
TURN is currently coming_soon, so some production networks will fail until TURN is added.

​
Opus packet logs

If you see logs about short or empty Opus packets but the call works, they may be padding, keepalive, or non-audio RTP packets from the browser. They are not always a failure. If audio fails at the same time, check codec negotiation and make sure the browser is sending Opus audio.