Langsung ke konten
WbizTool

Panduan produk

Kunci API dan Client ID

Kunci API memungkinkan software Anda sendiri, serta alat seperti Zapier, n8n, Make, dan plugin WordPress, mengirim pesan WhatsApp dari nomor-nomor workspace Anda. Kode Anda sendiri mengirim kunci di header Authorization: Bearer; integrasi meminta dua nilai dari halaman Kunci API: Client ID workspace Anda dan salah satu kuncinya. Halaman yang sama memuat rahasia yang menandatangani webhook kami.

Siapa yang dapat melakukannya: hanya Pemilik – semua Pemilik workspace, bukan hanya pembuatnya. Pemilik dapat melihat, membuat, menyalin, dan menghapus semua kunci workspace, siapa pun yang membuatnya. Editor dan Analis tidak melihat Kunci API di sidebar atau di halaman Pengaturan, dan tautan ke halaman itu membuka Profil bagi mereka (lihat Peran dan izin). Kunci berfungsi di semua paket, termasuk uji coba gratis; pesan yang Anda kirim dengannya memakai pesan workspace.

Buka Kunci API di bawah Integrasi di sidebar, atau buka Pengaturan → Kunci API.

Tab Kunci API di Pengaturan: Client ID 5012 dengan tombol Salin, kunci Zapier dan Website toko beserta tanggal pembuatannya, empat karakter terakhir setiap kunci, Salin kunci dan Hapus, serta tombol Buat kunci bergaris tepi (1)

Setiap kunci menampilkan namanya, kapan kunci itu Dibuat, empat karakter terakhir kunci (misalnya •••• 7f3a), Salin kunci, dan Hapus. Kunci terbaru tampil paling atas.

Membuat kunci API#

  1. Klik Buat kunci

    Di Pengaturan → Kunci API, klik Buat kunci di kanan atas kartu.

  2. Beri nama (opsional)

    Di Nama (opsional), ketik aplikasi yang akan menggunakannya, seperti n8n atau Website (maksimal 50 karakter). Jika dibiarkan kosong, kunci diberi nama seperti "API Key 3", sesuai petunjuk di bawah kolom.

  3. Buat kuncinya

    Klik Buat kunci.

    Dialog Buat kunci API: n8n diketik di Nama (opsional) (2), petunjuk tentang nama default, dan tombol Buat kunci bergaris tepi (3)
  4. Salin kuncinya

    Kunci API baru Anda menampilkan kunci lengkapnya: "Salin sekarang – Anda tidak akan melihat kunci lengkapnya lagi. Nanti, “Salin kunci” menyalinnya tanpa menampilkannya." Klik Salin ("Kunci disalin."), tempel kunci ke aplikasi atau integrasi Anda, lalu klik Selesai.

    Dialog Kunci API baru Anda: nama n8n, kunci lengkap dengan tombol Salin bergaris tepi (4), catatan kuning Salin sekarang – Anda tidak akan melihat kunci lengkapnya lagi, dan Selesai
  • Maksimal 10 kunci per workspace. Jika sudah ada 10, Buat kunci berwarna abu-abu, dan mengarahkan kursor ke tombol itu menampilkan "Anda dapat memiliki maksimal 10 kunci API. Hapus salah satu untuk membuat yang baru."
  • Kunci tidak kedaluwarsa, dan tidak dapat diganti namanya atau dinonaktifkan: kunci berfungsi sampai dihapus.
  • Satu kunci per aplikasi. Beri nama setiap kunci sesuai aplikasi yang menggunakannya, agar Anda dapat mengganti atau menghapus satu kunci tanpa merusak yang lain.
  • Workspace mana: kunci adalah milik workspace yang dipilih saat Anda membuatnya, dan setiap request dengan kunci itu bekerja pada workspace tersebut: nomor, pesan, dan paketnya. Untuk mengirim dari workspace lain, beralih ke workspace itu dan buat kunci di sana.

Yang perlu dimasukkan di aplikasi Anda#

Field APINama di integrasiTempat menemukannya
client_idClient IDBaris Client ID di bagian atas kartu Kunci API. Salin di sebelahnya menyalinnya ("Client ID disalin."). Nilainya sama untuk setiap kunci di workspace.
api_keyAPI keyKunci yang Anda salin: 40 karakter, berupa angka dan huruf a sampai f.
whatsapp_clientWhatsApp Client IDID nomor, seperti ID 101 ⧉ di kartu nomor tersebut di Nomor WhatsApp: klik untuk menyalinnya, atau tampilkan semua nomor dengan API akun WhatsApp. ID ini menentukan nomor mana yang mengirim. Lihat Halaman Nomor WhatsApp.

