FullstacknotesFullstackNotes

Panduan Integrasi & API

Dokumentasi teknis lengkap dan referensi API untuk menghubungkan sistem Anda.

Authentication

API FullstackNotes menggunakan API Key untuk melakukan autentikasi *request*. Anda dapat membuat dan mengelola API key Anda dari Dashboard.

Kirim API Key Anda melalui header HTTP X-API-Key atau Authorization (dengan format Bearer token).

curl -X GET https://api.fullstacknotes.org/api/v1/profile \
  -H "X-API-Key: fsk_live_123456789"

GET

Check Profile, Quota & Devices

/api/v1/profile

Endpoint ini digunakan untuk mengambil profil akun Anda, paket yang sedang aktif, sisa kuota bulan ini, beserta daftar perangkat (nomor WhatsApp) yang saat ini sedang terkoneksi (*online*). Anda wajib memeriksa ini untuk mendapatkan daftar perangkat beserta `session_id` masing-masing perangkat.

Example Request

curl -X GET https://api.fullstacknotes.org/api/v1/profile \
  -H "X-API-Key: fsk_live_123456789"

Example Response

{
  "user": {
    "name": "Budi Santoso",
    "email": "budi@example.com",
    "plan": "basic"
  },
  "quota": {
    "used": 150,
    "limit": 15000,
    "remaining": 14850,
    "period": "2026-10",
    "resets_at": "2026-10-31T17:00:00.000Z"
  },
  "devices": [
    {
      "session_id": "ses_01hyk...",
      "name": "Nomor CS Utama",
      "phone": "628123456789",
      "status": "connected"
    }
  ]
}

POST

Send Message

/api/v1/messages/send

Mengirim pesan teks ke nomor WhatsApp yang dituju. Pesan akan diproses oleh VPS WhatsApp Gateway tujuan secara langsung.

Request Body

phonerequiredstring

Nomor WhatsApp tujuan. Dapat diawali dengan 08... atau 628...

messagerequired*string

Isi pesan teks yang ingin dikirim. Jika parameter media_url digunakan, teks ini akan otomatis menjadi Caption dari gambar/media tersebut (bersifat opsional).

media_urloptionalstring

URL publik gambar, video, atau dokumen (contoh: https://.../gambar.jpg).

media_typeoptionalstring

Jenis media yang dikirim. Mendukung nilai: image, video, document, atau audio. Default: image.

session_idoptionalstring

ID spesifik perangkat pengirim. Jika kosong, sistem otomatis memakai perangkat pertama yang terhubung.

Example Request

curl -X POST https://api.fullstacknotes.org/api/v1/messages/send \
  -H "X-API-Key: fsk_live_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "081234567890",
    "message": "Halo, ini pesan percobaan dari API",
    "media_url": "https://example.com/image.jpg",
    "media_type": "image",
    "session_id": "ses_xxxxxxxx"
  }'

Example Response

{
  "success": true,
  "message_id": "msg_01hyk2x8z9b",
  "status": "sent",
  "recipient": "6281234567890",
  "quota": {
    "used": 15,
    "limit": 15000,
    "remaining": 14985,
    "period": "2026-10",
    "resets_at": "2026-10-31T17:00:00.000Z"
  }
}

GET

Check Message Status

/api/v1/messages/{message_id}

Endpoint ini digunakan untuk mengambil status pengiriman (delivery status) secara historis maupun real-time berdasarkan ID Pesan. Ini membantu Anda memastikan apakah pesan berhasil terkirim (sent) atau gagal (failed).

Example Request

curl -X GET https://api.fullstacknotes.org/api/v1/messages/msg_01hyk2x8z9b \
  -H "X-API-Key: fsk_live_123456789"

Example Response

{
  "message_id": "msg_01hyk2x8z9b",
  "target": "081234567890",
  "status": "sent",
  "error_message": null,
  "updated_at": "2026-06-21T08:00:05.000Z"
}

Blast API (Campaign)

