10. Otomasi

Otomasi menjalankan aksi otomatis setiap kali kejadian tertentu terjadi di workspace. Aksi yang tersedia:

Pasang tag — menandai kontak yang baru masuk dengan label tertentu.
Balas teks otomatis — kirim teks balasan ke pelanggan.
Tugaskan ke agen — set agen yang menangani percakapan.
Panggil webhook — POST JSON ke URL eksternal (integrasi n8n, Zapier, sistem internal).

Pemicu × aksi yang valid:

Pemicu	Pasang tag	Balas teks	Tugaskan agen	Panggil webhook
Kontak baru	✅	—	—	✅
Pesan masuk	—	✅	✅	✅
Tag ditambahkan	—	—	✅	✅
Jadwal (cron)	—	—	—	✅

10.1 Lihat daftar otomasi

Buka Otomasi dari sidebar atau /workflow. Tabel menampilkan setiap otomasi dengan nama, pemicu, aksi (chip tag atau preview teks), status, dan jumlah eksekusi.

10.2 Buat otomasi baru

Klik ”+ Otomasi baru” di kanan atas.
Isi:
- Nama otomasi — bebas, mis. “Greeting jam kerja” atau “Tag pendaftar form Bandung”
- Pemicu — pilih dari dropdown: Kontak baru, Pesan masuk, Tag ditambahkan, atau Jadwal (cron)
- Tag yang memicu (hanya untuk pemicu Tag ditambahkan) — pilih satu tag dari daftar workspace; otomasi cuma jalan kalau tag spesifik ini dipasang.
- Cron expression + Timezone (hanya untuk pemicu Jadwal) — format cron 5-field (mis. 0 9 * * 1 = setiap Senin 09:00). Ada dropdown preset untuk pola umum. Default timezone Asia/Jakarta. Cek crontab.guru untuk eksperimen.
- Aksi (dropdown kedua, muncul kalau pemicu punya >1 pilihan aksi):
  - Pesan masuk → Balas teks otomatis atau Tugaskan ke agen
  - Tag ditambahkan → Tugaskan ke agen
- Form parameter aksi muncul sesuai aksi yang dipilih:
  - Pasang tag — pilih chip; minimal 1
  - Balas teks otomatis — textarea (maks 4096 karakter) + checkbox “Hanya saat pesan pertama dari kontak” (default ✓)
  - Tugaskan ke agen — dropdown daftar anggota workspace + checkbox “Hanya jika belum ada agen yang menangani” (default ✓)
  - Panggil webhook — URL https:// (atau http://localhost untuk testing) + secret opsional. Lihat §10.5 untuk payload + signature.
- Langsung aktifkan setelah disimpan — centang untuk langsung jalan
Klik “Simpan” → Anda diarahkan ke halaman detail.

10.3 Apa yang memicu otomasi

Kontak baru jalan setiap kali kontak baru dibuat di workspace, dari sumber manapun:

Tombol “Tambah kontak” di halaman Kontak
Impor CSV
Form publik (/f/[slug])

Tag ditambahkan jalan saat tag spesifik dipasang ke kontak lewat:

Halaman Kontak: edit kontak (form), bulk-tag toolbar, atau form pendaftaran auto-tag.
TIDAK termasuk: tag yang dipasang lewat aksi otomasi lain (mis. workflow “Kontak baru → Pasang tag VIP”). Anti-loop sengaja dilanggar di sini supaya cascading otomasi tidak terjadi tidak sengaja.

Otomasi tag-added mencari percakapan aktif (OPEN/PENDING) milik kontak — kalau ada, assign-agent jalan; kalau tidak ada (kontak baru tanpa percakapan), workflow run di-log SUCCESS dengan no-op.

Aksi tag-added cuma fire untuk tag yang baru ditambahkan — bulk-tag 100 kontak yang 80-nya sudah punya tag itu hanya memicu 20 run, bukan 100.

Pesan masuk jalan setiap kali pelanggan kirim pesan ke nomor WhatsApp Anda (Mode Cepat atau Mode Resmi). Beberapa aspek penting:

Balas teks — “Hanya saat pesan pertama dari kontak” (default ✓): otomasi hanya jalan saat itu inbound pertama dari percakapan tersebut. Kalau auto-reply pelanggan balik ke Anda, ia bukan pesan pertama lagi → Karibin tidak balas otomatis lagi → loop terhindar.
Tugaskan ke agen — “Hanya jika belum ada agen yang menangani” (default ✓): otomasi skip percakapan yang sudah di-claim operator. Hilangkan centang kalau Anda mau selalu paksa-route ke agen ini (mis. semua inbound harus ke senior CS).
Hilangkan centang “pesan pertama” kalau Anda mau balas setiap inbound (mis. ack receipt untuk integrasi). Risiko: kalau pelanggan juga punya auto-reply, balasan bisa berputar terus.

