Kontak & Opt-in

Broadcast ke segmen bekerja di atas daftar kontakmu. Halaman ini menjelaskan cara memasukkan kontak, memberinya tag, dan menandai izin menerima broadcast (opt-in).

Opt-in aktif secara bawaan, keluar otomatis

Kontak baru (impor CSV, impor grup, tambah manual) langsung opt-in. WAQ mengeluarkannya otomatis dari broadcast segmen kalau ada tanda ia menolak atau tak terjangkau — alasannya tersimpan di kontak (optOutReason):

Alasan	Kapan
stop_keyword	Penerima membalas STOP / BERHENTI / UNREG di chat pribadi
not_on_whatsapp	Hasil cek nomor: tidak terdaftar di WhatsApp
undelivered	≥3 pesan tak pernah sampai (>72 jam) di ≥2 hari berbeda, tanpa satu pun yang sampai dalam 60 hari (dicek tiap hari 03.30 WITA)
manual	Dimatikan pemilik akun

Kontak yang dikeluarkan bisa dimasukkan kembali kapan saja (dashboard atau PATCH). Pesan transaksional satu-per-satu (/v1/messages/send) tidak terpengaruh aturan ini.

Kontak yang opt-out selalu dilewati broadcast, bahkan ketika filter opt-in dimatikan.

Impor CSV

Format per baris: nama,nomor (baris header opsional). Nomor dinormalkan otomatis ke format 62….

curl -X POST https://waq.karyawah.id/v1/contacts/import-csv \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "csv": "Budi,081234567890\nAni,6285242411466",
    "tags": ["pelanggan-juli"],
    "broadcast_opt_in": false
  }'

Field	Wajib	Keterangan
csv	ya	Isi CSV mentah
tags	tidak	Dipasang ke semua kontak hasil impor ini — dipakai sebagai segmen broadcast
broadcast_opt_in	tidak	Bawaan true. Kirim false kalau kontak ini belum boleh menerima broadcast
consent_acknowledged	jika broadcast_opt_in: true dikirim eksplisit	true — pernyataan bahwa kontak sudah memberi persetujuan

Balasan memuat jumlah yang masuk, duplikat, dan nomor tak valid:

{ "imported": 2, "dedup": 0, "invalid": 0, "tags": ["pelanggan-juli"], "broadcast_opt_in": false }

Beri tag sejak impor

Tanpa tag, satu-satunya cara menyasar kontak itu adalah "semua kontak". Tag membuat kamu bisa mengirim ke kelompok tertentu saja, mis. pelanggan-juli.

Mencari & memfilter kontak

# cari nama / nomor / tag
curl -G https://waq.karyawah.id/v1/contacts \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'q=62812' \
  --data-urlencode 'optIn=true' \
  --data-urlencode 'source=csv' \
  --data-urlencode 'page=1'

Parameter	Nilai
q	Kata kunci — dicocokkan ke nama, nomor, dan tag
optIn	true / false
source	manual, csv, group (alias group_sync)
page	Halaman, 50 kontak per halaman

Menandai opt-in

Satu kontak:

curl -X PATCH https://waq.karyawah.id/v1/contacts/<contact_id> \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"broadcastOptIn": true}'

Banyak kontak sekaligus — pilih salah satu mode:

# mode 1: daftar id tertentu
curl -X POST https://waq.karyawah.id/v1/contacts/bulk-opt-in \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"opt_in": true, "consent_acknowledged": true, "ids": ["<id1>", "<id2>"]}'

# mode 2: semua kontak yang cocok filter
curl -X POST https://waq.karyawah.id/v1/contacts/bulk-opt-in \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"opt_in": true, "consent_acknowledged": true, "all": true, "source": "csv"}'

Balasan: { "updated": 1937, "opt_in": true }.

Untuk menandai opt-out massal, kirim "opt_in": false (tanpa perlu consent_acknowledged). Waktu penolakan dicatat, dan kontak itu tak akan pernah ikut broadcast lagi.

Validasi nomor

Nomor yang tidak terdaftar di WhatsApp membuang kuota harian dan memperbesar risiko pemblokiran nomor pengirim. Periksa dulu sebelum broadcast besar:

curl -X POST https://waq.karyawah.id/v1/contacts/validate \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"device_id": "<device_id>"}'

Pemeriksaan berjalan di latar belakang. Setelah selesai, hapus yang tidak valid:

curl -X DELETE https://waq.karyawah.id/v1/contacts/invalid \
  -H "Authorization: Bearer $TOKEN"