MasukMulai uji coba gratis
easyCoexistence API resmi

Cara mengimpor riwayat chat dan kontak aplikasi WhatsApp Business melalui API

Nomor aplikasi WhatsApp Business yang terhubung melalui Coexistence dapat mengirim kontak yang ada dan chat satu-ke-satu hingga 180 hari ke API sekali saja, dalam 24 jam setelah onboarding. Kontak tiba sebagai webhook smb_app_state_sync dan chat sebagai webhook history, dalam potongan yang diurutkan menurut metadata.chunk_order; metadata.progress bernilai 100 menandakan impor selesai. Bisnis memilih di aplikasi apakah chat akan dibagikan.

easyCoexistence menghubungkan nomor aplikasi WhatsApp Business pelanggan Anda melalui Coexistence dan meminta kontak serta riwayat chat mereka dari Meta begitu webhook Anda siap, sehingga riwayat langsung dikirim ke endpoint Anda tanpa disimpan di tengah jalan, dan memantau setiap nomor 24/7.

180 days

Seberapa jauh webhook riwayat menjangkau, dihitung dari saat bisnis di-onboard ke Cloud API.

24 hours

Waktu setelah onboarding saat kontak dan riwayat pesan bisnis harus disinkronkan.

2593109

Kode kesalahan pada webhook riwayat ketika bisnis telah mematikan berbagi riwayat di aplikasi WhatsApp Business.

Once

Seberapa sering setiap sinkronisasi dapat berjalan; untuk mengulanginya, pelanggan perlu offboard dan menyelesaikan Embedded Signup lagi.

100

Nilai progress yang menandakan sinkronisasi riwayat telah selesai.

Bagaimana impor dimulai?

Dengan tujuan webhook pada nomor. Ketika nomor terhubung dengan webhook_url sudah diatur pada sesi koneksi, atau ketika Anda mengaturnya dengan PUT /connections/{id}/webhook dalam 24 jam setelah terhubung, easyCoexistence meminta data dari Meta sekali: POST /{phone_number_id}/smb_app_data dengan sync_type smb_app_state_sync untuk kontak, lalu history untuk chat, urutan yang didokumentasikan Meta. Log event nomor mencatat history_sync_requested dengan nilai request_id dari Meta untuk dukungan, atau history_sync_failed beserta alasannya.

1Connect sessionwebhook_url and webhook_verify_token set before the link goes out
2Customer connectsScans the QR code and chooses whether to share chats
3Contactssmb_app_state_sync, a change per contact
4Chatshistory chunks, the newest phase first
5Completemetadata.progress reaches 100

Apa yang dibawa webhook kontak?

Field smb_app_state_sync, dengan array state_sync di dalam value. Setiap item memiliki type contact; objek contact dengan full_name, first_name dan phone_number; action berupa add atau remove; serta metadata.timestamp. Nama dihilangkan pada remove. Meta terus mengirim webhook ini setelah impor setiap kali bisnis menambah, mengubah atau menghapus kontak di aplikasi WhatsApp Business, sehingga buku alamat Anda tetap sejalan dengan ponsel.

Apa yang dibawa webhook riwayat?

Field history, dengan array history di dalam value. Setiap item berisi metadata, dengan phase, chunk_order dan progress, serta threads, satu per pelanggan: id thread adalah nomor pelanggan, dan messages berisi percakapan satu-ke-satu itu, masuk dan keluar, dengan from yang menunjukkan pihak mana yang mengirim setiap pesan. Sebuah pesan memuat id, timestamp, type, isinya di bawah nama type tersebut, dan history_context.status, misalnya READ atau DELIVERED. Chat grup tidak disertakan.

