Melakukan Panggilan: Tunggal dan Batch

Halaman ini menjelaskan praktik pengiriman lengkap — dari satu panggilan uji hingga tugas batch — beserta semantik pemrosesan batch dan retry atas kegagalan.

Prasyarat

• Sudah memiliki template yang lolos review (lihat Menggunakan Konsol Voice)
• Pada tahap pengujian, disarankan menambahkan nomor ke whitelist pengujian (lihat Menggunakan Konsol Voice)

Memilih Metode Pengiriman

Kedua metode melalui rantai panggilan yang sama dengan semantik hasil yang identik.

Nomor dan Negara

• Nomor penerima memakai format E.164 (kode negara + nomor lokal, tanpa + pada permintaan), mis. 8613800138000; tabel kode lihat Kode Negara/Wilayah
• Negara panggilan ditentukan oleh template: tidak perlu mengirim kode negara saat mengirim; kode panggilan nomor penerima harus cocok dengan negara template, jika tidak mengembalikan 120003
• Satu permintaan API maksimum 1000 penerima; tugas Console mendukung impor batch yang lebih besar

Template dan Variabel

• Variabel template memakai placeholder ordinal {1}, {2} dengan nilai dikirim per nomor: {"to": "8613800138000", "variables": ["Budi", "A12345"]}
• Urutan variabel harus sesuai placeholder; abaikan variables untuk template tanpa variabel
• Jumlah pemutaran dapat ditimpa per pengiriman di atas nilai default template

Pengiriman Terjadwal

• Setel scheduling.type = SCHEDULED dan sertakan startTime/endTime (ISO 8601 dengan zona waktu, mis. 2026-11-20T09:00:00+08:00)
• Batasan jendela: titik awal harus setelah waktu saat ini, titik akhir setelah titik awal, dan jendela maksimum 8 hari; platform menyelesaikan panggilan keluar di dalam jendela
• Hanya tugas terjadwal yang boleh menyertakan field waktu

Strategi Panggil Ulang

Panggilan yang tidak tersambung dapat dipanggil ulang otomatis (objek retry):

Panggil ulang meningkatkan peluang tersambung, tetapi ditagih sesuai panggilan aktual; untuk skenario yang sensitif terhadap waktu, disarankan menonaktifkan atau mengurangi panggil ulang.

SMS Hang-up

Setelah panggilan berakhir, sebuah SMS dapat dikirim susulan ke penerima (objek hangupSms, aktif bila ada):

• templateId: template SMS hang-up (independen dari template suara, harus dibuat dan direview terlebih dahulu)
• sendType: ON_CONNECTED kirim setelah tersambung (default) / ALL semua / ON_UNANSWERED tidak tersambung / BY_DURATION berdasarkan durasi tersambung
• durationLimitSeconds: ambang durasi (detik) saat BY_DURATION

Semantik Pemrosesan Batch

• Sebelum diterima: platform memvalidasi parameter seluruh batch (format nomor, batas jumlah, aturan lintas field) — kegagalan validasi menolak seluruh batch (HTTP 400 atau 010003)
• Setelah diterima: panggilan keluar per nomor; kegagalan satu panggilan tidak memengaruhi nomor lain dalam batch
• API yang berhasil diterima mengembalikan callId (identifier tugas) dan acceptedCount (jumlah nomor yang diterima)

Nomor Tidak Valid dan Duplikat

• Nomor dengan format ilegal disaring sebelum diterima; pastikan format E.164 dan kode panggilan benar
• Nomor duplikat dalam batch masing-masing dipanggil; disarankan menghapus duplikat sebelum mengirim

Idempotensi dan Retry

• bulkId hanya untuk asosiasi rekonsiliasi (digema apa adanya dalam respons) dan bukan kunci idempoten: pengiriman ulang memicu panggilan dan penagihan ulang
• Setelah API timeout jangan langsung mengirim ulang: periksa terlebih dahulu dengan callId yang dikembalikan (atau cari bulkId di catatan) apakah tugas sudah diterima; retry hanya setelah dipastikan belum diterima
• Saran idempotensi sisi klien: buat bulkId unik untuk setiap peristiwa bisnis, lalu hapus duplikat berdasarkan callId + mobile setelah hasil diterima (Push CDR atau API Kueri)

FAQ

Diterima sukses (000000) tetapi penerima tidak mendapat panggilan?

Mungkin sedang menunggu panggil ulang setelah tidak tersambung, penerima mati/sibuk, atau gangguan jalur. Status per panggilan lihat Catatan Pengiriman; arti kode terminasi lihat Kode Error.

Kapan kegagalan validasi field mengembalikan HTTP 400 dan kapan 010003?

Masalah format/nilai satu field (mis. nomor bukan E.164, messages lebih dari 1 entri) mengembalikan body error standar HTTP 400; masalah lintas field/aturan bisnis (mis. jendela terjadwal tidak valid, field SMS hang-up tidak lengkap) mengembalikan HTTP 200 + code=010003.

Sumber Terkait

• Parameter lengkap API Pengiriman
• Melihat Hasil: Catatan Pengiriman dan Push CDR
• FAQ