Send

7 min read

Endpoint

POST https://api.kirisan.com/v1/send
Authorization: Bearer YOUR_ACCOUNT_TOKEN
Content-Type: application/json

Mengirim ke satu penerima per permintaan. Untuk batch besar, gunakan Send → Campaign di dashboard atau panggil endpoint ini sekali per penerima dari aplikasi Anda.

Body permintaan

Field	Wajib	Deskripsi
`keys`	Ya	Token channel — `whatsapp`, `telegram`, `waba`, `email`
`content`	Ya	Pesan per channel — ID template atau pesan inline
`target`	Ya	Alamat penerima per channel + `variables` opsional
`context`	Tidak	Penjadwalan dan perilaku pengiriman

`keys`

{
  "keys": {
    "whatsapp": {
      "token": "DEVICE_TOKEN",
      "fallback": false,
      "fallback_sequence": 0
    },
    "email": {
      "token": "SENDER_TOKEN",
      "fallback": true,
      "fallback_sequence": 1
    }
  }
}

Sertakan key untuk setiap channel yang akan Anda kirimi. Lihat Authentication untuk tempat menyalin token.

`content`

Setiap entri channel memakai salah satu template tersimpan atau pesan inline — bukan keduanya.

Referensi template (disarankan — sama seperti Send → Send):

{
  "content": {
    "whatsapp": { "template": 42 },
    "email": { "template": 17 }
  }
}

Pesan inline (WhatsApp, Telegram, WABA saja — email harus memakai template):

{
  "content": {
    "whatsapp": {
      "message": {
        "type": "text",
        "message": "Hello {{name}}, your order is ready."
      }
    }
  }
}

`message.type`	Channel	Catatan
`text`	WhatsApp, Telegram, WABA	Teks biasa (WABA: aturan sesi berlaku). Tombol Telegram dipasang di sini lewat `richContext.buttons`.
`image`, `video`, `document`	WhatsApp, Telegram, WABA	Memerlukan `richContext.fileUrl` atau `richContext.fileId`. Telegram boleh sekaligus menyertakan tombol.
`location`	WhatsApp, Telegram	Memerlukan `richContext.location` — teks `message` diabaikan
`interactive`	WABA	Tombol balas sesi atau daftar — lihat Tombol. Bukan untuk Telegram (pakai `text` + buttons).

message.richContext (opsional):

Field	Tujuan
`fileUrl`	URL HTTPS publik ke lampiran
`fileId`	ID file yang diunggah ke Resources → Files
`fileName`	Nama tampilan — Kirisan dapat menambahkan ekstensi yang terdeteksi
`footer`	Teks footer (jika didukung)
`location`	`{ "lat", "lng", "name", "address" }` untuk pesan lokasi
`buttons`	Baris tombol — bentuknya tergantung channel (lihat Tombol)
`listMessage`	Objek daftar WABA (label `button` + `sections`)

Tombol

Kirisan tidak menganggap “tombol” sebagai satu tipe universal. Channel dan jalur pesan menentukan jenis yang bisa dikirim.

Telegram — keyboard inline (`url` / `callback` / `copy`)

Pakai type: "text" (atau media) dengan richContext.buttons sebagai array baris. Setiap tombol butuh text dan type:

`type`	Field tambahan	Perilaku
`url`	`url`	Membuka tautan (`http` / `https` / `tg://`)
`callback`	`callbackData`	Mengirim callback ke bot Anda (maks. 64 byte)
`copy`	`copyText`	Menyalin teks ke clipboard pengguna

{
  "type": "text",
  "message": "Choose an option:",
  "richContext": {
    "buttons": [
      [
        { "text": "Open site", "type": "url", "url": "https://example.com" },
        { "text": "Confirm", "type": "callback", "callbackData": "confirm" }
      ],
      [
        { "text": "Copy code", "type": "copy", "copyText": "PROMO-10" }
      ]
    ]
  }
}

