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).

Kenapa opt-in penting

Kontak yang belum opt-in tidak akan menerima broadcast segmen. Ini guardrail UU PDP (Perlindungan Data Pribadi): promosi massal hanya boleh ke orang yang sudah setuju menerimanya. Pesan transaksional satu-per-satu (/v1/messages/send) tidak terpengaruh aturan ini.

Kontak yang pernah menolak (opt-out) selalu dilewati, 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": true,
    "consent_acknowledged": true
  }'

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	true = langsung ditandai boleh menerima broadcast
consent_acknowledged	jika opt-in	Wajib true — pernyataan bahwa kontak memang 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": true }

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"