Balasan otomatis dikirim via provider WhatsApp yang aktif (Baileys atau Meta). Untuk Baileys, guard ban-avoidance (warming cap) tetap diterapkan; cold-contact guard di-bypass otomatis karena pelanggan barusan chat.

Jika agen target sudah keluar dari workspace (mis. dihapus, role demoted), aksi assign-agent gagal dengan error di Riwayat jalan (“no longer a workspace member”). Otomasi tetap aktif — edit ke agen lain via halaman detail otomasi, lalu Simpan.

Pemicu jadwal (cron) fire berulang sesuai cron expression yang Anda set. Tidak butuh kontak/pesan/tag untuk fire — pure schedule. Use case: daily ping ke sistem eksternal jam 9 pagi untuk sync state, mingguan reminder, dll.

Cron expression: 5-field standar (menit jam tgl bulan hari). Contoh: 0 9 * * 1 = setiap Senin jam 09:00. Setiap field bisa * (semua), nilai literal, range (0-23), step (*/5), atau list (1,3,5).
Timezone: default Asia/Jakarta. Karyawan/audiens Anda di luar WIB ganti ke Asia/Makassar (WITA), Asia/Jayapura (WIT), atau UTC.
Pasangan aksi: hanya Panggil webhook (event terjadwal tidak punya konteks kontak/percakapan, jadi aksi lain tidak masuk akal). Payload yang dikirim ke URL Anda lihat di bawah.
Pause / aktifkan dari halaman detail menonaktifkan / mengaktifkan schedule. Hapus workflow → schedule otomatis di-remove dari Redis.
Backend worker process (karibin-worker) yang fire schedule — kalau worker mati, schedule pause sampai worker hidup lagi (BullMQ catch-up policy: kalau worker mati saat schedule due, fire begitu hidup).

Payload yang dikirim ke webhook saat scheduled fire:

{
  "event": "scheduled",
  "workspaceId": "ws_...",
  "timestamp": "2026-06-02T02:00:00.000Z",
  "data": {
    "workflow": { "id": "wf_...", "name": "Daily ping" },
    "cronExpression": "0 9 * * *",
    "timezone": "Asia/Jakarta"
  }
}

10.4 Kondisi (gate) & Delay sebelum aksi

Setiap otomasi punya dua kontrol opsional yang berlaku di semua kombinasi pemicu × aksi. Buka Lanjutan: kondisi & delay di form buat/edit otomasi.

Kondisi — gate yang dievaluasi sebelum aksi jalan. Kalau kondisi tidak terpenuhi, aksi dilewati (tidak jalan), statistik run tidak bertambah, dan log Riwayat jalan dicatat dengan tag “Dilewati” + alasan (mis. skipped: condition-not-met (contact does not have required tag)). Pilihan:

Kontak punya tag… — hanya jalan kalau kontak memiliki tag spesifik (mis. “VIP”, “Reseller”). Pilih tag dari dropdown.
Kontak TIDAK punya tag… — kebalikannya. Berguna untuk skip kontak yang sudah pernah di-greet (“greeted-already”).
Kontak punya nomor WA — skip kontak email-only (tidak bisa di-WA).
Kontak BELUM ada nomor WA — sebaliknya, mis. trigger email follow-up untuk kontak yang belum kasih nomor.
Kontak punya email — gate untuk aksi yang butuh email (kalau ada).

Kondisi tidak berlaku untuk pemicu Jadwal (cron) — tidak ada kontak dalam konteks scheduled trigger, jadi field dilewati otomatis.

Delay sebelum aksi jalan — jeda dalam detik antara pemicu fire dan aksi jalan. Default 0 (jalan langsung). Maks 86400 detik (24 jam). Use case:

Tag kontak baru, lalu kirim balas teks otomatis 30 detik kemudian supaya tidak terlihat seperti robot instan.
Balas pesan masuk 3 menit kemudian (180 detik) untuk human-like delay.
Tugaskan agen 10 menit kemudian kalau tidak ada operator yang manual-claim percakapan terlebih dulu.

Implementasi delay pakai BullMQ delayed job — saat pemicu fire, payload (workflowId + konteks kontak/pesan) di-enqueue ke Redis dengan timer. Worker process (karibin-worker) mem-fire aksi saat timer jatuh tempo.

Safety:

Kalau workflow di-pause/hapus sebelum delay jatuh tempo, job otomatis dilewati saat worker pick up (cek status === ACTIVE).
Kalau Redis sempat down saat enqueue, otomasi fallback ke run inline (log warning di server, tapi tidak gagal silently).
Delay tidak berlaku untuk pemicu Jadwal (cron) — schedule sendiri sudah menentukan kapan aksi jalan.

Riwayat jalan menampilkan timestamp saat aksi benar-benar dijalankan (bukan saat trigger fire), jadi delay terlihat sebagai gap di log.

10.5 Detail otomasi & status