Blast API mengirim satu pesan ke banyak nomor sekaligus lewat satu request. Pengiriman tidak langsung: campaign masuk antrean, lalu dikirim bertahap dengan jeda acak 60–180 detik, sesuai slot waktu dan batas harian, sama seperti Smart Blast di Dashboard. Pola ini menjaga nomor Anda tetap aman dari deteksi spam WhatsApp.

Tersedia di paket Production (Production, Growth, dan Enterprise), atau di paket apa pun dengan Blast Pass. Blast Pass Harian (Rp10.000, 150 pesan, 24 jam) atau Mingguan (Rp25.000, 700 pesan, 7 hari) dibeli lewat QRIS di Dashboard dan langsung membuka endpoint ini, tanpa ganti paket dan meski langganan utama sudah berakhir. Pesan blast saat memakai pass memotong kuota pass, bukan kuota bulanan. Tanpa paket Production atau pass aktif, Developer dan Lite mendapat 403 PLAN_NOT_ELIGIBLE. Masa transisi: Developer atau Lite yang dibayar sebelum 8 November 2026 tetap bisa blast sampai masa aktifnya habis; perpanjangan setelah tanggal itu mengikuti aturan baru. Setiap pengiriman memakai kuota WhatsApp bulanan paket. FSN adalah layanan Unofficial WhatsApp API; risiko pemblokiran nomor tetap ada dan menjadi tanggung jawab pengguna. Kirim hanya ke penerima yang sudah memberi izin.

Cara Pakai (Langkah demi Langkah)

  1. Hubungkan device WhatsApp di Dashboard, lalu ambil session_id-nya dari GET /api/v1/profile.
  2. Siapkan daftar nomor yang sudah memberi izin (opt-in). Kirim confirmed_opt_in: true sebagai pernyataan Anda.
  3. Buat blast dengan POST /api/v1/campaigns. Selalu sertakan header Idempotency-Key yang unik per blast, supaya retry karena timeout tidak membuat blast ganda.
  4. Simpan campaign_id dari respons. Periksa skipped (nomor yang dilewati) dan warnings.
  5. Cek progres dengan GET /api/v1/campaigns/{id} setiap beberapa menit, bukan setiap detik.
  6. Jika status on_hold: hubungkan ulang device atau pindahkan ke device lain dengan PATCH sebelum auto_stop_at (72 jam).
  7. Setelah selesai, ambil daftar nomor gagal dengan GET /api/v1/campaigns/{id}/targets?status=failed.

Status Campaign

statusArtiYang perlu Anda lakukan
runningSedang dikirim bertahap.Tunggu; cek berkala.
on_holdTertahan. status_reason: DEVICE_DISCONNECTED (device putus), DEVICE_BANNED (nomor diblokir/dikunci WhatsApp), SUBSCRIPTION_EXPIRED (masa langganan berakhir), atau PLAN_NOT_ELIGIBLE (paket di bawah Production, misalnya setelah downgrade ke Developer atau Lite).Hubungkan ulang / ganti device (wajib ganti jika DEVICE_BANNED), perpanjang paket, atau upgrade ke Production atau lebih tinggi. Lanjut otomatis.
pausedDijeda sistem. HIGH_INVALID_RATE: lebih dari 30% nomor tidak terdaftar di WhatsApp.Bersihkan daftar nomor, batalkan, lalu buat blast baru.
completedSemua nomor sudah diproses.Ambil laporan per nomor.
cancelledDibatalkan oleh Anda.—
stoppedDihentikan sistem. DEVICE_UNAVAILABLE: device tidak terhubung lebih dari 72 jam.Sisa nomor tidak memotong kuota; buat blast baru.

POST

Create Blast

/api/v1/campaigns

Membuat campaign blast dan memasukkan nomor ke antrean. Respons 201 berarti campaign sudah dibuat, belum berarti pesan sudah terkirim.

Headers

