Skip to main content
The Web Callback widget is a drop-in button you paste onto any website. A visitor clicks it, enters their number, confirms a one-time code, and Wave calls them back — all without an API key ever touching the browser. It runs on top of Web Callback: the widget places the same click-to-call, it just moves the trigger to your visitor’s browser instead of your backend.

​
Embed

Copy the snippet from your dashboard (Web Callback → Embed snippet) — your project id is filled in for you — and paste it just before the closing </body> tag:

​
How it works

1

Visitor requests a callback

They click the button and enter their Saudi mobile number.
2

They confirm a one-time code

Wave sends an SMS code; the visitor types it back. This proves they own the number, so the widget can never be used to dial a stranger.
3

Wave calls them

On a valid code, Wave places the callback. The call shows up in your Call Logs and fires your webhooks like any other call.
No API key in the browser. The widget only talks to the public /v1/public/widget/* endpoints, scoped by your public project_id. Your secret API keys stay on your servers.

​
Allowed origins

The widget is refused everywhere until you allowlist the sites that embed it. Add each site’s origin in the dashboard under Web Callback → Allowed origins (e.g. https://www.your-site.com). A request from any other origin is rejected with 403 WIDGET_ORIGIN_NOT_ALLOWED.
An origin is scheme + host + optional port, with no path — e.g. https://shop.example.com, not https://shop.example.com/contact. Only HTTPS is accepted (except http://localhost for local development).
Because the widget can spend money (each callback is a real call), we recommend adding Google reCAPTCHA v3. Create a v3 key pair, then add the site key to the snippet:
Wave verifies the token server-side on the first code request. Combined with the one-time code and the origin allowlist, this keeps automated abuse out.

​
Sandbox and Production projects

The widget follows the tier of the project in its data-project-id.
  • Sandbox project — Wave calls the visitor from the shared Wave number. The call uses the project’s sandbox minutes and is not charged.
  • Production project — Wave calls the visitor from the project’s own number. The call is charged like any production call and follows the production limits: the maximum call length, the organization’s concurrent-call limit and the call velocity limits. It does not use the sandbox minutes. The call shows in your call logs under Production.
When the visitor answers a production widget call, Wave connects the call the same way as a production callback. Do this before you go live:
  • Bind an IVR menu to your number. A bound IVR always comes first.
  • Or set a connect number: in the dashboard, open Settings → Connect number (owner or admin only). Wave calls this Saudi mobile or landline number and connects the visitor; the person who answers sees your project’s number. If nobody answers, the visitor hears a short message, then the call ends.
Widget calls have their own velocity counter. The calls-per-minute and calls-per-hour limits apply to widget calls and to API calls separately, with the same values. An organization can start up to the limit through the API and the same number again through the widget in each window.
A Production project with no own number (or with no active production API key) cannot place widget calls: the widget shows a neutral message and Wave returns 409 WIDGET_NOT_AVAILABLE. No call is placed and the visitor’s code stays valid, so they can try again when the project is set up. A code is valid only on the widget of the project that sent it.

​
Customisation

  • Language & direction — data-lang="ar" switches the widget to Arabic and flips it to right-to-left.
  • Colour — data-accent themes the launcher and panel.
  • Label — data-button-text overrides the launcher text.
The widget is a single self-contained script with no external dependencies and prefixed styles, so it won’t clash with your site’s CSS.