Tiga jenis yang sama tersedia saat Anda membuat keyboard di Channel → Telegram → Templates.

WABA — interaktif sesi (tombol balas atau daftar)

Pesan WABA bebas / free-form (termasuk interaktif) tidak membutuhkan template Meta, tetapi hanya jalan di dalam jendela customer care / sesi Meta — biasanya setelah pengguna mengirim pesan ke Anda (aturan sama dengan teks dan media bebas). Di luar jendela itu, Meta menolak kiriman free-form; pakai template yang sudah disetujui.

Saat sesi terbuka, type: "interactive" menerima:

Tombol balas — richContext.buttons dengan id + text saja (maks. 3 total; tombol reply Meta). Tidak perlu template.
Daftar — richContext.listMessage dengan label button dan sections / rows. Tidak perlu template.

Tidak tersedia di jalur free-form ini: tombol gaya template quick reply, URL, atau call.

{
  "type": "interactive",
  "message": "Need help with order {{order_id}}?",
  "richContext": {
    "footer": "Reply anytime",
    "buttons": [[{ "id": "yes", "text": "Yes" }, { "id": "no", "text": "No" }]]
  }
}

WABA — template Meta (quick reply / URL / call)

Pakai template bila Anda perlu mengirim di luar jendela sesi, atau bila Anda butuh tombol quick reply / URL / call.

Ketiga jenis tombol itu ada di template yang disetujui Meta, bukan di JSON interactive inline. Buat di Channel → WABA → Templates, lalu kirim dengan content.waba.template: <id>.

Tombol template	Tipe Meta	Catatan
Quick reply	`quick_reply`	Pengguna mengetuk → Anda menerima payload balasan
URL	`url`	Membuka tautan; boleh satu `{{variable}}`
Call	`phone_number`	Memulai panggilan telepon

Jalur	Butuh template disetujui?	Jendela sesi?	Jenis tombol
`interactive` free-form	Tidak	Wajib (jendela terbuka)	Balas (`id`/`text`) atau daftar
`content.waba.template`	Ya	Tidak wajib	Quick reply / URL / call (sesuai template)

WhatsApp (device Fonnte) tidak mendukung tombol interaktif outbound di /v1/send.

`target`

{
  "target": {
    "whatsapp": "6281234567890",
    "email": "customer@example.com",
    "telegram": "123456789",
    "waba": "6281234567890",
    "variables": {
      "name": "Alex",
      "order_id": "A-1001"
    }
  }
}

Field	Format
`whatsapp`, `waba`	Nomor telepon dengan kode negara (digit, tanpa `+` juga boleh)
`telegram`	Chat ID
`email`	Alamat email valid
`variables`	Mengganti `{{placeholder}}` di template dan pesan inline sebelum send

Abaikan field channel yang tidak Anda kirimi. Setiap channel aktif di content memerlukan target yang cocok (kecuali difilter oleh context.behaviour.channel).

`context`

{
  "context": {
    "timing": {
      "schedule": 1735689600
    },
    "behaviour": {
      "channel": "all",
      "mode": "sync"
    }
  }
}

Field	Arti
`timing.schedule`	Timestamp Unix (detik) — antre untuk pengiriman di masa depan. Abaikan atau set `null` untuk kirim sekarang. Waktu lampau ditolak.
`behaviour.channel`	`"all"` (default) — kirim setiap channel yang punya key dan content. Atau salah satu dari `whatsapp`, `telegram`, `waba`, `email` untuk membatasi ke satu channel.
`behaviour.mode`	`"sync"` (default) — tunggu hasil channel lalu kembalikan di respons HTTP. `"async"` — antre segera (`pending` di log Kirisan); hasil muncul di Logs/History otomatis. Opsional: terima POST ke webhook `send_status` jika Anda mengonfigurasinya.

Saat dijadwalkan, respons menyertakan "scheduled": true dan setiap channel menampilkan "scheduled": true alih-alih mengirim segera. Penjadwalan memakai jalur terjadwal (bukan mode: async).