X-API-Keyrequiredstring
API key Anda.
Idempotency-Keyoptionalstring
1–100 karakter (A-Z a-z 0-9 _ - : .). Request ulang dengan key yang sama mengembalikan campaign yang sama (200, idempotent_replay: true) tanpa membuat blast baru. Jangan pakai ulang key untuk blast yang berbeda.

Request Body

namerequiredstring
Nama campaign, maks. 120 karakter.
session_idrequiredstring
Device pengirim (milik Anda, status terhubung). Bisa diganti device_id.
phone_numbersrequiredstring[]
Daftar nomor (08… atau 628…). Maks. per request: Production 500, Growth 1.000, Enterprise 2.000, Blast Harian 150, Blast Mingguan 700. Duplikat dan format salah dibuang dan dilaporkan di skipped.invalid.
confirmed_opt_inrequiredboolean
Wajib true: pernyataan bahwa seluruh penerima sudah mengizinkan menerima pesan dari Anda.
use_aioptionalboolean
false: kirim base_prompt apa adanya. true (default): kirim variasi acak dari spintax_template, misalnya {Halo|Hai} kak. Variasi sangat disarankan untuk mengurangi risiko blokir.
base_promptoptionalstring
Isi pesan saat use_ai: false (maks. 4.096 karakter, min. 5).
spintax_templateoptionalstring
Template spintax saat use_ai: true.
daily_limitoptionalnumber
Maks. nomor per hari untuk campaign ini, 1–100 (default 100). Batas harian device dan akun tetap berlaku.
time_slotsoptionalstring[]
Slot kirim WIB: pagi (08:00), siang (13:00), sore (16:00), malam (19:00). Kosong = mulai sekarang.
start_dateoptionalstring
Tanggal mulai YYYY-MM-DD (WIB). Kosong = hari ini.
image_urloptionalstring
URL gambar http(s) publik untuk dikirim bersama pesan.

Example Request

curl -X POST https://api.fullstacknotes.org/api/v1/campaigns \
  -H "X-API-Key: $FSN_API_KEY" \
  -H "Idempotency-Key: promo-nov-2026-batch-1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Promo November",
    "session_id": "ses_xxxxxxxx",
    "phone_numbers": ["081234567890", "6281234567891"],
    "use_ai": true,
    "spintax_template": "{Halo|Hai} kak, pesanan promo November sudah bisa diambil ya.",
    "confirmed_opt_in": true,
    "daily_limit": 100,
    "time_slots": ["pagi", "sore"]
  }'

Example Response (201)

{
  "success": true,
  "campaign_id": "6fa506b4-f844-4821-997b-b3bb42b8a220",
  "status": "running",
  "total_targets": 2,
  "estimated_days": 1,
  "skipped": {
    "invalid": [{ "input": "0812", "reason": "INVALID_FORMAT" }],
    "cooldown": ["6281234567892"]
  },
  "limits": { "per_device_per_day": 100, "per_user_per_day": 200 },
  "quota": { "used": 120, "limit": 15000, "remaining": 14880, "period": "2026-10", "resets_at": "2026-10-31T17:00:00.000Z" },
  "warnings": []
}

skipped.cooldown berisi nomor yang sudah menerima atau sedang mengantre blast dari Anda dalam 24 jam terakhir. warnings memberi tahu jika sisa kuota bulanan lebih kecil dari jumlah nomor (sisanya menunggu periode berikutnya) atau jika device masih dalam masa pemanasan.

Error Codes