Tempat memasukkannya:

  • Kode Anda sendiri: di header Authorization: Bearer YOUR_API_KEY pada setiap request (disarankan). Kunci menentukan workspace-nya, sehingga client_id boleh tidak dikirim; jika Anda mengirimnya, nilainya tetap harus Client ID workspace ini. Lihat Mengirim kunci di header, dan Kirim pesan untuk pesan pertama dengan cURL, Python, Node.js, dan PHP.
  • Zapier: Client ID dan kunci API saat Anda menghubungkan akun.
  • n8n: Client ID, API Key, dan WhatsApp Client ID di kredensial WbizTool.
  • Make, Pabbly Connect, dan alat lain: body request HTTP.
  • WordPress: WbizTool → Settings, di bawah API Configuration.

Google Sheets dan Shopify disiapkan di dashboard dan tidak memerlukan kunci.

Mengirim kunci di header#

Setiap endpoint /api/v1/ menerima kunci di header Authorization, seperti yang juga akan dilakukan API v2 mendatang:

Authorization: Bearer YOUR_API_KEY
  • client_id bersifat opsional jika memakai header: kunci yang menentukan workspace. Jika Anda juga mengirim client_id, nilainya harus Client ID workspace ini, seperti sebelumnya.
  • Kirim kunci di satu tempat saja. Jika memakai header, jangan sertakan api_key di body, atau kirim kunci yang sama. Jika keduanya berbeda, kunci di header yang dipakai bila kunci itu valid; jika header berisi hal lain (misalnya token dari alat lain), api_key di body yang dipakai.
  • Kunci di body tetap berfungsi (client_id dan api_key sebagai JSON atau field formulir), jadi tidak ada yang berubah bagi aplikasi dan integrasi yang mengirimnya. Header lebih baik karena body request lebih sering tercatat di log, proxy, dan riwayat form builder dibandingkan header.
  • Field formulir, unggahan multipart, dan body JSON semuanya berfungsi dengan header.
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "phone": "919876543210", "msg": "Hello from WbizTool"}'

Menguji kunci Anda#

Panggil Cek kredensial (POST /api/v1/me/) dengan kunci Anda dan, jika mau, whatsapp_client. "status": 1 dengan "message": "Okay" berarti semuanya cocok. Panggilan ini tidak mengirim apa pun dan tidak memakai pesan, tetapi tidak memeriksa apakah pesan Anda masih tersisa atau apakah nomornya terhubung.

curl -X POST https://wbiztool.com/api/v1/me/ -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"whatsapp_client": 101}'

Kunci yang berfungsi menjawab {"status": 1, "message": "Okay", "name": "…"}.

Menyalin kunci lagi#

Klik Salin kunci di sebelah kunci. Kunci lengkap masuk ke clipboard tanpa ditampilkan di halaman; Anda melihat, misalnya, "“Zapier” disalin." dan tombol menampilkan Disalin ✓ sejenak. Anda tidak perlu kunci baru hanya karena kehilangan kunci lama.

Untuk mengetahui kunci mana yang dipakai sebuah aplikasi, bandingkan empat karakter terakhir kuncinya dengan daftar.

Menghapus kunci#

  1. Klik Hapus

    Klik Hapus di sebelah kunci.

  2. Konfirmasi

    Dialog "Hapus “…”?" memperingatkan: "Semua yang menggunakan kunci ini langsung berhenti berfungsi: Zap di Zapier, skenario n8n dan Make, plugin WordPress, dan panggilan API Anda sendiri. Berikan kunci lain terlebih dahulu. Tindakan ini tidak dapat dibatalkan." Klik Hapus kunci. Anda melihat "“…” dihapus."

Sejak itu, request dengan kunci tersebut mendapatkan Auth Error: invalid api key. Apa yang sudah dilakukannya tetap berlaku: pesan yang sudah diantrekannya tetap terkirim (batalkan di Laporan jika perlu), dan pengingat yang dibuatnya tetap berjalan. Pemicu Zapier Incoming WhatsApp Message yang disiapkan dengan kunci itu juga tetap menerima pesan, karena webhook-nya sudah terpasang di nomor: nonaktifkan Zap di Zapier untuk menghentikannya.

Mengganti kunci#

Ganti kunci jika mungkin bocor, jika seseorang yang dapat menyalinnya keluar, atau secara berkala. Tidak ada tombol rotasi: buat kunci baru terlebih dahulu agar tidak ada yang berhenti di antaranya.

  1. Buat kunci baru

    Buat kunci dan salin. Jika sudah ada 10 kunci, hapus dulu satu yang tidak lagi Anda gunakan.

  2. Perbarui aplikasi Anda

    Tempel kunci baru ke setiap aplikasi dan integrasi yang menggunakan kunci lama, lalu periksa masing-masing, misalnya dengan Cek kredensial.

  3. Hapus kunci lama

    Hapus kunci itu. Kunci langsung berhenti berfungsi.

  4. Periksa penyalahgunaan (setelah kebocoran)

    Periksa Laporan untuk pesan yang tidak Anda kirim dan batalkan yang masih menunggu. Di Pengingat, hapus pengingat yang tidak Anda buat, karena pengingat itu tetap berjalan. Hapus nomor yang tidak Anda tambahkan di Nomor WhatsApp. Dengan add-on Unibox, periksa Nomor kotak masuk untuk lencana Zapier atau webhook yang tidak Anda kenali.

