Embeddable widget

The bZapper widget is a standalone component you embed in your own system. Tied to a project, it loads that project's connected numbers and lets your customers manage the connections themselves — connect via QR, disconnect and add a number — plus a mini dashboard of usage and consumption.

It's a way to ship WhatsApp management inside your product without building any UI: one line of code and it's live.

Where things live

The widget operates within what the project has available. Billing (top-ups, plans, invoices) stays in the panel (board) — the widget never charges or changes a plan.

How it works, in one sentence

You create a widget key (wgt_…) in the panel, set which origins (domains) may use it, and paste the script into your site. The widget talks to the bZapper API with that public key, locked to an origin allowlist (CORS) — your real API key never reaches the browser.

1. Create the credential in the panel

In the panel, go to Widgets and create a new key:

1. Pick the project the widget is tied to (the numbers shown are that project's numbers).
2. Configure the origin allowlist: the domains where the widget may run (e.g. https://app.yourdomain.com, https://yourdomain.com). Requests from origins outside the list are rejected.
3. Copy the generated key, in the form wgt_…. It is public — it can ship in the HTML.

Public key, but locked

The wgt_ shows up in your site's HTML (unavoidable for a browser widget). Security doesn't come from hiding the key, but from the origin allowlist: even with the key in hand, nobody can use it from a domain you didn't authorize.

2. Floating snippet (plug-and-play)

The simplest mode: a bubble in the screen corner that opens the widget with one click. Paste one line before </body>:

<script
  src="https://assets.bzapper.com.br/widget/v1/widget.js"
  data-key="YOUR_WGT_KEY"
  async
></script>

That's it. The widget injects itself, reads the project's numbers and is available in one click.

3. Embedded snippet (inline)

Want the widget inside a specific area of your page (rather than floating)? Load the script without data-key and drop the <bzapper-widget> element wherever you want it to render:

<!-- load the runtime once -->
<script src="https://assets.bzapper.com.br/widget/v1/widget.js" async></script>

<!-- and render the widget wherever you like, like a native block -->
<bzapper-widget data-key="YOUR_WGT_KEY"></bzapper-widget>

The <bzapper-widget> element fills its parent container, like any other block in your layout.

Attributes

Attribute	Required	Default	Description
data-key	yes	—	The wgt_… key created in the panel under Widgets.
data-api	no	https://api.bzapper.com.br	API base. Only change it if you use a custom endpoint.
data-position	no	bottom-right	Floating mode only: bottom-right or bottom-left.

In floating mode the attributes go on the <script>. In embedded mode they go on the <bzapper-widget> element.

<!-- floating, bottom-left corner, custom API -->
<script
  src="https://assets.bzapper.com.br/widget/v1/widget.js"
  data-key="YOUR_WGT_KEY"
  data-position="bottom-left"
  data-api="https://api.bzapper.com.br"
  async
></script>

What the widget does

Tied to the key's project, the widget delivers full connection management:

• List the connected numbers of the project, each with live status (connected, warming, disconnected…).
• Connect via QR — the customer scans the QR and connects a new number right there.
• Disconnect an existing number.
• Add a number — if the project's plan allows more numbers.
• Mini dashboard of usage/consumption for the period: messages, numbers and storage.

All of it without the customer leaving your product, and without you building any screens.

Security

• Origin / CORS. The key only works from the origins you registered in the panel. That's the widget's main access control.
• Public key. The wgt_ ships in the HTML by design and does not expose your real API key. It can only do what the widget needs (manage connections and read the project's usage), and only from allowed origins.
• Billing in the panel. Top-ups, plans and invoices stay in the panel. The widget operates within what's available — it never charges or changes a plan.

Troubleshooting

The widget doesn't appear / "origin not authorized" error. The origin (domain) where the widget is running isn't in the key's allowlist. Go to Widgets in the panel, open the key and add the origin exactly — including the scheme (https://) and the port if any. Remember that https://app.example.com and https://example.com are different origins.

It appears, but with no numbers. Make sure the key is tied to the right project and that the project has numbers. In embedded mode, check that data-key is on the <bzapper-widget> (not on the <script>).

I want to point at a different API. Use data-api. The default is https://api.bzapper.com.br.

Next steps

• Account, projects and users — understand how a project isolates numbers and keys.
• Webhooks — receive connection events (instance.connected, instance.disconnected…) in real time on your backend.