HTTPcodePenyebab
400OPT_IN_REQUIREDconfirmed_opt_in bukan true.
400VALIDATION_ERRORField tidak valid; lihat field "field" pada respons.
400INVALID_MESSAGEPesan kosong atau terlalu panjang.
400MESSAGE_TOO_SHORTPesan kurang dari 5 karakter.
400TOO_MANY_LINKSLebih dari 2 link dalam satu pesan.
400LINK_SHORTENER_NOT_ALLOWEDMemakai pemendek link (bit.ly, s.id, tinyurl, dll).
400TOO_MANY_RECIPIENTSMelebihi maks. nomor per request untuk paket Anda.
400NO_VALID_RECIPIENTSTidak ada nomor berformat valid.
400DEVICE_NOT_AVAILABLEDevice bukan milik Anda atau tidak terhubung.
401UNAUTHENTICATEDAPI key tidak ada, salah, atau dicabut.
402SUBSCRIPTION_EXPIREDMasa berlangganan berakhir.
402MONTHLY_QUOTA_EXCEEDEDKuota bulanan sudah habis.
402BLAST_PASS_QUOTA_EXCEEDEDKuota Blast Pass yang aktif sudah habis; beli pass lagi.
403PLAN_NOT_ELIGIBLEPaket Anda di bawah Production dan tidak ada Blast Pass aktif.
409ACTIVE_CAMPAIGN_LIMITTerlalu banyak campaign berjalan bersamaan.
409DUPLICATE_CONTENTPesan sama persis sudah diblast dalam 24 jam; gunakan spintax.
409ALL_RECIPIENTS_IN_COOLDOWNSemua nomor sudah menerima blast dari Anda dalam 24 jam.
413PAYLOAD_TOO_LARGEBody lebih dari 256 KB.
429RATE_LIMITEDTerlalu banyak request; tunggu sesuai header Retry-After.

GET

Status & Laporan Blast

/api/v1/campaigns/{campaign_id}

Mengembalikan status campaign dan jumlah nomor per status. Untuk detail per nomor gunakan GET /api/v1/campaigns/{id}/targets (filter status: queued, sent, delivered, read, failed, invalid, pending, cancelled; limit 1–100; cursor dari next_cursor). Daftar semua campaign Anda: GET /api/v1/campaigns?limit=20&cursor=….

# Ringkasan status & progres
curl https://api.fullstacknotes.org/api/v1/campaigns/{campaign_id} -H "X-API-Key: $FSN_API_KEY"

# Detail per nomor (contoh: hanya yang gagal), dengan pagination
curl "https://api.fullstacknotes.org/api/v1/campaigns/{campaign_id}/targets?status=failed&limit=50" -H "X-API-Key: $FSN_API_KEY"

# Daftar campaign Anda (terbaru dulu)
curl "https://api.fullstacknotes.org/api/v1/campaigns?limit=20" -H "X-API-Key: $FSN_API_KEY"

Example Response: Campaign

{
  "campaign_id": "6fa506b4-f844-4821-997b-b3bb42b8a220",
  "name": "Promo November",
  "status": "on_hold",
  "status_reason": "DEVICE_DISCONNECTED",
  "source": "api",
  "session_id": "ses_xxxxxxxx",
  "total_targets": 250,
  "progress": { "queued": 130, "sent": 12, "delivered": 100, "read": 64, "failed": 2, "invalid": 6, "pending": 0, "cancelled": 0 },
  "on_hold_since": "2026-11-01T02:00:00.000Z",
  "auto_stop_at": "2026-11-04T02:00:00.000Z",
  "stopped_at": null,
  "created_at": "2026-10-31T09:00:00.000Z"
}

Example Response: Targets

{
  "data": [
    {
      "target_id": "0b9c…",
      "phone": "6281234567890",
      "status": "invalid",
      "error_code": "NOT_ON_WHATSAPP",
      "error": "Nomor tidak terdaftar di WhatsApp; tidak memotong kuota.",
      "scheduled_at": "2026-10-31T09:01:00.000Z",
      "sent_at": null,
      "delivered_at": null,
      "read_at": null
    }
  ],
  "next_cursor": "0b9c…"
}

Arti Status per Nomor