A history webhook, as Meta sends it
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "history",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": { "display_phone_number": "<BUSINESS_NUMBER>", "phone_number_id": "<PHONE_NUMBER_ID>" },
            "history": [
              {
                "metadata": { "phase": 1, "chunk_order": 3, "progress": 42 },
                "threads": [
                  {
                    "id": "<CUSTOMER_NUMBER>",
                    "messages": [
                      {
                        "from": "<CUSTOMER_NUMBER>",
                        "id": "wamid.<ID>",
                        "timestamp": "1790726400",
                        "type": "text",
                        "text": { "body": "<MESSAGE_TEXT>" },
                        "history_context": { "status": "READ" }
                      }
                    ]
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

Bagaimana pesan media diimpor?

Sebagai placeholder terlebih dahulu. Pesan media datang dengan type media_placeholder, tanpa content dan tanpa ID media. Meta kemudian mengirim webhook riwayat terpisah yang membawa ID media, tetapi hanya untuk media yang dikirim dalam 14 hari setelah onboarding; ambil file tersebut dari Meta dengan token pelanggan. Media yang lebih lama tetap sebagai placeholder, jadi tampilkan sebagai lampiran yang tidak tersedia alih-alih meninggalkan celah dalam thread.

Dalam urutan apa potongan tiba, dan kapan impor selesai?

Belum tentu berurutan. Meta membagi chat menjadi tiga fase, dari yang terbaru: fase 0 adalah hari sebelum onboarding, fase 1 mencapai hari ke-90 dan fase 2 hingga hari ke-180. Potongan bisa tiba tidak berurutan, jadi urutkan menurut metadata.chunk_order. metadata.progress adalah persentase dari seluruh sinkronisasi, dan 100 berarti selesai; nomor fase saja tidak menandakan bahwa sebuah fase sudah rampung.

Bagaimana jika bisnis menolak membagikan chat?

Selama koneksi, aplikasi WhatsApp Business menanyakan kepada bisnis apakah akan membagikan riwayat chatnya. Penolakan datang sebagai webhook riwayat tanpa messages dan dengan array errors yang kodenya 2593109, berjudul History sync is turned off by the business from the WhatsApp Business App. Kontak tetap tiba, dan pesan langsung mengalir seperti biasa sejak nomor terhubung.

Bisakah impor dijalankan ulang?

Tidak pada koneksi yang sama. Meta mengizinkan setiap sinkronisasi sekali, dalam 24 jam setelah onboarding, dan tidak dapat diputar ulang. Menjalankannya lagi berarti pelanggan memutus nomor dan menghubungkannya kembali, yang dihitung sebagai onboarding baru: dengan tujuan Anda yang masih tersimpan, easyCoexistence meminta impor lagi, sehingga lakukan deduplikasi berdasarkan id setiap pesan. Termasuk nomor yang kembali setelah aturan 14 hari.

Apa yang harus siap sebelum Anda mengirim tautan koneksi?

Endpoint Anda, aktif dan merespons. Meta memeriksa URL dengan handshake GET-nya ketika tujuan diterapkan, dan impor diminta sekali, tepat setelahnya. Jika handshake gagal, nomor tetap terhubung tetapi tanpa tujuan, last_error pada sesi menjelaskan alasannya, dan tidak ada yang diimpor kecuali Anda memperbaiki endpoint dan mengaturnya dengan PUT /connections/{id}/webhook dalam 24 jam. Nomor tanpa webhook_url tidak mendapat impor sama sekali, karena konten yang dikirim ke easyCoexistence dibuang.

Cara mengonfigurasi

  1. Prepare the endpointDeploy an HTTPS URL with a random secret in its path that answers Meta's GET handshake and accepts bodies up to 3 MB.
  2. Create the connect sessionPOST /connect-sessions with webhook_url and webhook_verify_token, then send the customer the url it returns.
  3. Store contacts and chatsUpsert contacts from smb_app_state_sync, and insert history messages keyed on their id, sorted by chunk_order.
  4. Wait for progress 100Treat the import as finished when metadata.progress reaches 100, or as declined when a history webhook carries error 2593109.

Kesalahan umum

  • Menolak potongan riwayat yang besar. Payload Meta dapat mencapai 3 MB, sedangkan Express hanya mengurai JSON hingga 100 KB secara default, jadi naikkan batasnya atau potongan akan gagal dan Meta terus mencoba ulang.
  • Memproses potongan menurut urutan kedatangan. Potongan bisa tiba tidak berurutan, jadi urutkan menurut metadata.chunk_order dan tunggu progress 100 sebelum menyatakan impor selesai.
  • Memasukkan riwayat tanpa deduplikasi. Pesan langsung dapat tumpang tindih dengan impor dan penyambungan ulang menjalankannya lagi, jadi kunci setiap pesan berdasarkan id-nya.
  • Mengirim tautan koneksi sebelum endpoint merespons handshake Meta. Tujuan kemudian tidak diterapkan, dan kecuali Anda mengaturnya dalam 24 jam, riwayat nomor tidak pernah diimpor.
Melakukan ini dengan EasyCoexistence

US$ 9 hingga US$ 0.75 per koneksi per bulan, turun seiring Anda menambah koneksi, dengan 3 hari pertama gratis.

Pertanyaan yang sering diajukan

Seberapa jauh impor riwayat chat WhatsApp berjalan?

Hingga 180 hari sebelum nomor di-onboard ke Cloud API, mencakup chat satu-ke-satu dalam kedua arah.

Apakah chat grup ikut diimpor?

Tidak. Meta tidak menyertakan pesan yang merupakan bagian dari chat grup.

Apakah chat WhatsApp lama pelanggan akan sampai ke webhook saya?

Ya, hingga 180 hari chat satu-ke-satu, dikirim sekali dalam 24 jam setelah onboarding, jika bisnis memilih di aplikasi untuk membagikannya.

Apakah easyCoexistence menyimpan salinan chat yang diimpor?

Tidak. Meta mengirim riwayat langsung ke webhook_url Anda, seperti pesan langsung, dan tidak ada yang disimpan di tengah jalan.

Lanjut membaca

Hubungkan saluran pertama Anda dalam dua menit.

Tanpa menunggu peninjauan platform. Hubungkan WhatsApp, Instagram, TikTok, atau saluran lainnya, lalu minta AI Anda untuk memposting, membalas, atau membuat laporan, dan lihat hasilnya langsung.

  • Gratis 3 hari
  • Batalkan kapan saja
  • Hanya API resmi
  • Dipantau 24/7

Diverifikasi pada