Menjaga keamanan kunci Anda#

Kunci tidak memiliki izin sendiri: siapa pun yang memilikinya dapat melakukan semua hal yang bisa dilakukan API di workspace Anda, apa pun perannya. Termasuk mengirim pesan dari nomor mana pun di workspace (memakai pesan workspace), membaca riwayat pesannya, membatalkan pesan yang menunggu, mengelola pengingat dan file media, memeriksa nomor, dan menghubungkan nomor baru.

  • Simpan kunci di server Anda, dalam environment variable atau penyimpanan kredensial integrasi Anda. Jangan pernah menaruh kunci di JavaScript situs web, aplikasi seluler, spreadsheet bersama, atau kode yang Anda publikasikan.
  • Jangan kirim kunci lewat email atau chat. Tempel langsung ke aplikasi yang membutuhkannya.
  • Gunakan satu kunci per aplikasi, dan hapus kunci yang tidak lagi Anda gunakan.
  • Ganti kunci secara berkala, dan segera jika ada kunci yang mungkin bocor.

Client ID saja bukan rahasia, tetapi perlakukan setiap kunci seperti kata sandi.

Kunci API v2#

API v2 memiliki kuncinya sendiri, yang dibuat di kartu Kunci API v2 pada tab yang sama. Kunci ini lebih aman daripada kunci di atas:

  • Ditampilkan sekali. Kunci lengkap (wbz_live_…) hanya ditampilkan saat Anda membuatnya; WbizTool hanya menyimpan sidik jarinya. Jika hilang, cabut kunci itu dan buat yang baru.
  • Hanya yang dibutuhkan. Centang apa yang boleh dilakukan kunci (mengirim pesan, membaca pesan, pengingat, nomor, media, pemeriksaan nomor), batasi ke sebagian nomor Anda, dan beri tanggal kedaluwarsa jika Anda mau.
  • Kunci uji. Kunci uji (wbz_test_…) memeriksa setiap request seperti kunci live, tetapi tidak mengirim apa pun – untuk membangun dan mencoba integrasi.
  • Terakhir digunakan. Setiap kunci menampilkan kapan dan dari mana kunci itu terakhir digunakan. Cabut langsung menghentikannya, beserta endpoint webhook yang dibuat dengan kunci itu.

Kunci di atas hanya berfungsi dengan API v1, dan kunci API v2 hanya dengan v2. Lihat Pindah dari v1 ke v2.

Tanda tangan webhook#

WbizTool menandatangani setiap webhook yang dikirim kepada Anda, sehingga endpoint Anda dapat memastikan request benar-benar berasal dari kami dan tidak diubah di tengah jalan: webhook status pesan (terkirim, gagal, dibatalkan, kedaluwarsa), event koneksi nomor, dan webhook kotak masuk. Body-nya sama seperti sebelumnya; ada dua header tambahan:

HeaderNilai
WbizTool-TimestampWaktu kami mengirimnya, dalam detik Unix, seperti 1792310400
WbizTool-Signaturev1= dan HMAC-SHA256 heksadesimal dari <timestamp>.<raw body>, dibuat dengan rahasia penandatanganan workspace Anda

Tanda tangan mencakup byte persis yang kami kirim: field formulir apa adanya saat tiba, seluruh body multipart saat gambar kode QR dilampirkan, dan JSON webhook kotak masuk. Penerima yang mengabaikan header ini tetap berfungsi.

Mendapatkan rahasia penandatanganan#

Di Pengaturan → Kunci API, kartu Rahasia penandatanganan webhook di bawah kunci-kunci Anda menampilkan empat karakter terakhir rahasia, seperti •••• b70d. Setiap workspace memiliki satu rahasia untuk semua webhook-nya; rahasia dibuat bersama webhook pertama yang kami kirim kepada Anda.

  1. Klik Tampilkan rahasia baru

    Klik Tampilkan rahasia baru (atau Buat rahasia jika workspace belum memilikinya). Dialog "Ganti rahasia penandatanganan?" memperingatkan bahwa rahasia saat ini langsung berhenti berfungsi. Klik Buat rahasia baru.

  2. Salin rahasianya

    Rahasia penandatanganan webhook Anda menampilkan rahasia lengkap satu kali. Klik Salin dan simpan di tempat yang dapat dibaca penerima webhook Anda, seperti environment variable. Anda tidak akan melihatnya lagi: jika hilang, buat yang baru.

