FullstacknotesFullstackNotes
Log inMulai Sekarang

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 hari 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": 50000,
    "resets_at": "midnight WIB"
  },
  "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": 500
  }
}
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"
}

Rate Limits & Quota

Setiap panggilan API akan mengurangi kuota harian Anda. Kuota ini otomatis direset setiap hari pada jam 00:00. Jika kuota Anda habis, API akan mengembalikan status 429 Too Many Requests.

Setiap response HTTP dari API kami akan menyertakan informasi kuota di header:

HTTP/1.1 200 OK
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499
X-RateLimit-Reset: 1718928000
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 🚀

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.