Widget embutível

O widget do bZapper é um componente standalone que você embute no seu próprio sistema. Atrelado a um projeto, ele carrega os números conectados daquele projeto e permite que seus clientes gerenciem as conexões sozinhos — conectar via QR, desconectar e adicionar número — além de uma mini-dashboard de uso e consumo.

É um jeito de entregar a gestão de WhatsApp dentro do seu produto sem construir tela nenhuma: uma linha de código e está no ar.

Onde fica o quê

O widget gerencia as conexões do projeto. A parte financeira (planos e faturas) fica no painel — o widget não cobra nem altera plano.

A URL do script é fixa

O runtime mora sempre em https://widget.bzapper.com.br/v1/widget.js (CDN da DigitalOcean). Não invente subdomínios/caminhos — copie o snippet exato do painel em Widgets (ele já vem com a sua chave).

Como funciona, em uma frase

Você cria uma chave de widget (wgt_…) no painel, define quais origens (domínios) podem usá-la e cola o script no seu site. O widget conversa com a API do bZapper usando essa chave pública, travada por allowlist de origens (CORS) — a sua API key real nunca vai para o navegador.

1. Crie a credencial no painel

No painel, vá em Widgets e crie uma nova chave:

1. Escolha o projeto ao qual o widget será atrelado (os números desse projeto é que vão aparecer).
2. Configure a allowlist de origens: os domínios onde o widget pode rodar (ex.: https://app.seudominio.com, https://seudominio.com). Requisições de origens fora da lista são recusadas.
3. Copie a chave gerada, no formato wgt_…. Ela é pública — pode ir no HTML.

Chave pública, mas travada

A wgt_ aparece no HTML do seu site (é inevitável num widget de browser). A segurança não vem de esconder a chave, e sim da allowlist de origens: mesmo de posse da chave, ninguém consegue usá-la a partir de um domínio que você não autorizou.

2. Snippet flutuante (plug-and-play)

O modo mais simples: uma bolha no canto da tela que abre o widget num clique. Cole uma linha antes do </body>:

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

Pronto. O widget se injeta sozinho, lê os números do projeto e fica disponível num clique.

3. Snippet embedded (inline)

Quer o widget dentro de uma área específica da sua página (e não flutuando)? Carregue o script sem data-key e coloque o elemento <bzapper-widget> onde quiser renderizar:

<!-- carregue o runtime uma vez -->
<script src="https://widget.bzapper.com.br/v1/widget.js" async></script>

<!-- e renderize o widget onde quiser, como um bloco nativo -->
<bzapper-widget data-key="SUA_CHAVE_WGT"></bzapper-widget>

O elemento <bzapper-widget> ocupa o espaço do contêiner pai, como qualquer outro bloco do seu layout.

Atributos

Atributo	Obrigatório	Padrão	Descrição
data-key	sim	—	A chave wgt_… criada no painel em Widgets.
data-api	não	https://api.bzapper.com.br	Base da API. Troque apenas se usar um endpoint próprio.
data-position	não	bottom-right	Só no modo flutuante: bottom-right ou bottom-left.

No modo flutuante, os atributos vão no <script>. No modo embedded, vão no elemento <bzapper-widget>.

<!-- flutuante, no canto inferior esquerdo, API customizada -->
<script
  src="https://widget.bzapper.com.br/v1/widget.js"
  data-key="SUA_CHAVE_WGT"
  data-position="bottom-left"
  data-api="https://api.bzapper.com.br"
  async
></script>

4. Verifique a instalação

1. Abra a página onde colou o snippet e olhe a aba Network do navegador: deve haver um widget.js com status 200 vindo de widget.bzapper.com.br.
2. No modo flutuante, a bolha aparece no canto. No embedded, o bloco renderiza dentro do <bzapper-widget>.
3. Se aparecer erro de origem não autorizada, adicione o domínio exato na allowlist da chave (ver Troubleshooting).

Content-Security-Policy (CSP)

Se o seu site tem CSP, libere o script e as chamadas do widget:

script-src  https://widget.bzapper.com.br;
connect-src https://api.bzapper.com.br;

Em SPAs (React, Vue, Angular, Next…)

O widget é um Web Component autônomo — funciona em qualquer framework. Em apps de página única, injete o script uma vez (ex.: no index.html ou no layout raiz) e use a tag <bzapper-widget data-key="…"> no JSX/template como qualquer elemento. Em Next.js, carregue o script com next/script (strategy="afterInteractive"). A tag <bzapper-widget> não conflita com o seu CSS — todo o estilo do widget vive em Shadow DOM isolado.

O que o widget faz

Atrelado ao projeto da chave, o widget entrega a gestão completa das conexões:

• Listar os números conectados do projeto, cada um com status ao vivo (conectado, aquecendo, desconectado…).
• Conectar via QR — o cliente lê o QR e conecta um número novo ali mesmo.
• Desconectar um número existente.
• Adicionar número — se o plano do projeto permitir mais números.
• Mini-dashboard de uso/consumo do período: mensagens, números e storage.

Tudo isso sem o cliente sair do seu produto e sem você construir telas.

Segurança

• Origem / CORS. A chave só funciona a partir das origens que você cadastrou no painel. É o controle de acesso principal do widget.
• Chave pública. A wgt_ vai no HTML por design e não expõe a sua API key real. Ela só consegue o que o widget precisa (gerenciar conexões e ler uso do projeto), e só a partir das origens permitidas.
• Financeiro no painel. Recarga, planos e faturas ficam no painel. O widget opera no disponível — não cobra nem muda plano.

Troubleshooting

O widget não aparece / erro de "origem não autorizada". A origem (domínio) onde o widget está rodando não está na allowlist da chave. Vá em Widgets no painel, abra a chave e adicione a origem exata — incluindo o esquema (https://) e, se for o caso, a porta. Lembre que https://app.exemplo.com e https://exemplo.com são origens diferentes.

Aparece, mas sem números. Confirme que a chave está atrelada ao projeto certo e que esse projeto tem números. Em modo embedded, verifique que o data-key está no <bzapper-widget> (e não no <script>).

Quero apontar para outra API. Use data-api. O padrão é https://api.bzapper.com.br.

Próximos passos

• Conta, projetos e usuários — entenda como o projeto isola números e chaves.
• Webhooks — receba eventos de conexão (instance.connected, instance.disconnected…) em tempo real no seu backend.