Log masukMulakan percubaan percuma
easyCoexistence API rasmi

Cara mengimport sejarah sembang dan kenalan aplikasi WhatsApp Business melalui API

Nombor aplikasi WhatsApp Business yang disambungkan melalui Coexistence boleh menghantar kenalan sedia ada dan sembang satu lawan satu sehingga 180 hari ke API sekali sahaja, dalam masa 24 jam selepas pendaftaran. Kenalan tiba sebagai webhook smb_app_state_sync dan sembang sebagai webhook history, dalam bahagian yang disusun mengikut metadata.chunk_order; metadata.progress pada 100 menandakan import selesai. Perniagaan memilih dalam aplikasi sama ada untuk berkongsi sembang.

easyCoexistence menyambungkan nombor aplikasi WhatsApp Business pelanggan anda melalui Coexistence dan meminta kenalan serta sejarah sembang mereka daripada Meta sebaik webhook anda sudah sedia, supaya sejarah itu terus ke endpoint anda tanpa sebarang penyimpanan di pertengahan jalan, dan setiap nombor dipantau 24/7.

180 days

Sejauh mana webhook sejarah merangkumi, dikira dari masa perniagaan didaftarkan pada Cloud API.

24 hours

Masa selepas pendaftaran ketika kenalan dan sejarah mesej perniagaan mesti disegerakkan.

2593109

Kod ralat pada webhook sejarah apabila perniagaan telah mematikan perkongsian sejarah dalam aplikasi WhatsApp Business.

Once

Sekerap mana setiap penyegerakan boleh berjalan; mengulanginya memerlukan pelanggan memutuskan sambungan dan melengkapkan Embedded Signup semula.

100

Nilai kemajuan yang menandakan penyegerakan sejarah selesai.

Bagaimana import bermula?

Dengan destinasi webhook pada nombor. Apabila ia disambungkan dengan webhook_url sudah ditetapkan pada sesi sambungan, atau apabila anda menetapkannya dengan PUT /connections/{id}/webhook dalam masa 24 jam selepas disambungkan, easyCoexistence meminta data daripada Meta sekali sahaja: POST /{phone_number_id}/smb_app_data dengan sync_type smb_app_state_sync untuk kenalan, kemudian history untuk sembang, susunan yang didokumenkan oleh Meta. Log peristiwa nombor merekodkan history_sync_requested dengan nilai request_id Meta untuk sokongan, atau history_sync_failed dengan sebabnya.

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 oleh webhook kenalan?

Medan smb_app_state_sync, dengan tatasusunan state_sync dalam value. Setiap item mempunyai type contact; objek kenalan dengan full_name, first_name dan phone_number; tindakan add atau remove; dan metadata.timestamp. Nama ditinggalkan pada remove. Meta terus menghantar webhook ini selepas import setiap kali perniagaan menambah, mengedit atau membuang kenalan dalam aplikasi WhatsApp Business, supaya buku alamat anda sentiasa selari dengan telefon.

Apa yang dibawa oleh webhook sejarah?

Medan history, dengan tatasusunan history dalam value. Setiap item mempunyai metadata, dengan phase, chunk_order dan progress, dan threads, satu untuk setiap pelanggan: id urutan sembang ialah nombor pelanggan, dan messages menyenaraikan sembang satu lawan satu itu, masuk dan keluar, dengan from menunjukkan pihak yang menghantar setiap mesej. Setiap mesej membawa id, timestamp, type, kandungannya di bawah nama jenis tersebut, dan history_context.status, seperti READ atau DELIVERED. Sembang kumpulan 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 mesej media diimport?

Sebagai pemegang tempat dahulu. Mesej media datang dengan type media_placeholder, tanpa kandungan dan tanpa ID media. Meta kemudian menghantar webhook sejarah berasingan yang membawa ID media, tetapi hanya untuk media yang dihantar dalam masa 14 hari selepas pendaftaran; ambil fail tersebut daripada Meta dengan token pelanggan. Media yang lebih lama kekal sebagai pemegang tempat, jadi paparkan sebagai lampiran yang tidak tersedia dan bukannya meninggalkan ruang kosong dalam urutan sembang.

Dalam susunan apa bahagian tiba, dan bila import selesai?

Tidak semestinya mengikut susunan. Meta membahagikan sembang kepada tiga fasa, yang terbaharu dahulu: fasa 0 ialah hari sebelum pendaftaran, fasa 1 kembali ke hari ke-90 dan fasa 2 ke hari ke-180. Bahagian boleh tiba tidak mengikut urutan, jadi susun mengikut metadata.chunk_order. metadata.progress ialah peratusan keseluruhan penyegerakan, dan 100 bermakna ia selesai; nombor fasa sahaja tidak memberitahu anda bahawa sesuatu fasa telah tamat.

