Pular para o conteúdo principal

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 opera no disponível do projeto. A parte financeira (recarga, planos, faturas) fica no painel (board) — o widget não cobra nem altera plano.

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://assets.bzapper.com.br/widget/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://assets.bzapper.com.br/widget/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​

AtributoObrigatórioPadrãoDescrição
data-keysim—A chave wgt_… criada no painel em Widgets.
data-apinãohttps://api.bzapper.com.brBase da API. Troque apenas se usar um endpoint próprio.
data-positionnãobottom-rightSó 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://assets.bzapper.com.br/widget/v1/widget.js"
  data-key="SUA_CHAVE_WGT"
  data-position="bottom-left"
  data-api="https://api.bzapper.com.br"
  async
></script>

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.