Dashboard Utama

Node.js / JavaScript SDK

SDK resmi BaBlast membantu aplikasi backend mengirim pesan WhatsApp, mengelola kontak, mengirim template Official WABA, dan memverifikasi webhook dengan API yang konsisten.

TypeScript / Node.js SDK

Package resmi:

hljs bash
npm install @bablast/client

Alternatif package manager:

hljs bash
yarn add @bablast/client
pnpm add @bablast/client

SDK membutuhkan Node.js >=18 karena memakai runtime fetch bawaan.

Quickstart Berdasarkan Jenis API Key

1. Legacy / Device API Key

Legacy API Key sudah terikat ke satu sender. Jangan mengirim senderCode atau senderId.

hljs typescript
import { BablastClient } from "@bablast/client";

const legacyBablast = new BablastClient({
  apiKey: process.env.BABLAST_LEGACY_API_KEY!,
});

await legacyBablast.wa.sendText({
  to: "6281234567890",
  message: "Halo dari Legacy API Key!",
});

await legacyBablast.waba.sendTemplate({
  to: "6281234567890",
  templateName: "promo_agustus",
  language: "id",
});

2. Global API Key (Terbaru)

Global API Key dapat mengakses beberapa sender. Standard WA menggunakan senderCode. Untuk WABA dengan sender_code, reference_id, dan metadata, gunakan HttpClient karena wrapper WABA SDK saat ini belum mengekspos field tersebut.

hljs typescript
import { BablastClient, HttpClient } from "@bablast/client";

const globalBablast = new BablastClient({
  apiKey: process.env.BABLAST_GLOBAL_API_KEY!,
});

await globalBablast.wa.sendText({
  senderCode: "SND-A1B2C3",
  to: "6281234567890",
  message: "Halo dari Global API Key!",
  metadata: {
    reference_id: "REF-QUICKSTART-001"
  }
});

const http = new HttpClient({
  apiKey: process.env.BABLAST_GLOBAL_API_KEY!,
});

await http.request("/waba/send-template", {
  body: {
    sender_code: "SND-WABA01",
    phone: "6281234567890",
    template_name: "promo_agustus",
    language: "id",
    reference_id: "REF-QUICKSTART-002",
    metadata: {
      source: "sdk_quickstart"
    }
  }
});

Secara default SDK memakai base URL:

hljs text
https://api.bablast.id/v2/openapi

Modul SDK

ModulAksesKegunaan
Standard WAbablast.waKirim pesan teks, media, bulk, riwayat pesan, dan status sender.
Official WABAbablast.wabaKirim template WABA dan kelola template Meta.
Contactsbablast.contactsBuat kontak, grup kontak, dan bulk insert ke grup.
Webhooksbablast.webhooksVerifikasi signature, parse event, dan kelola konfigurasi webhook.

Standard WA

1. Legacy / Device API Key

hljs typescript
const result = await legacyBablast.wa.sendText({
  to: "6281234567890",
  message: "Terima kasih sudah mendaftar.",
  metadata: {
    reference_id: "REF-LEGACY-001",
    order_id: "INV-2026-9901"
  }
});

2. Global API Key (Terbaru)

hljs typescript
const result = await globalBablast.wa.sendText({
  senderCode: "SND-A1B2C3",
  to: "6281234567890",
  message: "Terima kasih sudah mendaftar.",
  metadata: {
    reference_id: "REF-2026-001",
    order_id: "INV-2026-9901",
    customer_tier: "VIP"
  }
});

const data = result.data as Record<string, unknown>;
console.log(data.message_id); // UUID transaksi internal BaBlast

SDK versi saat ini belum memiliki property referenceId tersendiri pada SendTextParams. Letakkan reference_id di dalam metadata; API akan mengekstraknya menjadi data.reference_id pada webhook dan menghapusnya dari data.metadata.

Kirim Media — Legacy / Device API Key

hljs typescript
await legacyBablast.wa.sendMedia({
  to: "6281234567890",
  mediaUrl: "https://example.com/invoice.pdf",
  mediaType: "document",
  caption: "Berikut faktur tagihan Anda.",
  filename: "invoice.pdf",
  metadata: {
    reference_id: "REF-LEGACY-002",
    order_id: "INV-2026-9901"
  }
});

Kirim Media — Global API Key

hljs typescript
await globalBablast.wa.sendMedia({
  senderCode: "SND-A1B2C3",
  to: "6281234567890",
  mediaUrl: "https://example.com/invoice.pdf",
  mediaType: "document",
  caption: "Berikut faktur tagihan Anda.",
  filename: "invoice.pdf",
  metadata: {
    reference_id: "REF-2026-002",
    order_id: "INV-2026-9901"
  }
});

Kirim Bulk — Legacy / Device API Key

hljs typescript
await legacyBablast.wa.sendBulk({
  message: "Halo {{name}}, voucher Anda: {{code}}",
  recipients: [
    { to: "6281234567890", variables: { name: "Budi", code: "DISC50" } },
    { to: "6281234567891", variables: { name: "Siti", code: "DISC50" } },
  ],
});

Kirim Bulk — Global API Key

hljs typescript
await globalBablast.wa.sendBulk({
  senderCode: "SND-A1B2C3",
  message: "Halo {{name}}, voucher Anda: {{code}}",
  recipients: [
    { to: "6281234567890", variables: { name: "Budi", code: "DISC50" } },
    { to: "6281234567891", variables: { name: "Siti", code: "DISC50" } },
  ],
});

Sender & QR Code