Hanya Pemilik yang melihat kartu ini. Membuat rahasia baru langsung menggantikan yang lama, jadi segera perbarui penerima Anda; webhook yang terkirim di antaranya gagal dalam pemeriksaan Anda.

Memeriksa webhook#

Hitung tanda tangan dari body mentah (sebelum framework Anda mem-parsing-nya), bandingkan dengan header dalam waktu konstan, dan tolak timestamp yang lebih lama dari 5 menit agar request lama tidak dapat diputar ulang:

import hashlib, hmac, time

def verify(secret: str, body: bytes, headers) -> bool:
    ts, sig = headers["WbizTool-Timestamp"], headers["WbizTool-Signature"]
    mac = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts)) < 300 and hmac.compare_digest(mac, sig)

Di Django, berikan request.body dan request.headers; di Flask, request.get_data() dan request.headers.

Jawab dengan 2xx jika pemeriksaan lolos dan 401 jika gagal. Webhook kotak masuk yang memiliki secret webhook sendiri di nomornya tetap juga membawa X-Wbiztool-Signature; WbizTool-Signature adalah skema yang sama di setiap webhook.

Pemecahan masalah#

Pesan atau masalahYang harus dilakukan
Tidak ada Kunci API di sidebar atau di halaman PengaturanAnda adalah Editor atau Analis di workspace ini. Minta kunci kepada Pemilik, atau minta dijadikan Pemilik.
Buat kunci berwarna abu-abuWorkspace sudah memiliki 10 kunci. Hapus satu yang tidak lagi Anda gunakan.
"Tidak dapat menyalin – browser Anda memblokir clipboard. Coba lagi."Izinkan akses clipboard untuk wbiztool.com di browser Anda, atau coba browser lain. Di Kunci API baru Anda, Anda juga dapat memilih kunci dan menyalinnya sendiri.
"Tidak dapat mengambil kunci. Coba lagi."Muat ulang halaman dan klik Salin kunci lagi.
"Kunci tersebut sudah dihapus."Pemilik lain telah menghapusnya sementara itu. Daftar menampilkan kunci yang tersisa.
Sebuah kunci menampilkan Tidak aktifKunci itu tidak berfungsi. Hapus dan buat kunci baru.
Auth Error: invalid api keyKunci sudah dihapus atau salah ketik (salin lagi, tanpa spasi), atau client_id bukan Client ID workspace ini.
Auth Error - Please send correct API key and Client idapi_key tidak ada atau kosong.
Webhook gagal dalam pemeriksaan tanda tangan AndaPeriksa terhadap body mentah, bukan field yang sudah di-parsing lalu dienkode ulang; gunakan rahasia saat ini (setelah Tampilkan rahasia baru, hanya rahasia baru yang berfungsi); dan periksa jam server Anda (timestamp yang selisihnya lebih dari 5 menit ditolak).
Auth Errorclient_id atau api_key tidak ada, body bukan JSON atau field formulir, atau request bukan POST, pada endpoint seperti Kirim ke banyak nomor, Jadwalkan pesan, dan Status pesan.
Invalid client id., Invalid Client Id, client_id is required, atau client_id must be a valid integerclient_id tidak ada atau bukan angka seperti 5012. Salin dari baris Client ID.
Invalid WhatsApp Client ID (Cek kredensial) atau Invalid whatsapp client … (Kirim pesan)ID nomor tidak ada di workspace kunci ini, atau nomornya sudah dihapus. Salin ID … ⧉ dari Nomor WhatsApp.
Email "Tidak ada pesan dari … selama 2 hari"Workspace Anda biasanya mengirim lewat API atau integrasi setiap hari, dan tidak ada apa pun selama 2 hari. Email ini menyebutkan kunci yang dibuat atau dihapus dalam seminggu terakhir: pastikan aplikasi masih memiliki kunci yang berfungsi (lihat Notifikasi).
Invalid API key atau Invalid client_id for this API keyAPI verifikasi nomor atau media: kunci salah atau sudah dihapus, atau client_id bukan milik workspace kunci tersebut.
This API key is not linked to a workspace. Create a new API key in WbizTool.Kunci berasal dari penyiapan akun lama. Buat kunci baru dan gunakan kunci itu.
Only workspace owners and editors can connect Zapier triggersKunci dibuat oleh seseorang yang bukan lagi Pemilik atau Editor. Buat kunci baru dan hubungkan ulang Zapier.
Demo Account can not access apisAkun demo tidak dapat menggunakan API. Daftar untuk akun Anda sendiri.
Not enough creditsKunci berfungsi, tetapi workspace memakai paket gratis dan pesannya sudah habis. Lihat Paket dan tagihan.
Request bekerja pada workspace yang salahKunci dibuat di workspace lain. Beralih workspace dan buat kunci di sana.

Terkait#