SDKs oficiais

Bibliotecas oficiais do bZapper para integrar em minutos, na sua linguagem. Todas cobrem o mesmo conjunto de operações da API: os 13 tipos de mensagem (texto, imagem, vídeo, documento, áudio, sticker, localização, contato, enquete, reação, botões, lista e OTP), números/instâncias, API keys, uso, e as funções avançadas — grupos, presença, conversas e contatos.

Disponíveis nos registros oficiais 🎉

Instale com um comando — sem clonar nada. Node, Python, PHP, Go e Java já publicados (npm, PyPI, Packagist, Go modules e Maven Central).

O essencial: você só precisa da sua API key

O SDK já aponta para a API de produção (https://api.bzapper.com.br). Você não passa URL nenhuma — basta a sua API key (bz_live_..., gerada no painel em Chaves de API). Isso é tudo.

A URL da API é opcional e serve só para desenvolvimento (http://localhost:8080) ou self-host. Em produção, não informe nada.

Instalação

Linguagem	Instalação
Node / TypeScript	npm install @bzapper/client
Python	pip install bzapper
PHP	composer require bzapper/bzapper
Go	go get github.com/bernisoftware/bzapper-go@latest
Java (Maven)	veja o bloco <dependency> abaixo

Para Node, Python, PHP e Go o comando acima já baixa a versão mais recente e todas as dependências — você não adiciona mais nada.

Java — dependência (Maven / Gradle)

Adicione apenas o artefato do SDK. A única dependência de runtime (Jackson, para JSON) vem transitivamente — você não precisa declarar mais nada.

Maven (pom.xml):

<dependency>
  <groupId>br.com.bernisoftware</groupId>
  <artifactId>bzapper</artifactId>
  <version>0.5.0</version>
</dependency>

Gradle (build.gradle.kts):

implementation("br.com.bernisoftware:bzapper:0.5.0")

Requer Java 17+. Nada de Gson, OkHttp ou qualquer outra lib manual — o SDK usa o java.net.http.HttpClient do próprio JDK e puxa o Jackson sozinho.

Início rápido

Instalou? Então é só passar a API key e enviar. Nenhuma URL.

Node / TypeScript

import { Bzapper } from '@bzapper/client';

const bz = new Bzapper({ apiKey: 'bz_live_...' });
await bz.sendText({ to: '+5511999999999', body: 'Olá do bZapper! 👋' });

Python

from bzapper import Client

bz = Client("bz_live_...")
bz.send_text(to="+5511999999999", body="Olá do bZapper! 👋")

PHP

use Bzapper\Client;

$bz = new Client("bz_live_...");
$bz->sendText("+5511999999999", "Olá do bZapper! 👋");

Go

bz := bzapper.NewClient("bz_live_...")
bz.SendText(context.Background(), bzapper.SendTextParams{
    SendBase: bzapper.SendBase{To: "+5511999999999"},
    Body:     "Olá do bZapper! 👋",
})

Java

import com.bernisoftware.bzapper.BzapperClient;
import com.bernisoftware.bzapper.model.SendOptions;

var bz = new BzapperClient("bz_live_...");
bz.sendText(SendOptions.to("+5511999999999"), "Olá do bZapper! 👋");

Apontar para dev/self-host (opcional)

Só se você não estiver usando a produção:

new Bzapper({ apiKey: 'bz_live_...', baseUrl: 'http://localhost:8080' }); // Node

Client("bz_live_...", "http://localhost:8080")  # Python

new Client("bz_live_...", "http://localhost:8080"); // PHP

bzapper.NewClient("bz_live_...", bzapper.WithBaseURL("http://localhost:8080")) // Go

new BzapperClient("http://localhost:8080", "bz_live_..."); // Java

Dica: explore e teste tudo no Playground dentro do painel (admin), com envio real e exemplos de código prontos em cada linguagem.

Presença em grupo

Mostrar “digitando…” num grupo é só apontar a presença para o JID do grupo:

bz.presence_chat(instance_id=inst, to="[email protected]", state="typing")

Webhooks — receber e processar eventos

Os SDKs recebem o payload do webhook e processam pra você: verificam a assinatura HMAC (X-Bzapper-Signature), transformam o envelope num evento tipado e roteiam pra um handler por tipo. Cada SDK também faz o CRUD dos webhooks (createWebhook/listWebhooks/…). Eventos: message.{received,sent,delivered,read,failed}, instance.{connected,disconnected,banned,logged_out,warming,status}, group.{joined,participant_added,participant_removed,participant_promoted,participant_demoted,subject_changed,description_changed}.

Python

from bzapper.webhooks import Webhooks

hooks = Webhooks(secret="whsec_...")   # secret devolvido pelo create_webhook

@hooks.on("message.received")
def _(event):
    print(event.sender.name, event.payload["body"])

# no seu endpoint — corpo CRU + header. Lança SignatureError se inválido.
hooks.handle(raw_body=request.get_data(), signature=request.headers["X-Bzapper-Signature"])

Node / TypeScript

import { Webhooks } from '@bzapper/client';

const hooks = new Webhooks('whsec_...');
hooks.on('message.received', (e) => console.log(e.sender?.name, e.payload.body));

// Express: use express.raw() e o middleware pronto
app.post('/webhooks', express.raw({ type: '*/*' }), hooks.middleware());

Go

rx := bzapper.NewWebhookReceiver("whsec_...").
    On("message.received", func(e *bzapper.WebhookEvent) { /* ... */ })
http.Handle("/webhooks", rx) // é um http.Handler: verifica + roteia sozinho

PHP (new Bzapper\Webhooks($secret)) e Java (new Webhooks(secret)) seguem o mesmo padrão: on(tipo, handler) + handle(corpoCru, assinatura). Use o event_id para idempotência (a API pode reentregar). O verify é timing-safe; sempre passe o corpo CRU (não o JSON re-serializado).

Tratamento de erros

Todas as bibliotecas lançam um erro tipado com um código neutro estável (use sempre o code, nunca o texto) e o status HTTP. Ex. (Python):

from bzapper import Client, BzapperError
try:
    bz.send_text(to="+550000", body="oi")
except BzapperError as e:
    print(e.code, e.status_code)  # ex.: "instance_not_connected", 409

Cada SDK tem um README completo (no repositório do pacote) com exemplos de cada tipo de mensagem, grupos, presença, conversas e erros.