Meta Conversions API

Meta Conversions API (CAPI)

Copy page

Fitur ini mengirim data konversi dari percakapan ke Meta Ads agar event dapat dipakai untuk attribution, optimasi kampanye, dan laporan.

Judul & Scope

Dukungan kanal

• whatsapp dan whatsapp-unofficial
• instagram, instagram-direct
• widget (terbatas pada flow khusus saat customer meminta CS)

Tombol CAPI

Di halaman akun, tombol CAPI muncul untuk semua akun non-widget. Jadi selain WhatsApp, akun Instagram juga bisa dikonfigurasi dari tombol yang sama.

Cara kerja (event-driven)

Code
  Agent set label CAPI di panel profil percakapan
        ↓
  Event dicatat di `CapiEventLog` (source: label_save) dan dikirim ke Meta jika valid

1. Agent memilih label/event dari Customer Profile → Label.
2. Saat label dipilih, event tersimpan ke log Meta CAPI (CapiEventLog) sebagai source: label_save.
3. Jika event valid dan konfigurasi benar, event langsung dikirim ke Meta dari action label.
4. Statusnya tercatat di log (pending/sent/failed) dan bisa di-retry dari halaman analytics.

Setup kanal akun

1. Buka menu Accounts.

2. Pilih akun WA/IG dan klik tombol CAPI.

3. Isi:

   Field	Keterangan
   Pixel ID / Dataset ID	ID dataset Meta CAPI milik advertiser
   Access Token	Token conversion access dari Meta Events Manager
   Enable CAPI	Toggle aktif/non-aktif per akun
   Facebook Page ID	Opsional; wajib saat sending WA business_messaging (ctwa click-based flow)
   Instagram Account ID	Dibaca otomatis dari akun/ID yang tersambung (dipakai untuk business messaging Instagram)

4. Klik Simpan.

Menetapkan label konversi

Setelah percakapan di-close/arsip, buka panel profil percakapan dan atur:

• Label: NONE / Lead / Purchase / event lain yang didukung.
• Purchase menampilkan input nilai & mata uang.
• Catatan tambahan opsional dapat diisi dan ikut terkirim sebagai detail tambahan.

Event yang tersedia (flow standard vs business messaging)

Pemilihan event bergantung pada flow data yang tersedia:

• Standard flow (umumnya chat organik): event dari daftar standard Meta.
• Business Messaging flow (mis. Instagram DM dan WhatsApp dengan ctwaClid): event dibatasi ke event type business messaging.

Contoh event yang umum muncul di UI:

• Lead
• Purchase
• CompleteRegistration
• InitiateCheckout
• AddToCart
• ViewContent

Pipeline pengiriman background (queue + worker)

• Pengiriman event dari WhatsappClosing yang berstatus pending dijalankan oleh queue capi-drain-queue (jalur arsip/snapshot).
• Worker retry dikonfigurasi:
  • attempts: 3
  • backoff: exponential dengan delay awal 5 detik
• Hanya event dengan sentStatus = "pending" yang dikirim.
• Hasil pengiriman memutakhirkan:
  • sent + sentAt saat sukses
  • failed + failureReason saat gagal
  • event tetap dicoba ulang sesuai retry worker

Status, retry, dan analitik

Data log disimpan di dua tempat untuk keperluan audit dan monitoring:

• WhatsappClosing (closing-level status pending | sent | failed | null)
• CapiEventLog (untuk event yang diset dari label profile, termasuk status dan alasan gagal)

Di halaman Meta Pixel (CAPI) kamu bisa filter:

• Status (pending, sent, failed)
• Event (Lead, Purchase, dst)
• Platform
• Waktu

Untuk event gagal, pakai tombol Retry di halaman analytics untuk kirim ulang.

Deduplication event

Mintol mengirim event_id pada payload ke Meta. Jika retry manual/manual reprocess terjadi, event yang sama tetap menggunakan konteks idempotensi (event_id pada record event terkait), sehingga Meta bisa melakukan dedup pada window yang berlaku di sisi Meta.

• Closing capture dari archive: event id biasanya berasal dari whatsappClosing.id.
• Send dari label langsung: event id dapat berbentuk label-<conversationId>-<timestamp>.
• CAPI test event memakai eventId test khusus agar aman untuk lingkungan testing.

Data yang dikirim ke Meta

Data	Sumber	Keterangan
event_name	Label event	Lead, Purchase, dan event lain sesuai flow
event_time	Waktu close/trigger	Unix timestamp
event_id	Internal ID event	Konsisten per record untuk dedupe
action_source	Engine runtime	system_generated, business_messaging, website (widget)
user_data.ph	Customer phone	SHA-256 (WA/IG/Widget sesuai konteks)
user_data.fn / user_data.ln	Nama customer	SHA-256
user_data.em	Email customer	SHA-256
user_data.external_id	External ID customer	SHA-256 (kondisional)
waba_id	WA Account setting	Untuk Business Messaging WA
ctwa_clid	Conversation	Untuk WA klik-to-WhatsApp
page_id	Account setting	Untuk Business Messaging WA
ig_account_id	Account setting / Instagram ID	Untuk Instagram Business Messaging
ig_sid	Conversation/customer	Untuk Instagram Business Messaging
custom_data.value	Label Purchase/input	Nilai transaksi (jika ada)
custom_data.currency	Label Purchase/input	Mata uang (default IDR bila tidak ada)

Semua field sensitif (ph, fn, em, external_id, dll) sudah diproses dengan hash sebelum dikirim.

Widget CAPI

Untuk alur widget:

• CAPI dikirim saat customer menekan request CS.
• Event default yang dikirim adalah Lead.
• Payload memakai action_source = website dan bisa menyertakan client_user_agent, fbc, fbp bila tersedia.

Troubleshooting

Event tidak muncul di Meta Events Manager

• Pastikan akun sudah connect ke CAPI dan toggle Enable CAPI ON.
• Pastikan token/Pixel ID valid dan belum kedaluwarsa.
• Periksa status di Meta Pixel (CAPI) apakah berhasil (sent) atau gagal (failed).

Label tidak terkirim / tidak ada event

• Kalau label adalah NONE, tidak ada event CAPI yang dikirim (ini setara skip).
• Untuk event yang gagal, cek dan jalankan Retry.

Error CAPI token/akses

• Pastikan token valid dan belum dicabut.
• Cek akun yang dipakai (harus sesuai capiEnabled, capiPixelId, capiAccessToken non-null).

WhatsApp Business Messaging gagal

• Cek Facebook Page ID sudah diisi jika flow business messaging dipakai.
• Verifikasi ctwaClid tersedia pada conversation bila flow tersebut memerlukan identitas attributed click-to-wa.

Event tidak didukung untuk platform

• Jika event tidak valid untuk flow, API akan menolak (mis. event business-messaging vs standard tidak cocok).

Catatan saat disconnect akun

Saat akun disconnected/deleted, konfigurasi CAPI terkait akun ikut terhapus bersama akun.

Riwayat yang sudah tercatat (close log / event log) tetap tersimpan sesuai retention dan kebijakan audit.