Logo VelaStack

WhatsApp

Depends: auth

Let users sign up and log in with a one-time code sent on WhatsApp, next to email. vela enable whatsapp adds a “Continue with WhatsApp” option to the login and signup pages that vela enable auth created, with form actions or with --remote.

Syntax

$ vela enable whatsapp

Run vela enable auth first; like auth, it needs shadcn-svelte, since the pages are built from its components. The command needs vela 0.15.13 or later. WhatsApp sign-in comes from a plugin in pocketbase-server 0.40.5-beta.5 and later; with an older PocketBase the command stops and says what to update.

What it adds

  • A Continue with WhatsApp option on /login and /signup. The user enters their number, gets a code on WhatsApp, and types it in on /whatsapp/[token].
  • src/lib/server/whatsapp.ts, the calls to the PocketBase plugin.
  • phone and phoneVerified fields on users. The number is unique among users who have one.
  • New accounts land on /welcome to pick a name, since all they have is a number.

Email becomes optional

A WhatsApp signup has no email, so enable whatsapp makes email optional on users. The pages auth, teams and payments generate already handle users without one:

  • Settings hides the email, verification and password sections from them.
  • The nav and team member lists show the name, then the phone number.
  • Billing creates their Stripe customer from the name and phone number.

Team invites still go to an email address, so a user without one sees no pending invites. There is no page yet for adding an email to an account made with a phone number.

Local development

Until you set a sender, codes are not sent: they show in the PocketBase logs of vela dev. Sign up with any number in international format, like +16165550123, and copy the code from there.

Sending codes in production

A deploy target without a sender hides the WhatsApp option. Set one with vela env set, which takes one key per command and prompts for its value. Codes go out through the VelaStack relay:

$ vela env set VELASTACK_API_KEY -t production

Or directly through the WhatsApp Cloud API, with a message template approved in your Meta Business account:

$ vela env set WHATSAPP_PHONE_NUMBER_ID -t production
$ vela env set WHATSAPP_ACCESS_TOKEN -t production
$ vela env set WHATSAPP_TEMPLATE_NAME -t production

WHATSAPP_WABA_ID is optional but recommended: without it the PocketBase admin can’t confirm the template is approved.

The sender follows the credentials that are set, so WHATSAPP_MODE is not needed: VELASTACK_API_KEY picks the relay and WHATSAPP_ACCESS_TOKEN the Cloud API. Set WHATSAPP_MODE only to override that: direct when a target has both credentials (the relay wins otherwise), or dev to keep codes in the PocketBase logs, on previews for example. WhatsApp sign-in itself is turned on by a migration enable whatsapp writes, so it reaches every deploy with the rest of your migrations.

Customized pages

enable whatsapp rewrites the login and signup pages, and only does so while they are still the pages enable auth wrote. If you changed a form, its page, server code and schema are left as they are and reported as failed; the other form is still updated. Add WhatsApp to your version by hand, using the WhatsApp pages as the reference.

Turn it back off with vela disable whatsapp.

Read as Markdown