hljs typescript
const senders = await globalBablast.wa.senders.list();
const status = await globalBablast.wa.senders.getStatus("12");
const qr = await globalBablast.wa.senders.getQrCode("12");

Official WABA

1. Legacy / Device API Key

hljs typescript
await legacyBablast.waba.sendTemplate({
  to: "6281234567890",
  templateName: "payment_confirmation",
  language: "id",
  parameters: ["Budi", "INV-001"],
});

2. Global API Key (Terbaru)

waba.sendTemplate() versi saat ini belum mengekspos senderCode, referenceId, atau metadata. Gunakan HttpClient agar Global API Key dapat memilih sender melalui sender_code:

hljs typescript
import { HttpClient } from "@bablast/client";

const http = new HttpClient({
  apiKey: process.env.BABLAST_GLOBAL_API_KEY!,
});

await http.request("/waba/send-template", {
  body: {
    sender_code: "SND-WABA01",
    phone: "6281234567890",
    template_name: "payment_confirmation",
    language: "id",
    parameters: ["Budi", "INV-001"],
    reference_id: "REF-2026-003",
    metadata: {
      customer_tag: "VIP"
    }
  }
});

Kelola Template — Legacy / Device API Key

hljs typescript
const templates = await legacyBablast.waba.templates.list();

await legacyBablast.waba.templates.create({
  name: "payment_confirmation",
  category: "UTILITY",
  language: "id",
  components: [
    {
      type: "BODY",
      text: "Halo {{1}}, pembayaran invoice {{2}} sudah kami terima.",
    },
  ],
});

Kelola Template — Global API Key

hljs typescript
const templates = await http.request(
  "/waba/templates?sender_code=SND-WABA01"
);

await http.request("/waba/templates", {
  body: {
    sender_code: "SND-WABA01",
    name: "payment_confirmation",
    category: "UTILITY",
    language: "id",
    components: [
      {
        type: "BODY",
        text: "Halo {{1}}, pembayaran invoice {{2}} sudah kami terima."
      }
    ]
  }
});

Contacts & Groups

hljs typescript
await globalBablast.contacts.createGroup({
  name: "Pelanggan VIP 2026",
  code: "VIP_2026",
});

await globalBablast.contacts.create({
  name: "Budi Santoso",
  phone: "6281234567890",
  email: "[email protected]",
  groupCode: "VIP_2026",
});

await globalBablast.contacts.addBulkToGroup("12", [
  { name: "Siti Rahma", phone: "6281234567891" },
  { name: "Andi Wijaya", phone: "6281234567892" },
]);

HttpClient mengembalikan envelope JSON API tanpa proses unwrap. Karena beberapa type response package saat ini masih menggambarkan isi data secara langsung, periksa respons runtime sebelum mengakses hasil create/list yang akan dipakai kembali.

Webhook Verification

Gunakan modul webhooks untuk memverifikasi signature HMAC SHA-256 sebelum memproses payload.

hljs typescript
import express from "express";
import { BablastClient } from "@bablast/client";

const app = express();
const bablast = new BablastClient({ apiKey: process.env.BABLAST_API_KEY! });

app.post(
  "/webhook/bablast",
  express.text({ type: "application/json" }),
  async (req, res) => {
    const signature = req.get("X-Webhook-Signature") || "";
    const isValid = await bablast.webhooks.verifySignature(
      req.body,
      signature,
      process.env.BABLAST_WEBHOOK_SECRET!
    );

    if (!isValid) {
      return res.sendStatus(401);
    }

    const payload = JSON.parse(req.body);
    const event = bablast.webhooks.parseEvent(payload);
    const senderCode = payload.sender_code;

    if (event.event === "incoming_message") {
      console.log("Pesan masuk dari sender:", senderCode, event.data);
    }

    if (
      [
        "message_status",
        "message_sent",
        "message_delivered",
        "message_read",
        "message_failed"
      ].includes(event.event)
    ) {
      const statusData = event.data as Record<string, unknown>;
      console.log("Reference ID:", statusData.reference_id);
      console.log("Metadata kustom:", statusData.metadata);
    }

    res.sendStatus(200);
  }
);

Gunakan body mentah (express.text) saat memverifikasi signature agar byte yang dihitung sama dengan body yang ditandatangani BaBlast. Pada versi SDK saat ini, parseEvent() juga belum memetakan top-level sender_code; ambil nilainya langsung dari payload seperti contoh di atas.

Client Options

hljs typescript
const bablast = new BablastClient({
  apiKey: "YOUR_API_KEY",
  baseUrl: "https://api.bablast.id/v2/openapi",
  timeoutMs: 30_000,
  retries: 2,
  authHeaderMode: "x-api-key",
  headers: {
    "x-app-name": "my-backend",
  },
});
OptionDefaultDeskripsi
apiKeyWajibAPI key BaBlast.
baseUrlhttps://api.bablast.id/v2/openapiOverride base URL, misalnya untuk white-label domain.
timeoutMs30000Timeout request dalam milidetik.
retries2Retry otomatis untuk timeout, rate limit, dan error server.
authHeaderModex-api-keyGunakan x-api-key atau bearer.

Error Handling

hljs typescript
import { BablastClient, BablastError } from "@bablast/client";

const globalBablast = new BablastClient({
  apiKey: process.env.BABLAST_GLOBAL_API_KEY!,
});

try {
  await globalBablast.wa.sendText({
    to: "invalid_phone",
    message: "Halo",
    senderCode: "SND-A1B2C3",
  });
} catch (error) {
  if (error instanceof BablastError) {
    console.error(error.status);
    console.error(error.code);
    console.error(error.response);
  }
}