Memulai API & Webhook

API CSWA.AI menghubungkan aplikasi, CRM, toko online, atau alat otomasi Anda ke WhatsApp: kirim pesan, baca percakapan, kelola kontak, dan terima pesan masuk secara langsung lewat webhook. Ikuti lima langkah ini dari nol.

1. Buat kunci API#

1. 1

   Langkah 1: Buka Integrasi › API & Webhook

   Buka API & Webhook, lalu klik Buat kunci.

2. 2

   Langkah 2: Beri nama, pilih mode & izin

   Pilih Test untuk mencoba dulu (tanpa pesan sungguhan), atau Produksi untuk kirim sungguhan. Centang izin seperlunya — mis. hanya pesan:kirim untuk sistem yang cuma mengirim notifikasi.

3. 3

   Langkah 3: Salin kunci — hanya tampil sekali

   Simpan kunci di variabel lingkungan server (mis. CSWA_API_KEY). Jangan taruh di kode yang berjalan di peramban, di aplikasi HP, atau di URL.

2. Kirim pesan pertama#

Salin perintah ini ke terminal, ganti kunci dan nomor tujuan (format internasional tanpa tanda +):

curl -X POST "https://api.cswa.ai/v1/messages" \
  -H "Authorization: Bearer KUNCI_API_ANDA" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to":"6281234567890","type":"text","text":{"body":"Halo! Pesan pertama dari API 👋"}}'

Jawaban berhasil (202) — pesan masuk antrean lalu dikirim dari nomor WhatsApp Anda:

{
  "id": "kk_0123456789abcdef0123456789abcdef0123",
  "status": "queued",
  "conversation_id": "ct_0123456789abcdef",
  "channel_id": "chd_pr_0123456789abcdef",
  "test": false
}

3. Pasang webhook & verifikasi tanda tangan#

Di tab Webhook, klik Tambah URL, isi URL https server Anda, centang event (mis. message.received), lalu salin rahasia. Setiap kiriman membawa header X-CSWA-Signature; tolak kiriman yang tanda tangannya tidak cocok.

// Node.js (Express) — baca badan MENTAH, jangan JSON.parse dulu.
import crypto from "node:crypto";
import express from "express";

const RAHASIA = process.env.WEBHOOK_SECRET; // whsec_…
const app = express();

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const badan = req.body.toString("utf8");
  const bagian = Object.fromEntries((req.get("X-CSWA-Signature") || "").split(",").map((x) => x.split("=")));
  const semuaV1 = (req.get("X-CSWA-Signature") || "").split(",").filter((x) => x.startsWith("v1=")).map((x) => x.slice(3));
  const t = Number(bagian.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return res.status(400).send("stempel waktu kedaluwarsa");
  const harus = crypto.createHmac("sha256", RAHASIA).update(`${t}.${badan}`).digest("hex");
  const cocok = semuaV1.some((v) => v.length === harus.length && crypto.timingSafeEqual(Buffer.from(v), Buffer.from(harus)));
  if (!cocok) return res.status(401).send("tanda tangan salah");

  res.sendStatus(200); // jawab cepat (≤ 10 detik), proses di belakang
  const event = JSON.parse(badan);
  // Cegah ganda: simpan event.id yang sudah diproses.
  console.log(event.type, event.data);
});

app.listen(3000);

Contoh PHP & Python ada di Menerima webhook. Klik Uji kirim di dasbor untuk memastikan server Anda menjawab 2xx.

4. Uji dengan kunci test#

Kunci …_test_… menjalankan semua pemeriksaan (izin, nomor, jendela 24 jam, STOP, template) lalu mengembalikan respons simulasi — tidak ada pesan terkirim dan tidak ada data yang berubah (percakapan, catatan, AI Agent, kontak & tag, broadcast, follow up, tagihan, resi, tiket, URL webhook). Respons membawa "test": true. Unggah media dan Uji kirim webhook tetap berjalan sungguhan. Setelah semua lancar, ganti dengan kunci produksi (…_live_…).

5. Galat umum & solusinya#

Daftar lengkap ada di Batas & galat; semua endpoint ada di Referensi API.