@tehlink-id/ngonek

SDK Resmi Node.js untuk platform Ngonek WhatsApp Gateway. Library ini mempermudah developer dalam mengintegrasikan pengiriman pesan WhatsApp (tunggal maupun massal/batch) dan verifikasi webhook signature di aplikasi Node.js.

Fitur Utama

• Pengiriman Pesan WhatsApp Tunggal (Teks kustom maupun menggunakan Template Database).
• Pengiriman Pesan Massal (Batch) dengan sistem antrean teratur untuk mencegah pemblokiran nomor.
• Verifikasi Webhook Signature terintegrasi menggunakan HMAC SHA-256 (timing-safe comparison).
• Zero Dependencies di sisi runtime (hanya menggunakan modul bawaan Node.js).
• Dukungan TypeScript penuh dengan autocompletion tipe data yang lengkap.

Instalasi

Instal paket menggunakan package manager pilihan Anda:

npm install @tehlink-id/ngonek

atau menggunakan Yarn / Pnpm:

yarn add @tehlink-id/ngonek
# atau
pnpm add @tehlink-id/ngonek

Penggunaan

1. Inisialisasi Client

Dapatkan Token API Anda terlebih dahulu dari Dashboard Ngonek pada menu API Developer.

import { NgonekClient } from '@tehlink-id/ngonek'

const client = new NgonekClient({
  apiKey: 'YOUR_API_TOKEN'
})

2. Kirim Pesan Tunggal

A. Pesan Kustom Biasa

client.sendMessage({
  deviceId: 'DEVICE_DATABASE_ID',
  receiver: '628123456789',
  message: 'Halo dari SDK Node.js Ngonek!'
})
.then(response => {
  console.log('Pesan Terkirim:', response)
})
.catch(error => {
  console.error('Gagal Mengirim:', error)
})

B. Menggunakan Template Database

client.sendMessage({
  deviceId: 'DEVICE_DATABASE_ID',
  receiver: '628123456789',
  templateId: 'TEMPLATE_DATABASE_ID',
  variables: {
    nama: 'Budi',
    tagihan: 'Rp 150.000'
  }
})
.then(response => {
  console.log('Pesan Terkirim:', response)
})
.catch(error => {
  console.error('Gagal Mengirim:', error)
})

3. Kirim Pesan Massal (Batch)

Sangat disarankan menggunakan API Batch untuk mengirim pesan dalam jumlah banyak secara bersamaan guna menghindari pemblokiran nomor WhatsApp oleh sistem WhatsApp.

A. Mode Pesan Kustom Per Penerima

client.sendBatchMessage({
  deviceId: 'DEVICE_DATABASE_ID',
  recipients: [
    {
      phone: '628123456789',
      message: 'Halo Budi, akun Anda telah aktif!'
    },
    {
      phone: '628987654321',
      message: 'Halo Andi, silakan konfirmasi kehadiran Anda.'
    }
  ],
  delay: 5 // Jeda pengiriman antar pesan (menit)
})
.then(response => {
  console.log('Batch Sukses:', response)
})
.catch(error => {
  console.error('Batch Gagal:', error)
})

B. Mode Template Database

client.sendBatchMessage({
  deviceId: 'DEVICE_DATABASE_ID',
  templateId: 'TEMPLATE_DATABASE_ID',
  recipients: [
    {
      phone: '628123456789',
      variables: {
        nama: 'Budi',
        tagihan: 'Rp 150.000'
      }
    },
    {
      phone: '628987654321',
      variables: {
        nama: 'Andi',
        tagihan: 'Rp 75.000'
      }
    }
  ],
  delay: 5
})
.then(response => {
  console.log('Batch Sukses:', response)
})
.catch(error => {
  console.error('Batch Gagal:', error)
})

C. Mode Custom Template String (Dinamis Seketika)

client.sendBatchMessage({
  deviceId: 'DEVICE_DATABASE_ID',
  template: 'Halo {nama}, tagihan Anda sebesar {jumlah} jatuh tempo pada {tanggal}.',
  recipients: [
    {
      phone: '628123456789',
      variables: {
        nama: 'Budi',
        jumlah: 'Rp 150.000',
        tanggal: '15 Juni'
      }
    }
  ],
  delay: 2
})
.then(response => {
  console.log('Batch Sukses:', response)
})
.catch(error => {
  console.error('Batch Gagal:', error)
})

4. Verifikasi Webhook Signature

Jika Anda menggunakan fitur Webhook dari Ngonek untuk menerima laporan status pengiriman pesan, Anda wajib memverifikasi signature yang dikirimkan pada header X-TehLink-Signature guna memastikan request tersebut asli dikirim dari server Ngonek.

import { NgonekUtils } from '@tehlink-id/ngonek'

// Express.js / Fastify Route Handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-tehlink-signature']
  const rawBody = JSON.stringify(req.body) // Gunakan raw body string
  const webhookSecret = 'YOUR_WEBHOOK_SECRET_KEY' // Dari dashboard Ngonek

  const isValid = NgonekUtils.verifyWebhookSignature(rawBody, signature, webhookSecret)

  if (!isValid) {
    return res.status(401).send('Signature tidak valid')
  }

  // Lanjutkan memproses payload webhook
  console.log('Webhook payload:', req.body)
  res.status(200).send('OK')
})

Penanganan Error (Error Handling)

SDK akan melempar error dengan format terstruktur jika terjadi kegagalan validasi atau masalah koneksi.

client.sendMessage({
  deviceId: 'INVALID_ID',
  receiver: '628123456789',
  message: 'Halo!'
})
.catch(error => {
  // error.message berisi deskripsi masalah dari server Ngonek
  console.error('Error Code:', error.statusCode) // contoh: 404
  console.error('Detail Error:', error.message) // contoh: Perangkat tidak ditemukan
})

Lisensi

MIT