Mengi WhatsApp rim acara konversi di AWS Pesan Soal Pengguna Akhir

Jika Anda menjalankan kampanye “Iklan yang Klik WhatsApp ke”Meta, Anda dapat mengirim kembali peristiwa konversi (seperti pembelian, prospek, atau tampilan konten) Meta untuk atribusi dan pengoptimalan iklan. Kirim acara ini secara langsung melalui AWS Social Pesan Pengguna Akhir, tanpa memanggil Meta Graph API.

AWS End User Messaging Social menyediakan dua API untuk alur kerja ini:

• CreateWhatsAppDataset— Membuat (atau mengambil) dataset konversi untuk Akun WhatsApp Bisnis Anda (WABA). Dataset adalah wadah yang digunakan Meta untuk menerima dan mengaitkan peristiwa konversi Anda.

• SendWhatsAppConversionEvent— Mengirim satu atau lebih peristiwa Meta konversi ke API Konversi, di mana peristiwa tersebut dikaitkan dengan klik iklan yang memulai WhatsApp percakapan.

Cara kerja pelacakan peristiwa konversi

Alur kerja ujung ke ujung adalah:

1. Pelanggan mengklik iklan “Klik WhatsApp untuk” Anda Meta dan memulai percakapan dengan bisnis Anda.

2. Pesan masuk tiba di tujuan acara yang dikonfigurasi (topik Amazon SNS, Amazon EventBridge, atau Amazon Connect). Ini termasuk ctwa_clid (ID klik-ke- WhatsApp klik) yang mengidentifikasi klik iklan. Aplikasi Anda harus menangkap dan menyimpan nilai ini.

3. Ketika konversi terjadi (misalnya, pelanggan melakukan pembelian), aplikasi Anda memanggil SendWhatsAppConversionEvent dengan detail acara ctwa_clid dan.

4. AWS Social Pesan Pengguna Akhir meneruskan acara ke API Meta Konversi untuk atribusi.

ctwa_clidIni termasuk dalam referral objek payload webhook pesan masuk ketika pelanggan memulai percakapan dari iklan. Contoh berikut menunjukkan bagian yang relevan dari pesan webhook:

{
  "messages": [
    {
      "from": "12345678",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "referral": {
        "body": "This is a great product",
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a",
        "headline": "Our new product",
        "source_id": "1234567890",
        "source_type": "ad",
        "source_url": "https://fb.me/AAAAA"
      },
      "text": {
        "body": "Can I learn more about your business?"
      },
      "timestamp": "1678189586",
      "type": "text"
    }
  ]
}

Simpan ctwa_clid nilai dari referral objek. Berikan itu di user_data setiap acara konversi yang Anda kirim untuk percakapan ini. Untuk informasi selengkapnya tentang webhook rujukan, lihat komponen Webhooks dalam dokumentasi Meta pengembang.

Prasyarat

Sebelum mengirim peristiwa konversi, Anda memerlukan yang berikut:

• Akun WhatsApp Bisnis (WABA) yang ditautkan ke AWS akun Anda.

• Kampanye “Iklan yang Klik untuk WhatsApp” aktif aktifMeta.

• Aplikasi Anda harus menangkap ctwa_clid dari webhook pesan masuk saat pelanggan memulai percakapan dari klik iklan. Nilai ini dihasilkan oleh Meta dan tidak dapat dibuat.

penting

Jika Anda menautkan WhatsApp Akun Bisnis (WABA) sebelum 6 Agustus 2026, Anda harus mengulang alur pendaftaran untuk memberikan izin ke Social Pesan Pengguna AWS Akhir untuk mengirim acara konversi. Ikuti langkah 1 hingga 14 di bawah “Daftar melalui konsol” di Mend aftar WhatsApp, dan pilih WABA dan nomor telepon yang ada yang sudah terkait dengan AWS akun Anda. Anda kemudian dapat melewati langkah-langkah yang tersisa.

Langkah 1: Buat kumpulan data konversi

Sebelum mengirim peristiwa konversi, Anda harus membuat kumpulan data konversi untuk WABA Anda. Setiap WABA memiliki tepat satu dataset (ini diberlakukan olehMeta). Operasi ini tidak berpotensi: jika dataset sudah ada, ID dataset yang ada dikembalikan.

Contoh berikut membuat atau mengambil dataset untuk WABA. Ganti waba-id dengan ARN Akun WhatsApp Bisnis tertaut Anda (WABA) (misalnya,arn:aws:social-messaging:us-east-1:123456789012:waba/a1b2c3d4e5example).

aws socialmessaging create-whatsapp-dataset \
    --region us-east-1 \
    --id waba-id

Respons berisi ID dataset. Simpan nilai ini. Anda meneruskannya sebagai datasetId parameter setiap kali Anda mengirim peristiwa konversi.

{
    "datasetId": "123456789012345"
}

Langkah 2: Kirim acara konversi

Setelah membuat kumpulan data, Anda dapat mengirim peristiwa konversi ke Meta menggunakan SendWhatsAppConversionEvent API. Setiap panggilan mengirimkan satu atau lebih peristiwa ke API Kon Meta versi untuk atribusi.