statusArtiMemotong kuota?
queuedMenunggu jadwal kirim.Belum
sentSudah diterima server WhatsApp, belum ada konfirmasi sampai di HP penerima.Ya
deliveredSudah sampai di HP penerima (delivered_at). Jika penerima membaca dan fitur tanda baca aktif, read_at ikut terisi.Ya
invalidNomor tidak terdaftar di WhatsApp (NOT_ON_WHATSAPP).Tidak
failedGagal setelah beberapa percobaan (SEND_FAILED) atau dihentikan (DEVICE_UNAVAILABLE).Tidak
pendingHasil tidak dapat dipastikan (UNCONFIRMED); tidak dikirim ulang otomatis agar tidak dobel.Ya
cancelledDibatalkan sebelum dikirim.Tidak

Status delivered dan waktu baca (read_at) diperbarui otomatis dalam beberapa detik setelah WhatsApp mengirim tanda terima. progress.read adalah bagian dari delivered. Penerima yang mematikan tanda baca (centang biru) tidak pernah mengirim read_at, dan pesan yang tetap sent bisa berarti HP penerima sedang offline.


PATCH

Ganti Device & Batalkan

/api/v1/campaigns/{campaign_id}

PATCH dengan session_id (atau device_id) memindahkan sisa antrean ke device lain milik Anda yang sudah terhubung. POST /api/v1/campaigns/{id}/cancel menghentikan campaign secara permanen; nomor yang belum terkirim ditandai cancelled dan tidak memotong kuota. Pembatalan tetap bisa dilakukan walau masa berlangganan sudah berakhir.

# Pindahkan sisa antrean ke device lain milik Anda yang sudah terhubung
curl -X PATCH https://api.fullstacknotes.org/api/v1/campaigns/{campaign_id} \
  -H "X-API-Key: $FSN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "ses_device_cadangan" }'

# Batalkan campaign (permanen; nomor yang belum terkirim tidak memotong kuota)
curl -X POST https://api.fullstacknotes.org/api/v1/campaigns/{campaign_id}/cancel -H "X-API-Key: $FSN_API_KEY"

Jika Device Terputus atau Nomor Terblokir

  1. Pengiriman otomatis ditahan (on_hold). Pesan yang tertahan tidak dihitung gagal dan tidak memotong kuota. Anda juga mendapat notifikasi di Dashboard.
  2. Jika device hanya terputus, scan ulang QR di Dashboard. Pengiriman lanjut otomatis.
  3. Jika WhatsApp memblokir atau mengunci nomor, sistem mendeteksinya otomatis: status device menjadi banned, campaign menjadi on_hold dengan status_reason: DEVICE_BANNED, dan Anda mendapat notifikasi. Hubungkan nomor lain lalu panggil PATCH dengan session_id device baru.
  4. Jika dalam 72 jam device tidak kembali dan tidak diganti, campaign otomatis stopped (DEVICE_UNAVAILABLE) dan sisa nomor ditandai gagal tanpa memotong kuota.

Batasan Anti-Spam

Kuota bulanan menentukan total pesan yang bisa dikirim. Batasan harian berikut bukan kuota: hanya mengatur kecepatan dan kualitas blast agar nomor tidak diblokir, dan berlaku sama untuk blast dari API maupun Dashboard. Pesan yang melewati batas harian tidak ditolak, melainkan dipindah otomatis ke hari berikutnya mulai pukul 08:00 WIB.

