All Products
Search

This Product

    :Integrasikan layanan asisten AI dengan WeCom

    Document Center

    :Integrasikan layanan asisten AI dengan WeCom

    Last Updated:Jun 24, 2026

    Ikhtisar

    DataClaw mendukung dua mode penerimaan pesan WeCom:

    Fitur

    URL Callback Mode

    Mode koneksi persisten

    Metode koneksi

    WeCom secara aktif mendorong pesan ke callback URL

    Instans secara aktif terhubung ke server WeCom

    Titik akhir jaringan publik

    Diperlukan (dibuat secara otomatis)

    Tidak diperlukan

    Skenario yang berlaku

    Penerapan berbasis container, kontrol akses detail halus

    Integrasi cepat, tidak memerlukan titik akhir jaringan publik

    Kontrol akses IP

    Mendukung daftar putih IP

    Tidak berlaku

    Metode autentikasi

    API Key

    BotId + Secret

    • Mode callback URL: Server WeCom secara aktif mendorong pesan pengguna ke instans DataClaw melalui callback URL HTTPS. Mode ini cocok untuk skenario yang memerlukan kontrol detail atas IP inbound.

    • Mode koneksi persisten: Instans DataClaw secara aktif terhubung ke server WeCom untuk membentuk koneksi persisten. Mode ini cocok untuk skenario integrasi cepat yang tidak memerlukan titik akhir jaringan publik.

    Prasyarat

    • Sebuah instans DataClaw telah dibuat dan berada dalam status Running.

    • Anda memiliki izin untuk mengelola Konsol admin WeCom.

    Buat robot WeCom

    1. Buka Konsol admin WeCom. Di panel navigasi kiri, klik Management Tools > Intelligent Bot. Klik Create Bot, lalu klik Create Manually.

    2. Buat robot cerdas dalam mode API.

      1. Di halaman Create intelligent robot, gulir ke bawah dan klik Create in API Mode.

      2. Konfigurasikan parameter berikut dan klik Save.

        1. Visibility Scope: Atur visibilitas robot.

        2. API Configuration: Di bagian Connection Method, pilih mode koneksi.

          • Use Long-lived Connection: Instans secara aktif terhubung ke server WeCom. Di bagian Configuration Method, di bawah Secret, klik Click to get dan simpan Bot ID serta Secret.

          • Use URL Callback: Server WeCom secara aktif mendorong pesan ke callback URL melalui HTTPS. Anda tidak perlu mendapatkan Bot ID atau Secret. Anda hanya perlu mengonfigurasi Token dan EncodingAESKey secara manual saat mengonfigurasi instans di Konsol DataWorks.

        3. Permissions: Atur izin yang diperlukan untuk robot.

    Konfigurasi dengan mode koneksi persisten

    Kembali ke Konsol DataWorks dan buka bagian Channel Configuration pada tab Basic Information di halaman detail instans.

    1. Di bagian Channel Configuration, pilih WeCom sebagai channel.

    2. Pilih Use Long-lived Connection sebagai mode koneksi.

    3. Masukkan Bot ID dan Secret (diperoleh dari Konsol admin WeCom).

    4. Klik Save.

    Konfigurasi dengan mode callback URL

    Konfigurasi instans layanan asisten AI DataWorks

    Kembali ke Konsol DataWorks dan buka bagian Channel Configuration pada tab Basic Information di halaman detail instans.

    1. Di bagian Channel Configuration, pilih WeCom sebagai channel.

    2. Pilih Use URL Callback sebagai mode koneksi.

    3. Masukkan atau hasilkan secara acak parameter berikut:

      Parameter

      Deskripsi

      Persyaratan format

      Token

      Memverifikasi sumber permintaan untuk memastikan permintaan berasal dari server WeCom.

      3 hingga 32 karakter (huruf atau angka)

      EncodingAESKey

      Mengenkripsi konten pesan untuk mencegah data dicegat atau dimodifikasi selama transmisi.

      Persyaratan format: Harus tepat 43 karakter (angka atau huruf).
      Standar enkripsi: algoritma AES-256-CBC.

      Penting

      Jaga kerahasiaan Token dan EncodingAESKey dan jangan mengungkapkannya kepada pihak ketiga mana pun.

      Token dan EncodingAESKey dapat dihasilkan baik di Konsol DataWorks maupun di Konsol admin WeCom. Setelah menghasilkannya di salah satu konsol, salin nilainya ke konsol lainnya. Nilai parameter di kedua sisi harus identik.

    4. Konfigurasikan daftar putih IP: Batasi akses ke callback URL hanya untuk rentang IP tertentu. Daftar putih IP harus mencakup IP server WeCom. Untuk detail cara memperolehnya, lihat dokumentasi IP callback WeCom.

    5. Klik Save.

      Setelah menyimpan konfigurasi, tunggu hingga status instans berubah menjadi Running.

    Di informasi channel WeCom pada halaman detail instans, Anda dapat melihat Callback URL (callbackUrl) dalam format berikut:

    https://ai-assistants.cn-beijing.data.aliyuncs.com/xxxx/plugins/wecom/bot?apikey=sk-ai-assistants-xxxxx

    Salin callback URL lengkap (termasuk parameter ?apikey=...) untuk digunakan pada langkah berikutnya saat mengonfigurasi Konsol admin WeCom. Jika halaman menampilkan Callback configuration failed, periksa penyebab kegagalan dan simpan konfigurasi lagi.

    Konfigurasi di Konsol admin WeCom

    1. Login ke Konsol admin WeCom.

    2. Buka Security & Management > Management Tools > Intelligent Bot > Create Bot, lalu beralih ke Create in API Mode.

    3. Atur metode koneksi ke URL Callback.

    4. Masukkan tiga item berikut:

      Item konfigurasi

      Nilai

      Deskripsi

      URL

      Callback URL yang disalin dari Konsol DataWorks

      URL lengkap, termasuk parameter ?apikey=...

      Token

      Harus sama dengan Token yang dikonfigurasi di Konsol DataWorks

      Harus identik di kedua sisi

      EncodingAESKey

      Harus sama dengan EncodingAESKey yang dikonfigurasi di Konsol DataWorks

      Harus identik di kedua sisi (43 karakter)

    5. Klik Save.

    Setelah disimpan, server WeCom secara otomatis mengirim permintaan verifikasi ke callback URL:

    • Verifikasi berhasil: Konsol admin WeCom menampilkan pesan sukses, dan instans dapat mulai menerima pesan.

    • Verifikasi gagal: Periksa apakah Token dan EncodingAESKey benar-benar sama, instans berada dalam status Running, callback URL disalin lengkap (termasuk bagian ?apikey=), dan daftar putih IP telah dikonfigurasi.

    Daftar putih IP

    Daftar putih IP membatasi IP mana saja yang dapat mengakses callback URL untuk mencegah permintaan tidak sah.

    Metode konfigurasi

    Di bagian IP Whitelist pada halaman edit instans:

    • Add IP: Masukkan alamat IP atau Blok CIDR (misalnya 101.226.62.xx atau 10.0.0.0/8), lalu klik Add.

    • Delete IP: Klik Delete di daftar putih.

    Kami menyarankan Anda memperoleh daftar IP callback terbaru dari Konsol admin WeCom dan menambahkannya ke daftar putih untuk mencegah permintaan callback diblokir.

    Perilaku saat daftar putih kosong

    • Jika belum pernah dikonfigurasi daftar putih: Tidak ada kontrol akses IP yang dibuat, dan semua IP dapat mengakses callback URL.

    • Jika semua IP di daftar putih dihapus: 127.0.0.1 ditambahkan secara otomatis, yang memblokir semua akses eksternal (secara efektif menonaktifkan sementara titik akhir callback). Tambahkan kembali rentang IP callback WeCom untuk memulihkan akses.

    Rotasi API Key

    Jika API Key dikompromikan atau perlu dirotasi secara berkala, arahkan kursor ke tombol URL Callback, lalu klik tombol refresh di jendela pop-up untuk merefresh API Key. Setelah direfresh:

    • API Key baru dihasilkan, dan callback URL lama langsung menjadi tidak valid.

    • Anda harus memperbarui callback URL baru di Konsol admin WeCom.

    Penting

    Setelah rotasi, Anda harus memperbarui callback URL di Konsol admin WeCom. Jika tidak, pesan tidak dapat diterima.

    Uji robot

    1. Di obrolan grup, klik untuk menambahkan anggota, cari robot berdasarkan nama, lalu tambahkan ke grup.

    2. Di obrolan grup yang berisi robot, @mention robot tersebut untuk memulai percakapan streaming.

    Catatan

    Pengujian mode callback URL: Setelah konfigurasi berhasil, ketika pengguna mengirim pesan ke robot di WeCom, instans DataClaw menerima dan memproses pesan tersebut secara real time. Anda dapat memeriksa status channel di halaman detail instans. Status Connected menunjukkan bahwa konfigurasi berhasil.

    Beralih mode

    Beralih dari WebSocket ke callback URL

    1. Di konfigurasi channel, ubah mode koneksi ke URL Callback.

    2. Masukkan Token dan EncodingAESKey.

    3. Setelah mengklik Save, lengkapi konfigurasi di Konsol admin WeCom seperti dijelaskan dalam Konfigurasi di Konsol admin WeCom.

    Beralih dari callback URL kembali ke WebSocket

    1. Di konfigurasi channel, ubah mode koneksi ke Use Long-lived Connection.

    2. Masukkan Bot ID dan Secret.

    3. Setelah mengklik Save, sumber daya gerbang webhook secara otomatis dibersihkan.

    Catatan

    Modifikasi konfigurasi channel memicu restart instans. Setelah restart, hanya data ruang kerja (memori dan keterampilan) yang dipertahankan. Dependensi kustom harus diinstal ulang.

    FAQ

    Verifikasi callback URL gagal?

    • Periksa apakah Token dan EncodingAESKey benar-benar sama dengan yang dikonfigurasi di Konsol DataWorks.

    • Verifikasi bahwa instans berada dalam status Running dan konfigurasi callback tidak menampilkan kegagalan.

    • Verifikasi bahwa callback URL disalin lengkap (termasuk bagian ?apikey=...).

    Konfigurasi berhasil tetapi tidak menerima pesan?

    • Periksa apakah daftar putih IP mencakup rentang IP callback WeCom.

    • Verifikasi bahwa API Key belum dirotasi (jika dirotasi, perbarui callback URL di Konsol admin WeCom).

    • Periksa halaman detail instans untuk pesan error terkait callback.

    Callback masih aktif setelah menghapus instans?

    Saat instans dihapus, semua sumber daya gerbang secara otomatis dibersihkan dan callback URL langsung menjadi tidak valid. Tidak diperlukan tindakan tambahan.

    Callback tidak berfungsi setelah menghapus daftar putih?

    Setelah semua IP di daftar putih dihapus, 127.0.0.1 ditambahkan secara otomatis untuk memblokir semua akses eksternal. Tambahkan kembali rentang IP callback WeCom untuk memulihkan akses.

    Bagaimana cara memperoleh rentang IP server WeCom?

    Lihat dokumentasi IP callback WeCom.