Konten acara yang Anda kirim dalam event-data parameter mengikuti format server-event API Meta Konversi. AWS End User Messaging Social meneruskan konten ini keMeta. Untuk daftar lengkap bidang acara, lihat referensi parameter Meta server-event dalam dokumentasi Meta pengembang.

Mengirim acara konversi pembelian

Contoh berikut melaporkan Purchase konversi. Ganti nilai placeholder dengan milik Anda sendiri.

aws socialmessaging send-whatsapp-conversion-event \
    --region us-east-1 \
    --id waba-id \
    --dataset-id dataset-id \
    --event-data '{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": 1720000000,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            },
            "custom_data": {
                "currency": "USD",
                "value": 99.99
            }
        }
    ]
}'

Tanggapan berisi ID permintaan yang mengidentifikasi kiriman Anda:

{
    "requestId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}

Mengirim acara konversi prospek

Non-purchase jenis acara seperti LeadSubmitted tidak diperlukancustom_data.

aws socialmessaging send-whatsapp-conversion-event \
    --region us-east-1 \
    --id waba-id \
    --dataset-id dataset-id \
    --event-data '{
    "data": [
        {
            "event_name": "LeadSubmitted",
            "event_time": 1720000000,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            }
        }
    ]
}'

Kirim beberapa acara dalam satu permintaan

Ar data ray menerima beberapa peristiwa dalam satu panggilan. Metamemungkinkan hingga 1.000 acara per permintaan.

aws socialmessaging send-whatsapp-conversion-event \
    --region us-east-1 \
    --id waba-id \
    --dataset-id dataset-id \
    --event-data '{
    "data": [
        {
            "event_name": "ViewContent",
            "event_time": 1720000000,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            }
        },
        {
            "event_name": "Purchase",
            "event_time": 1720000500,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            },
            "custom_data": {
                "currency": "USD",
                "value": 149.00
            }
        }
    ]
}'

Referensi peristiwa konversi

event-dataParameter adalah objek JSON dengan data array yang berisi satu atau lebih objek peristiwa. Tabel berikut menjelaskan bidang yang paling umum digunakan untuk konversi “Iklan yang Klik WhatsApp ke”. Metaadalah sumber kebenaran untuk konten acara; lihat referensi parameter Meta server-event dalam dokumentasi Meta pengembang untuk spesifikasi lengkapnya.

Bidang acara wajib

Bidang	Tipe	Deskripsi
event_name	String	Jenis konversi. Case-sensitive. Nilai-nilai umum termasuk PurchaseLeadSubmitted,, danViewContent.
event_time	Bilangan	Waktu konversi terjadi, sebagai stempel waktu Unix dalam hitungan detik. Harus dalam 7 hari terakhir dan tidak di masa depan.
action_source	String	Harus berupa business_messaging.
messaging_channel	String	Saluran pesan. Gunakan whatsapp.
user_data	Objek	Informasi yang digunakan untuk mencocokkan acara dengan klik iklan. Lihat Bidang user_data yang diperlukan.

Bidang user_data yang diperlukan

Tabel berikut menjelaskan bidang yang diperlukan dalam user_data objek.

Bidang	Tipe	Deskripsi
whatsapp_business_account_id	String	ID Akun Meta WhatsApp Bisnis numerik Anda (dari Meta Pengaturan Bisnis).
ctwa_clid	String	ID klik-ke- WhatsApp klik dari webhook pesan masuk dari percakapan yang dimulai iklan. Metamemvalidasi nilai ini; itu tidak dapat dibuat.

penting

Jika Anda memasukkan informasi identitas pribadi (PII)user_data, seperti alamat email atau nomor telepon, Anda harus memberikan nilai sebagai SHA-256 hash. Metamenolak PII yang tidak di-hash. ctwa_clidNilai tidak di-hash.

Objek custom_data

Untuk Purchase acara, Anda harus menyertakan custom_data objek dengan bidang berikut:

Bidang	Tipe	Deskripsi
currency	String	Kode mata uang ISO 4217 (misalnya,USD).
value	Bilangan	Nilai moneter dari konversi.

Penanganan kesalahan

Karena AWS Social Pesan Pengguna Akhir meneruskan konten acara Anda keMeta, sebagian besar masalah konten acara muncul sebagai. InvalidParametersException Pesan kesalahan mencakup alasan yang dilaporkan olehMeta, misalnya: nama acara yang tidak dikenali, waktu acara di luar jendela yang diizinkan, mata uang yang hilang untuk pembelian, PII yang tidak di-hash, atau tidak valid. ctwa_clid

Kesalahan	Status HTTP	Arti
InvalidParametersException	400	Permintaan atau konten acara tidak valid. Pesan kesalahan menjelaskan masalah spesifik.
ResourceNotFoundException	404	WABA atau dataset yang ditentukan tidak dapat ditemukan.
AccessDeniedByMetaException	403	Metamenolak permintaan karena izin (misalnya, token Meta akses yang mendasarinya tidak memiliki izin yang diperlukan atau tidak valid).
ThrottledRequestException	429	Tingkat permintaan melebihi batas yang diizinkan. Coba lagi dengan mundur eksponensial.
DependencyException	502	Ketergantungan hilir (Meta) mengembalikan kesalahan. Dapat dicoba ulang.
InternalServiceException	500	Terjadi kesalahan internal. Dapat dicoba ulang.