01 · diagnostic checklist
quick troubleshooting before filing.
Many delivery or auth errors arise from minor environment misconfigurations. Check these common points first:
1. Check Mock Delivery Setting
If messages are written to the database but no real WhatsApp/Telegram message arrives, verify if WAOTP_MOCK_DELIVERY=1 is set. Set it to 0 for live dispatch.
2. Verify API Key Header
Calls to /v1/otp/send and /v1/otp/verify require the secret key in the X-Api-Key header, NOT the bearer Authorization token.
3. Rate Limits & Mutual Exclusions
When you resend an OTP to the same phone number, prior active codes are automatically invalidated. Sending more than 5 OTPs per hour to one phone number triggers HTTP 429.
4. Test in Interactive Sandbox
Use the Dashboard OTP Tester to isolate whether the issue is with your client code or the server environment.
02 · issue types
choose the report template that fits.
API or UI Glitch
Report unexpected HTTP responses, schema errors, or rendering problems in the dashboard.
New Channel or Tool
Propose new notification channels (e.g. Discord, RCS, Twilio fallback) or dashboard enhancements.
Vulnerability Report
Found a security or cryptography flaw? Please report it responsibly directly to the lead maintainer.