BatasanProductionGrowthEnterprise
Total pesanKuota bulanan paketKuota bulanan paketKuota bulanan paket
Kecepatan maks. per device per hari100150200
Kecepatan maks. per akun per hari (semua device)2005001.000
Nomor per request5001.0002.000
Campaign berjalan bersamaan235
Kecepatan maks. device baru (< 7 hari) per hari252525
BatasanBlast HarianBlast Mingguan
Total pesan150 dalam 24 jam700 dalam 7 hari
Kecepatan maks. per device per hari150100
Kecepatan maks. per akun per hari (semua device)150100
daily_limit maks.150100
Nomor per request150700
Campaign berjalan bersamaan22
Kecepatan maks. device baru (< 7 hari) per hari2525
  • Satu nomor, satu blast per 24 jam. Nomor yang sudah menerima atau sedang mengantre blast dari akun Anda dalam 24 jam terakhir otomatis dilewati.
  • Isi pesan: minimal 5 karakter, maksimal 2 link, tanpa pemendek link. Pesan yang sama persis tidak boleh diblast ulang dalam 24 jam, kecuali memakai spintax.
  • Auto-pause: jika setelah minimal 30 nomor diproses lebih dari 30% ternyata tidak terdaftar di WhatsApp, campaign dijeda (paused, HIGH_INVALID_RATE). Ini ciri daftar hasil scraping atau beli database.
  • Blast Pass berakhir atau kuotanya habis: nomor yang belum terkirim ditahan (on_hold, PLAN_NOT_ELIGIBLE, atau SUBSCRIPTION_EXPIRED jika langganan utama juga sudah berakhir) dan lanjut otomatis setelah Anda membeli pass lagi atau upgrade paket. Sisa kuota pass yang tidak terpakai hangus.
  • Langganan berakhir: pengiriman ditahan (on_hold, SUBSCRIPTION_EXPIRED) dan lanjut otomatis setelah paket diperpanjang. Target yang tertahan tidak dihitung gagal dan tidak memotong kuota.

Rate Limits & Quota

Setiap pesan yang berhasil dikirim akan mengurangi kuota bulanan Anda. Kuota dihitung per bulan kalender dan otomatis direset setiap tanggal 1 pukul 00:00 WIB. Kuota ini dipakai bersama oleh API, Bot, Campaign, dan pengiriman dari Dashboard. Untuk Bot, pesan masuk dan balasan dihitung terpisah: setiap pesan masuk yang diproses bot (diteruskan ke webhook Anda atau dijawab Bot AI) mengurangi 1 kuota, dan setiap balasan yang terkirim (dari Bot AI atau lewat API) mengurangi 1 kuota lagi. Pesan yang gagal terkirim (misalnya nomor tidak terdaftar atau error server) tidak memotong kuota.

Jika kuota bulanan habis, API mengembalikan status 402 Payment Required dengan kode MONTHLY_QUOTA_EXCEEDED (sebelumnya DAILY_QUOTA_EXCEEDED). Selain itu ada rate limit per detik sesuai paket; jika terlampaui, API mengembalikan 429 Too Many Requests.

Response dari endpoint kirim pesan dan profil menyertakan informasi rate limit dan kuota di header:

HTTP/1.1 201 Created
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-Quota-Limit: 15000
X-Quota-Remaining: 14985
X-Quota-Reset: 2026-10-31T17:00:00.000Z

Contoh Response Kuota Habis

HTTP/1.1 402 Payment Required
Retry-After: 1209600

{
  "error": "Batas kuota bulanan (15000 pesan) telah tercapai. ...",
  "code": "MONTHLY_QUOTA_EXCEEDED",
  "used": 15000,
  "limit": 15000,
  "period": "2026-10",
  "resets_at": "2026-10-31T17:00:00.000Z"
}

WEBHOOK

Receiving Messages (Bot Webhook)

Anda dapat menerima pesan WhatsApp yang masuk ke nomor Anda secara real-time menggunakan fitur Bot Webhook. Setiap kali ada pesan masuk (Teks, Media, Grup) atau ada perubahan status, sistem kami akan mengirimkan HTTP POST request dengan payload JSON ke URL Webhook yang Anda tentukan di Dashboard.

Webhook Payload Format

Sistem akan mengirimkan data dengan format berikut ke endpoint Anda:

{
  "event": "message.received",
  "timestamp": "2026-06-21T08:00:00.000Z",
  "device": {
    "session_id": "ses_xxxxxxxx",
    "phone_number": "6281234567890"
  },
  "data": {
    "message_id": "msg_xxx",
    "from": "6289876543210",
    "from_name": "Budi Santoso",
    "text": "Halo, ini pesan dari pelanggan",
    "type": "text",
    "is_group": false
  }
}

