Troubleshooting

Check the installed version

1npm ls @qentrah/whatsapp

Compare the installed version with the version noted in this guide. Inspect your lockfile before changing dependencies; prerelease behavior may differ between versions.

Import or module errors

Use only public import paths listed in API and exports. Avoid importing guessed paths inside dist. ESM-only packages require an ESM-aware application. Install declared peer dependencies in the consuming application.

Message accepted but not delivered

A successful send is not proof of delivery. Record the message id and inspect status webhooks. Confirm the configured business phone id, recipient, approved template and language. Surface API error categories from the returned exception rather than retrying every failure.

Security

• Store access tokens outside source control.
• Configure appSecret so outgoing Graph requests include appsecret_proof.
• Keep verifyToken private; Meta uses it only during webhook setup.
• Keep the raw webhook request body intact before signature verification.
• Do not log access tokens, app secrets, or full customer payloads in production.