Bagaimana jika perniagaan menolak untuk berkongsi sembang?

Semasa sambungan, aplikasi WhatsApp Business bertanya kepada perniagaan sama ada hendak berkongsi sejarah sembangnya. Penolakan tiba sebagai webhook sejarah tanpa mesej dan dengan tatasusunan errors yang kodnya ialah 2593109, bertajuk History sync is turned off by the business from the WhatsApp Business App. Kenalan masih tiba, dan mesej langsung mengalir seperti biasa sejak saat nombor disambungkan.

Bolehkah import dijalankan semula?

Tidak pada sambungan yang sama. Meta membenarkan setiap penyegerakan sekali sahaja, dalam masa 24 jam selepas pendaftaran, dan ia tidak boleh diulang semula. Untuk menjalankannya semula, pelanggan perlu memutuskan sambungan nombor dan menyambungkannya semula, yang dikira sebagai pendaftaran baharu: dengan destinasi anda masih tersimpan, easyCoexistence meminta import sekali lagi, jadi buang mesej pendua mengikut id setiap mesej. Ini termasuk nombor yang kembali selepas peraturan 14 hari.

Apa yang perlu siap sebelum anda menghantar pautan sambungan?

Endpoint anda, aktif dan menjawab. Meta menyemak URL dengan jabat tangan GET semasa destinasi digunakan, dan import diminta sekali sahaja, sejurus selepas itu. Jika jabat tangan gagal, nombor masih disambungkan tetapi tanpa destinasi, last_error dalam sesi menerangkan sebabnya, dan tiada apa yang diimport melainkan anda membetulkan endpoint dan menetapkannya dengan PUT /connections/{id}/webhook dalam masa 24 jam. Nombor tanpa webhook_url tidak mendapat import langsung, kerana kandungan yang dihantar ke easyCoexistence akan digugurkan.

Cara menetapkannya

  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.

Kesilapan biasa

  • Menolak bahagian sejarah yang besar. Payload Meta boleh mencecah 3 MB, sedangkan Express hanya menghurai JSON sehingga 100 KB secara lalai, jadi naikkan had atau bahagian akan gagal dan Meta terus mencuba semula.
  • Memproses bahagian mengikut susunan ketibaan. Ia boleh tiba tidak mengikut urutan, jadi susun mengikut metadata.chunk_order dan tunggu progress 100 sebelum menganggap import selesai.
  • Memasukkan sejarah tanpa buang pendua. Mesej langsung boleh bertindih dengan import dan penyambungan semula menjalankannya sekali lagi, jadi kunci setiap mesej mengikut id-nya.
  • Menghantar pautan sambungan sebelum endpoint menjawab jabat tangan Meta. Destinasi itu kemudian tidak digunakan, dan melainkan anda menetapkannya dalam masa 24 jam, sejarah nombor itu tidak pernah diimport.
Menggunakan EasyCoexistence untuk ini

Daripada US$ 9 turun kepada US$ 0.75 bagi setiap sambungan sebulan, berkurangan apabila anda menambah sambungan, dengan 3 hari pertama percuma.

Soalan lazim

Sejauh mana import sejarah sembang WhatsApp pergi ke belakang?

Sehingga 180 hari sebelum nombor didaftarkan pada Cloud API, meliputi sembang satu lawan satu dalam kedua-dua arah.

Adakah sembang kumpulan diimport?

Tidak. Meta tidak menyertakan mesej yang merupakan sebahagian daripada sembang kumpulan.

Adakah sembang lama pelanggan akan sampai ke webhook saya?

Ya, sehingga 180 hari sembang satu lawan satu, dihantar sekali dalam masa 24 jam selepas pendaftaran, jika perniagaan memilih dalam aplikasi untuk berkongsinya.

Adakah easyCoexistence menyimpan salinan sembang yang diimport?

Tidak. Meta menghantar sejarah terus ke webhook_url anda, sama seperti mesej langsung, dan tiada apa yang disimpan di perantaraan.

Teruskan membaca

Sambungkan saluran pertama anda dalam masa dua minit.

Tidak perlu menunggu semakan platform. Sambungkan WhatsApp, Instagram, TikTok atau saluran lain, kemudian minta AI anda menyiarkan, membalas atau melaporkan, dan lihat ia bekerja.

  • 3 hari percuma
  • Batal bila-bila masa
  • API rasmi sahaja
  • Dipantau 24/7

Disahkan pada