Klik baris otomasi → halaman detail (/workflow/[id]):

Kanan atas: tombol Aktifkan / Jeda (toggle status) + Hapus
Kolom kiri: mulai dengan kartu Alur otomasi — canvas interaktif berbasis react-flow menampilkan node Pemicu → [Delay?] → [Kondisi?] → Aksi, dievaluasi kiri-ke-kanan, dengan ringkasan tiap node (nama tag yang diset, cron expression, hostname webhook, dll). Canvas mendukung pan (drag kosong) + zoom (scroll/Controls). Di kanan atas kartu ada palette dengan chip + Delay dan + Kondisi: klik atau drag chip ke canvas untuk menambah node ke alur (default value: delay 60 detik, kondisi contact-has-phone). Setelah ditambahkan, modal edit otomatis terbuka supaya bisa langsung di-tweak. Chip otomatis disabled kalau slot sudah ada di alur (cuma satu Delay dan satu Kondisi per otomasi) atau kalau pemicu = Jadwal (cron). Klik node untuk edit inline — modal terbuka dengan field yang sesuai (pemicu: cron/tag pemicu; kondisi: pilih gate; delay: detik; aksi: tag/body/agen/URL). Untuk Delay/Kondisi, modal punya tombol merah Hapus dari alur di kiri footer — klik untuk hilangkan dari otomasi. Setelah Simpan, canvas auto-refresh. Untuk mengubah JENIS pemicu/aksi (mis. dari “kontak baru” ke “pesan masuk”), tetap pakai form di bawah canvas karena perubahan jenis cascade ke validitas params + scheduler. Catatan urutan: Delay digambar SEBELUM Kondisi karena itulah runtime sesungguhnya — saat trigger fire, payload masuk antrian Redis; setelah delay habis, baru kondisi dievaluasi terhadap state kontak terkini (kalau kontak berubah selama delay, kondisi melihat state baru).
Kolom kanan: riwayat jalan — 50 entri terakhir dengan timestamp, status (Sukses/Gagal/Dilewati), id konteks (kontak atau pesan yang memicu). Tag Dilewati (abu-abu) muncul saat kondisi gagal terpenuhi.

Status:

Draf — disimpan tapi tidak jalan
Aktif — jalan otomatis pada setiap pemicu
Jeda — sementara dihentikan; bisa diaktifkan lagi

10.6 Aksi Panggil webhook (integrasi eksternal)

Karibin POST body JSON kecil ke URL yang Anda tentukan saat pemicu terjadi. Bagus untuk integrasi ke n8n, Zapier, Make.com, atau sistem internal Anda lewat HTTP.

Konfigurasi:

URL — wajib https:// (atau http://localhost untuk testing lokal). Maks 2048 karakter.
Shared secret (opsional, min 8 karakter) — kalau diisi, Karibin tambah header X-Karibin-Signature: sha256=[hex] hasil HMAC body. Receiver bisa verifikasi pakai secret yang sama untuk menolak request palsu.

Payload yang dikirim (semua trigger):

{
  "event": "new-contact" | "inbound-message" | "tag-added",
  "workspaceId": "ws_...",
  "timestamp": "2026-05-31T10:30:00.000Z",
  "data": { ... }
}

data berbeda tergantung trigger:

Event	Isi `data`
`new-contact`	`contact: { id, name, phone, email }`
`inbound-message`	`contact: {...}`, `conversationId`, `message: { id, body, sentAt, mediaType }`
`tag-added`	`contact: {...}`, `tag: { id, name, color }`

Body pesan dipotong di 500 karakter pertama supaya request tidak ballooning.

Header:

Content-Type: application/json
User-Agent: Karibin-Webhook/1
X-Karibin-Signature: sha256=[hex] (hanya jika secret di-set)

Cara verifikasi signature (Node.js contoh):

const expected = require("crypto")
  .createHmac("sha256", SHARED_SECRET)
  .update(rawBody)
  .digest("hex");
const provided = req.headers["x-karibin-signature"].replace("sha256=", "");
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided))) {
  return res.status(401).send("invalid signature");
}

Behavior:

Timeout 5 detik — receiver yang lambat dianggap fail. Jangan kerjakan tugas berat sinkron di handler webhook; balas 200 dulu, lalu queue di sisi receiver.
Tidak ada retry — kalau receiver balas non-2xx atau timeout, workflow run di-log FAILED (error text + status code di Riwayat jalan). Anda perlu refire trigger manual kalau mau ulang.
Webhook fired dari workflow lain juga di-call — panggil webhook tidak punya loop guard. Hati-hati kalau receiver Anda balik posting ke Karibin (mis. balik bikin kontak/tag) dan ada workflow yang nyala dari aksi itu.

10.7 Hapus otomasi

Di halaman detail klik “Hapus” (atau ikon tong sampah di tabel daftar) → konfirmasi → otomasi terhapus permanen beserta semua riwayat jalannya.