Mode Panggilan Balik WeCom — Aplikasi Kustom

Anggap saja seperti menyiapkan kotak surat kantor khusus untuk asisten AI Anda—alih-alih bersembunyi di obrolan grup, Anda memberinya meja sendiri di mana orang bisa datang dan meninggalkan pesan secara langsung.

Apa Perbedaan Besarnya?

Hermes Agent memberi Anda dua cara untuk menghubungkan WeCom (WeChat Enterprise). Mode Bot itu seperti asisten ramah yang bergabung dengan obrolan grup—cepat disiapkan, tapi terbatas. Mode callback berbeda: Anda membangun aplikasi kustom yang muncul di sidebar WeCom karyawan Anda, seperti aplikasi resmi lainnya. Terasa native, mendukung banyak perusahaan, dan menangani pesan terenkripsi dengan aman.

Kekurangannya? Anda butuh server publik untuk menerima pesan. Tapi jangan khawatir—tunnel sederhana seperti ngrok sudah cukup untuk pengujian.

---

Cara Kerjanya Sebenarnya

Ini alurnya dalam bahasa yang sederhana:

1. Seseorang mengirim pesan ke aplikasi kustom Anda di WeCom.
2. WeCom mengenkripsi pesan itu dan mengirimnya ke endpoint HTTP server Anda.
3. Hermes mendekripsinya, mengantrekannya untuk agen AI, dan langsung memberi tahu WeCom “pesan diterima” (secara diam-diam—pengguna belum melihat apa pun).
4. Agen berpikir selama 3–30 menit (tergantung tugas Anda).
5. Hermes mengirim balasan secara proaktif menggunakan API pesan WeCom.

Tidak ada polling. Tidak ada penundaan. Hanya percakapan asinkron yang bersih.

---

Pengaturan Langkah demi Langkah

1. Buat Aplikasi di Admin WeCom

Masuk ke Konsol Admin WeCom, buka Aplikasi → Buat Aplikasi.
Catat ID Perusahaan (Corp ID) Anda (di bagian atas konsol) dan buat Rahasia Perusahaan (Corp Secret).
Di halaman ringkasan aplikasi, ambil ID Agen (Agent ID).

Di bagian Terima Pesan, konfigurasikan:

• URL: http://IP_PUBLIK_ANDA:8645/wecom/callback
• Token: buat token acak
• EncodingAESKey: buat kunci 43 karakter

2. Atur Variabel Lingkungan

Tambahkan ini ke file .env Anda:

WECOM_CALLBACK_CORP_ID = id-perusahaan-anda
WECOM_CALLBACK_CORP_SECRET = rahasia-perusahaan-anda
WECOM_CALLBACK_AGENT_ID = 1000002
WECOM_CALLBACK_TOKEN = token-callback-anda
WECOM_CALLBACK_ENCODING_AES_KEY = kunci-aes-43-karakter-anda

# Opsional
WECOM_CALLBACK_PORT = 8645
WECOM_CALLBACK_ALLOWED_USERS = user1,user2

3. Mulai Gateway

hermes gateway

Catatan: Hanya gunakan hermes gateway start setelah Anda menjalankan hermes gateway install untuk mendaftarkan layanan.

Adaptor callback memulai server HTTP di port 8645. WeCom akan memverifikasi URL melalui permintaan GET, lalu mulai mengirim pesan melalui POST.

---

Referensi Konfigurasi

Anda juga dapat mengatur ini di config.yaml di bawah platforms.wecom_callback.extra:

Pengaturan	Default	Deskripsi
corp_id	—	Wajib. ID Perusahaan WeCom Anda
corp_secret	—	Wajib. Rahasia aplikasi
agent_id	—	Wajib. ID Agen aplikasi Anda
token	—	Wajib. Token verifikasi callback
encoding_aes_key	—	Wajib. Kunci AES 43 karakter
host	tidak disetel (dual-stack)	Alamat bind untuk server HTTP
port	8645	Port untuk server callback

---

Penutup

Mode Callback WeCom adalah cara “resmi” untuk mengintegrasikan Hermes ke dalam alur kerja perusahaan Anda. Pengaturannya lebih rumit daripada bot, tapi hasilnya adalah pengalaman aplikasi kelas satu yang mulus bagi pengguna Anda.

Tips praktis: Mulailah dengan ngrok sebelum mengekspos server sungguhan. Jalankan ngrok http 8645, gunakan URL itu di konsol WeCom, dan uji dengan satu pengguna. Setelah berhasil, beralihlah ke server produksi dan kunci WECOM_CALLBACK_ALLOWED_USERS ke tim Anda. Selamat membangun!

---