Contoh

Setiap contoh adalah permintaan POST /v1/send lengkap. Buka baris untuk cURL, Node.js, Python, PHP, Go, atau JSON mentah. Ganti token, ID, dan target dengan nilai Anda sendiri.

Fallback cascade

Ketika channel key memakai fallback: true, Kirisan mencoba tier secara berurutan:

Primary — semua key tanpa fallback (dikirim bersamaan).
Fallback 1 — key dengan fallback_sequence: 1 (paralel dalam tier).
Fallback 2 — key dengan fallback_sequence: 2, dan seterusnya.

Segera setelah channel apa pun dalam tier berhasil, tier berikutnya dilewati. Ini sama dengan Use as fallback dan Sequence di Send → Send. Lihat Send messages untuk panduan dashboard.

Channel yang gagal di tier sebelumnya tetap muncul di bawah "channels" dengan "reason". Channel fallback yang berhasil dapat menyertakan "fallback": true.

Respons

Send langsung (mode: sync atau dihilangkan):

{
  "status": true,
  "id": 98765,
  "request_id": 12345,
  "channels": {
    "whatsapp": {
      "status": true,
      "id": 98765,
      "processing_time": "142ms"
    }
  }
}

id adalah send.id (integer, sumber utama untuk pelacakan di Kirisan). request_id adalah send_log.id untuk permintaan /v1/send ini. id dihilangkan jika belum ada baris send (misalnya diblokir sebelum channel dipanggil).

Async (mode: async) — diterima ke antrean:

{
  "status": true,
  "queued": true,
  "request_id": 12345
}

Message id belum ada saat antre — hasil akhir tersimpan otomatis di log Kirisan (send / send_log). Jika Anda mengonfigurasi webhook send_status, payload yang sama juga di-POST ke URL Anda.

Kegagalan sebagian:

{
  "status": false,
  "channels": {
    "whatsapp": {
      "status": false,
      "reason": "Device disconnected",
      "processing_time": "89ms"
    },
    "email": {
      "status": true,
      "fallback": true,
      "processing_time": "891ms"
    }
  }
}

Terjadwal:

{
  "status": true,
  "scheduled": true,
  "channels": {
    "telegram": { "status": true, "scheduled": true }
  }
}

`status` tingkat atas	Arti
`true`	Minimal satu channel terkirim atau dijadwalkan, atau permintaan async berhasil diantrekan
`false`	Setiap channel yang dicoba gagal, atau validasi memblokir permintaan

Baca "reason" di root untuk error validasi. Baca "channels.<name>.reason" untuk kegagalan pengiriman. Lihat Errors.

Kirisan juga menyimpan request + response ke audit log untuk kegagalan validasi/auth (JSON tidak valid, token salah, content salah, dll.) — respons menyertakan request_id bila log berhasil ditulis, agar dukungan bisa menelusuri permintaan Anda.

Catatan channel

Channel	`message` inline	Template
WhatsApp	Ya — teks, media, lokasi (tanpa tombol interaktif)	Ya — harus disetujui dan aktif
Telegram	Ya — teks/media + keyboard inline (`url` / `callback` / `copy`)	Ya — jenis tombol yang sama di editor template
WABA	Ya — teks, media, tombol balas interaktif atau daftar (jendela sesi)	Ya — template Meta dengan quick reply / URL / call; kelola di Channel → WABA → Templates
Email	Tidak — hanya `content.email.template`	Ya — buat di Channel → Email → Templates

Template yang direferensikan via ID harus Approved dan Active. Daftar ID lewat Templates API (GET /v1/templates), salin dari Channel → channel → Templates, atau gunakan konten message inline.

Terkait

Authentication — token akun dan channel key
Templates API — daftar dan ambil template
Errors — kode HTTP dan alasan umum
Send status webhook — hasil async POST /v1/send
Send messages — bentuk permintaan yang sama dari UI
WhatsApp templates — buat template dan salin ID untuk send