Inbound vs Outbound (Memahami 2 Jenis Key)

Untuk membangun chatbot yang interaktif (tanya-jawab otomatis), sistem Anda harus menangani dua jalur komunikasi yang masing-masing menggunakan Key yang berbeda:

1. Inbound (Webhook)

Jalur ini menangkap pesan masuk dari pengguna WA ke sistem Anda.

Key: Webhook Secret
Fungsi: Server Anda menggunakan secret ini untuk memvalidasi signature bahwa data JSON tersebut asli berasal dari sistem FSN.

2. Outbound (API Request)

Jalur ini mengirim pesan balasan dari sistem Anda ke pengguna WA.

Key: X-API-Key
Fungsi: Server Anda mengirimkan header ini ke /messages/send sebagai tiket akses agar FSN mau memproses permintaan kirim pesan.

Security & Signature

Untuk memastikan bahwa request yang masuk ke endpoint Anda benar-benar berasal dari sistem kami (dan bukan dari pihak yang tidak bertanggung jawab), setiap request webhook dilengkapi dengan header X-FSN-Signature.

Header ini berisi HMAC-SHA256 hash dari raw payload JSON, menggunakan Webhook Secret yang bisa Anda dapatkan di menu Bot Dashboard.

// Contoh verifikasi Signature di Node.js / Express
const crypto = require('crypto');

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signatureHeader = req.headers['x-fsn-signature'];
  const webhookSecret = 'secret_dari_dashboard_anda';
  
  // Hash payload mentah
  const hash = crypto
    .createHmac('sha256', webhookSecret)
    .update(req.body) // raw body buffer
    .digest('hex');
    
  const expectedSignature = `sha256=${hash}`;
  
  if (signatureHeader !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  // Lanjut proses pesan...
  const payload = JSON.parse(req.body.toString());
  res.status(200).send('OK');
});

Tutorial: Integrasi Auto-Responder dengan n8n

Anda bisa membangun flow canggih tanpa coding menggunakan n8n. Berikut adalah panduan dasar membuat auto-responder:

1

Setup Webhook di n8n

Buat workflow baru di n8n dan tambahkan node Webhook. Ubah HTTP Method menjadi POST, lalu copy Webhook URL (baik Test atau Production) dari node tersebut.

2

Daftarkan Bot di FSN Gateway

Masuk ke Dashboard FSN (menu Bot), klik Create Bot, pilih Device Anda, lalu paste Webhook URL dari n8n. Pastikan status bot dalam keadaan aktif.

3

Test Koneksi Payload

Di n8n, klik Listen for Test Event. Kemudian di Dashboard FSN, klik tombol Test Webhook pada bot yang baru dibuat. n8n akan langsung mendeteksi skema data JSON yang dikirimkan.

4

Logic Filtering (Opsional)

Tambahkan node Switch (atau If) di n8n untuk merespon pesan tertentu. Contoh konfigurasi pengecekan kata PING:

Value 1: {{ $json.body.data.text }}
Condition: Equal
Value 2: PING
5

Kirim Pesan Balasan (Auto-Reply)

Hubungkan ke node HTTP Request untuk menembak API Gateway kita dan membalas pengirim.

MethodPOST
URLhttps://api.fullstacknotes.org/api/v1/messages/send
Header AuthX-API-Key: fsk_live_...
Body Parameters (JSON)
phone{{ $json.body.data.from }}
messagePONG! Bot n8n aktif 🚀

Official Node.js SDK

GitHub

Untuk mempermudah integrasi dengan project berbasis Node.js atau TypeScript, Anda dapat menggunakan Official SDK kami. SDK ini menyediakan metode yang aman, type-safe, dan praktis untuk mengakses API Gateway FSN.

Instalasi

npm install fsn-wa-sdk

Contoh Penggunaan

import { WAGateway } from 'fsn-wa-sdk';

const client = new WAGateway({
  apiKey: 'fsk_live_123456789',
  // gatewayBaseUrl: 'https://api.fullstacknotes.org/api/v1' // (Opsional)
});

async function run() {
  // Cek profil & dapatkan session_id perangkat yang aktif
  const profile = await client.getProfile();
  console.log(profile);
  
  const sessionId = profile.devices[0]?.session_id;

  if (sessionId) {
    // Kirim pesan
    const response = await client.sendMessage({
      session_id: sessionId,
      phone: '081234567890',
      message: 'Halo dari Node.js SDK!'
    });
    console.log('Status pengiriman:', response);
  }
}

run();

Tutorial: Custom Backend dengan Node.js (VPS)

Bagi Anda yang ingin mengelola bot sendiri di VPS, berikut adalah contoh *source code* menggunakan Express.js untuk memvalidasi signature dan membalas pesan otomatis.

const express = require('express');
const crypto = require('crypto');
const axios = require('axios');

const app = express();

// Simpan raw body untuk verifikasi HMAC
app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));

// Dapatkan dari halaman Dashboard Anda
const WEBHOOK_SECRET = 'whsec_xxxxxx';
const API_KEY = 'fsk_live_xxxxxx';

app.post('/webhook/whatsapp', async (req, res) => {
  // 1. Validasi Keamanan (Signature)
  const signature = req.headers['x-fsn-signature'];
  const hash = crypto.createHmac('sha256', WEBHOOK_SECRET)
                     .update(req.rawBody)
                     .digest('hex');
                     
  if (signature !== hash) {
    console.error('Peringatan: Signature tidak valid!');
    return res.status(401).send('Unauthorized');
  }

  const { event, data } = req.body;
  
  // 2. Filter Event Pesan Masuk Pribadi
  if (event === 'message.received' && !data.is_group) {
    console.log(`Pesan dari ${data.from_name} (${data.from}): ${data.text}`);
    
    // 3. Logic Bot Sederhana
    if (data.text.toLowerCase() === 'ping') {
       try {
         await axios.post('https://api.fullstacknotes.org/api/v1/messages/send', {
           phone: data.from,
           message: 'PONG! Balasan otomatis dari Node.js VPS 🚀'
         }, {
           headers: { 'X-API-Key': API_KEY }
         });
         console.log('Balasan berhasil dikirim!');
       } catch (error) {
         console.error('Gagal mengirim balasan:', error.message);
       }
    }
  }

  // 4. Selalu kembalikan status 200 OK agar gateway berhenti melakukan retry
  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Server webhook berjalan di port 3000'));

Catatan: URL Webhook yang Anda masukkan ke Dashboard harus dapat diakses publik (HTTPS). Anda dapat menggunakan Nginx sebagai Reverse Proxy untuk port 3000 atau menggunakan layanan seperti Ngrok selama masa development.


POST

Generate Saweran QRIS API

/api/saweran/create-qris

Endpoint publik ini digunakan untuk membuat kode QRIS donasi dinamis secara terprogram bagi streamer. Sistem akan menghubungi gateway Pakasir API dan mengembalikan qr_string standar nasional yang siap di-render menjadi QR Code di aplikasi penonton.

Example Request

curl -X POST https://api.fullstacknotes.org/api/saweran/create-qris \
  -H "Content-Type: application/json" \
  -d '{
    "username": "hendristream",
    "donor_name": "Sultan Budi",
    "donor_email": "budi@example.com",
    "amount": 25000,
    "message": "Semangat terus live streamingnya! 🔥"
  }'

Example Response

{
  "success": true,
  "order_id": "SWR-819274-902",
  "amount": 25000,
  "formattedAmount": "Rp 25.000",
  "donor_name": "Sultan Budi",
  "message": "Semangat terus live streamingnya! 🔥",
  "qr_string": "00020101021226610016ID.CO.SHOPEE.WWW011893600918...",
  "payment_url": "https://app.pakasir.com/pay/wa-gateway-fullstacknotes/25000?order_id=SWR-819274-902"
}