REST API dan token
Kelola bot dari program Anda: jenis token, tindakan REST API, dan tempat melihat contoh permintaan.
Di halaman ini
REST API memungkinkan program Anda menghubungi GetMyBot melalui HTTP, misalnya membaca pesanan dari koleksi, membuat reaksi, atau mengambil statistik. Jika Anda hanya mengatur bot melalui situs, API tidak diperlukan. Pengembang integrasi dapat memulai dari permintaan pertama, lalu melihat format data di referensi interaktif.
Akses diberikan melalui token, yaitu kunci rahasia untuk program. Ada token untuk satu bot dan token pribadi untuk otomatisasi dalam satu ruang kerja yang dipilih. Keduanya memiliki kemampuan berbeda.
Token API bot
Buat token di Pengaturan → Token API. Setiap token terikat pada satu bot dan dapat mengakses alamat REST bot tersebut untuk reaksi, pelanggan, koleksi, statistik, dan sebagainya. Nilai token hanya ditampilkan sekali saat dibuat. Simpan di tempat aman. Daftar kemudian hanya menampilkan nama, sebagian karakter, dan tanggal pembuatan. Hapus token yang tidak diperlukan.
Token akses pribadi (PAT)
Token pribadi, disingkat PAT, dimulai dengan mbp_. Token dibuat di akun Anda dan digunakan untuk otomatisasi serta integrasi dalam satu ruang kerja yang dipilih. Kirim melalui Authorization: Bearer mbp_…. Setiap token memiliki cakupan akses (scopes) seperti reactions:read atau bots:write; * mencakup semua tindakan publik yang masih diizinkan oleh hak akun Anda. Token memiliki masa berlaku dan hanya disimpan dalam bentuk hash. Dengan PAT, program tidak perlu mengetahui kata sandi Anda. Lihat Izin akses dan token.
Data yang tersedia melalui API
API menyediakan bot dan pengaturannya, reaksi termasuk impor/ekspor, pelanggan dan label, koleksi dan isinya, statistik dan riwayat permintaan, serta siaran. Anda dapat membuat panel sendiri, sinkronisasi, atau otomatisasi di atas GetMyBot.
Saluran dan WhatsApp
Koneksi Telegram, WhatsApp, dan VK juga dapat dikelola melalui REST. Membaca saluran dan template WhatsApp memerlukan bots:read; mengubahnya memerlukan bots:write. Tidak ada cakupan khusus untuk saluran.
GET /api/channels/capabilities(bots:read): daftar kemampuan tiap saluran. Sesi situs web dapat memakainya tanpa scope PAT.GET /api/bots/{botID}/channels(bots:read): daftar saluran bot.POST /api/bots/{botID}/channels(bots:write): hubungkan WhatsApp atau VK.DELETE /api/bots/{botID}/channels/{channelID}(bots:write): putuskan saluran.GET /api/bots/{botID}/channels/{channelID}/templates(bots:read): daftar template WhatsApp.POST /api/bots/{botID}/channels/{channelID}/templates(bots:write): buat template dan kirim untuk diperiksa Meta.POST /api/bots/{botID}/channels/{channelID}/templates/sync(bots:write): perbarui daftar dari Meta.PUT /api/bots/{botID}/channels/{channelID}/templates/{templateID}(bots:write): ubah template.DELETE /api/bots/{botID}/channels/{channelID}/templates/{templateID}(bots:write): hapus template.POST /api/bots/{botID}/channels/{channelID}/templates/media(bots:write): unggah contoh gambar, video, atau dokumen pada judul template.
Format permintaan dan respons tersedia di Referensi API. Cara menggunakan saluran dan templatenya dijelaskan di WhatsApp.
Koneksi CRM
CRM memerlukan cakupan tersendiri, crm:read dan crm:write. Cakupan integrations:* tidak menggantikannya. Setiap alamat juga memeriksa hak Reaksi pada bot.
Cara menghubungkan bergantung pada layanan:
POST /api/bots/{botID}/crm/connections/amocrm/start(crm:write): kirim{"account_key": "acme.amocrm.ru"}, lalu bukaredirect_urldalam peramban. Paling banyak tiga percobaan per menit per akun. Jika aplikasi OAuth amoCRM belum dikonfigurasi pada platform, server mengirim503. Bitrix24 juga mengirim503jika konfigurasinya belum tersedia.GET /api/integrations/crm/{provider}/callback: alamat tujuan setelah izin diberikan dalam peramban. Tidak memerlukan token karena menggunakan keadaan sekali pakai yang berlaku lima menit dari langkah awal. Respons hanya berisi ringkasan aman, tanpa data akses.POST /api/bots/{botID}/crm/connections/retailcrm(crm:write): hubungkan dengan kunci API.POST /api/bots/{botID}/crm/connections/ozmacrm(crm:write): hubungkan dengan OIDC, nama pengguna, dan pengaturan data.
API juga menyediakan pencarian kolom dan tahapan CRM, versi pemetaan, pratinjau, sinkronisasi awal dan ulang, riwayat tindakan, penyelesaian konflik, serta DELETE /api/bots/{botID}/crm/connections/{connectionID} untuk memutus koneksi. Tiga tindakan pelanggan, yaitu melihat status CRM, sinkronisasi manual, dan ekspor percakapan, berada di bawah /api/bots/{botID}/subscribers/{subscriberID}/crm/…; tindakan ini memerlukan cakupan subscribers:* dan hak Obrolan.
Enam alat MCP hanya-baca juga dapat membaca CRM. Lihat MCP. Daftar lengkap alamat dan cara kerja setiap penyedia ada di Integrasi CRM.
Konten, kampanye email, dan pop-up
Fitur ini memiliki cakupan sendiri. Setiap alamat juga memeriksa hak Reaksi pada bot.
content:read/content:writeuntuk dokumen dan template konten:GET|POST /api/bots/{botID}/content,GET /api/bots/{botID}/content/{documentID},PATCH /api/bots/{botID}/content/{documentID}/draft,POST /api/bots/{botID}/content/{documentID}/publish|clone|archive|test-send,POST /api/bots/{botID}/content/{documentID}/validate|preview,GET /api/bots/{botID}/content/test-recipients,GET|POST /api/bots/{botID}/content-templates, danDELETE /api/bots/{botID}/content-templates/{templateID}.email_campaigns:read/email_campaigns:writeuntuk kampanye email dan laporannya:GET|POST /api/bots/{botID}/email-campaigns,GET|PATCH /api/bots/{botID}/email-campaigns/{campaignID},GET /api/bots/{botID}/email-campaigns/{campaignID}/report|recipients|links,POST /api/bots/{botID}/email-campaigns/{campaignID}/consent-preview, danPOST /api/bots/{botID}/email-campaigns/{campaignID}/test-send|schedule|clone|pause|resume|cancel|archive.popups:read/popups:writeuntuk pop-up:GET|POST /api/bots/{botID}/popups,PATCH|DELETE /api/bots/{botID}/popups/{popupID},GET /api/bots/{botID}/popups/{popupID}/stats|experiment, danPOST /api/bots/{botID}/popups/preflight.settings:read/settings:writeuntuk domain pengirim dan alamat email masuk di/api/bots/{botID}/email/…. Membaca memerlukan akses ke bot; membuat, memeriksa, atau menghapus juga memerlukan hak Reaksi.
consent-preview, validate, dan preview memakai POST meskipun tidak mengubah data. Karena itu, permintaan tersebut tetap masuk catatan audit. Untuk perubahan, kirim expected_revision yang Anda baca sebelumnya. Respons 409 berarti data sudah berubah: muat ulang sebelum mencoba lagi. Menjadwalkan kampanye melalui POST /api/bots/{botID}/email-campaigns/{campaignID}/schedule juga memerlukan "confirm": true; jika kampanye belum siap, respons 422 berisi hasil pemeriksaan penerima.
Alamat publik untuk pelacakan, berhenti berlangganan, dan webhook penyedia (/e/t/…, /u/…, /esp/{provider}/webhook, /esp/{provider}/inbound) bukan bagian API bertoken. Lihat Kampanye email.
Push peramban dan SDK pelanggan
Keduanya memiliki cakupan sendiri. Hak Analitik pada bot diperlukan untuk membaca; hak Reaksi diperlukan untuk mengubah. Semua perubahan tercatat dalam audit.
Push peramban memakai web_push:read / web_push:write:
GET /api/bots/{botID}/web-push: pengaturan yang aman untuk dibaca, termasuk kunci publik VAPID, kontak, alamat asal tautan yang diizinkan, dan jam tenang. Kunci pribadi tidak dikirim.GET /api/bots/{botID}/web-push/subscriptions: langganan terbaru dengan status persetujuan, jenis peramban, bahasa, dan zona waktu. Alamat layanan push dan kunci enkripsinya tidak dikirim.GET /api/bots/{botID}/web-push/report: jumlah langganan dan hasil pengiriman.POST /api/bots/{botID}/web-push/enable: membuat sepasang kunci VAPID pada penggunaan pertama; pemakaian berikutnya memperbarui pengaturan tanpa membuat duplikat.PATCH /api/bots/{botID}/web-push: mengubah kontak, alamat asal tautan, jam tenang, atau status aktif.POST /api/bots/{botID}/web-push/rotate-keys: mengirim409beserta jumlah langganan aktif sampai"confirm": truedikirim. Konfirmasi mematikan semua langganan lama.POST /api/bots/{botID}/web-push/test: mengirim satu pesan uji ke satu langganan dengan tautan ke dokumen Push yang sudah diterbitkan. Pengiriman biasa memakai siaran atau kampanye.
SDK pelanggan memakai customer_sdk:read / customer_sdk:write:
GET /api/bots/{botID}/customer-sdk: pengaturan proyek tanpa rahasia, termasuk kunci proyek, wilayah, daftar aplikasi yang diizinkan, versi rahasia identitas, dan masa berlaku rahasia lama saat pergantian.GET /api/bots/{botID}/customer-sdk/installations: hingga 200 pemasangan terbaru.GET /api/bots/{botID}/customer-sdk/report: jumlah pemasangan dan token push.POST /api/bots/{botID}/customer-sdk/enable: membuat proyek dan menampilkan rahasia identitas sekali. Panggilan berikutnya hanya memperbarui pengaturan. Jika rahasia penanda tangan kunci proyek belum disiapkan pada server, responsnya503.PATCH /api/bots/{botID}/customer-sdk: mengubah daftar aplikasi yang diizinkan dan status aktif.POST /api/bots/{botID}/customer-sdk/rotate-secret: menampilkan rahasia identitas baru; rahasia lama masih bekerja satu hari.DELETE /api/bots/{botID}/customer-sdk/installations/{installationID}: mencabut akses satu perangkat.
Alamat untuk aplikasi pelanggan, /sdk/v1/*, bukan bagian API ini. Alamat tersebut menerima token pemasangan dan versi identitas, bukan PAT. Demikian juga /api/* tidak menerima token pemasangan. Spesifikasi terpisah tersedia tanpa login di GET /sdk/openapi.yaml.
Siaran
Siaran hanya memiliki cakupan broadcasts:write. Tidak ada broadcasts:read, sehingga membaca daftar, laporan, dan penerima juga memerlukan broadcasts:write. Token yang hanya boleh membaca siaran tidak tersedia. Setiap alamat juga memeriksa hak Reaksi pada bot.
Siaran baru yang memakai konten, penerima, dan saluran memiliki alamat:
GET /api/bots/{botID}/broadcasts: daftar;?archived=truemenyertakan arsip.POST /api/bots/{botID}/broadcasts: buat draf.PATCH /api/bots/{botID}/broadcasts/{broadcastID}: ubah draf.POST /api/bots/{botID}/broadcasts/{broadcastID}/preflight: periksa penerima tanpa mengirim, tetapi tetap dicatat dalam audit sebagaiPOST.POST /api/bots/{botID}/broadcasts/{broadcastID}/schedule: jalankan.POST /api/bots/{botID}/broadcasts/{broadcastID}/test-send: uji pada satu kontak yang telah dikonfirmasi.POST /api/bots/{botID}/broadcasts/{broadcastID}/archive: arsipkan.GET /api/bots/{botID}/broadcasts/{broadcastID}/report: laporan menurut saluran.GET /api/bots/{botID}/broadcasts/{broadcastID}/recipients: penerima, denganlimitdancursor.
Siaran lama yang dibuat dari reaksi tetap tersedia. Jalankan melalui POST /api/bots/{botID}/reactions/{reactionID}/broadcast dengan isi {"paid": false, "labels": ["vip"]}. Hanya cara lama ini yang dapat membatasi penerima menurut label. Empat alamat berikut dipakai oleh siaran lama dan baru: GET /api/bots/{botID}/broadcasts/{broadcastID} serta POST /api/bots/{botID}/broadcasts/{broadcastID}/pause|resume|cancel.
Server mencari ID siaran baru terlebih dahulu, lalu siaran lama. Karena itu, isi permintaan dan respons bergantung pada jenis siaran. Siaran baru memerlukan {"expected_revision": N} dan mengembalikan seluruh data siaran. Siaran lama mengabaikan isi permintaan dan mengembalikan {"status": "pausing"}, {"status": "resuming"}, atau {"status": "canceled"}.
Isi permintaan diperiksa ketat: kolom yang tidak dikenal menghasilkan 400. Saat mengubah siaran baru, kirim expected_revision yang baru dibaca; 409 berarti Anda perlu memuat ulang. schedule juga memerlukan "confirm": true; tanpanya server mengirim 400.
Kode respons siaran:
402: paket pemilik bot tidak mendukung siaran.403: siaran berbayar untuk bot ini belum diaktifkan.409: versi data lama atau siaran belum siap, misalnya konten belum terbit, segmen belum dihitung, eksperimen belum dimulai, atau penerima kosong.422: konten tidak ada atau tidak sesuai untuk salah satu saluran.429: pesan uji dikirim terlalu sering.
Di MCP, cakupan yang sama digunakan oleh start_broadcast, get_broadcast, pause_broadcast, resume_broadcast, cancel_broadcast, list_content_broadcasts, dan get_content_broadcast_report. Tiga alat pembacaan tetap memerlukan broadcasts:write. MCP tidak menyediakan pembuatan dan perubahan draf, pemeriksaan penerima, pengiriman uji, penjadwalan, atau pengarsipan siaran baru; untuk itu gunakan REST. Alat pause_broadcast, resume_broadcast, dan cancel_broadcast hanya bekerja untuk siaran lama dari reaksi. Cara menggunakan kedua jenis siaran dijelaskan di Siaran.
Akses seluler
Aplikasi seluler GetMyBot memakai token akses dan token pembaruan tersendiri untuk menampilkan ringkasan bot. Aplikasi ini memakai server yang sama, tetapi cara masuknya berbeda dari PAT.
Referensi API
Referensi API menampilkan alamat publik yang dapat diakses dengan PAT, parameter, format permintaan dan respons, cakupan yang diperlukan, serta contoh curl, JavaScript, dan Python. Anda juga dapat menjalankan permintaan uji dari halaman itu dengan token Anda.
Corong dan eksperimen
Definisi dan laporan corong tersimpan memakai analytics:read dan analytics:write. Menyimpan kelompok pelanggan sebagai segmen juga memerlukan segments:write. Eksperimen dan laporannya memakai experiments:read dan experiments:write. Semua alamat ini juga memeriksa hak Analitik pada bot. Untuk pemilik yang sudah masuk, setiap POST, PUT, PATCH, atau DELETE dicatat dalam audit, termasuk permintaan laporan atau kelompok pelanggan yang tidak mengubah data tetapi memakai POST. Pembacaan melalui GET tidak dicatat.
Untuk laporan, kirim rentang waktu UTC dalam format RFC3339. Rentang corong dan eksperimen paling lama 366 hari. Pendapatan eksperimen memiliki bilangan bulat minor dan kode mata uang ISO 4217 currency. Jangan menjumlahkan mata uang berbeda di sisi program Anda.
curl "$BASE_URL/api/bots/$BOT_ID/funnels?limit=50&cursor=$CURSOR" \
-H "Authorization: Bearer $PAT"
Kirim kembali cursor next dari server tanpa mengubahnya. Cursor atau isi permintaan yang salah menghasilkan 400. Data bot yang tidak dapat diakses atau versi eksperimen yang diminta tetapi tidak ada menghasilkan 404. Versi data lama atau konflik pemilihan pemenang menghasilkan 409. Lihat format lengkap di Referensi API, Corong, dan Eksperimen.
- Corong tersimpan: aturan dan permintaan kelompok pelanggan.
- Eksperimen dan atribusi: versi, kejadian, dan pendapatan.
Keamanan
- Token ditampilkan sekali; simpan sebagai rahasia.
- Rahasia bot dan data akses lainnya disimpan terenkripsi.
- Permintaan terautentikasi dengan metode
POST,PUT,PATCH, danDELETEdicatat dalam audit; pembacaanGETtidak.
Customer AI, analitik alur, playbook, dan Meta
Fitur berikut dapat diotomatisasi melalui AI. Nama dalam API tetap berbahasa Inggris; penjelasan berikut menunjukkan kegunaannya:
- Managed AI:
POST /api/v1/ai/responses(managed_ai:invoke) memanggil AI danGET /api/v1/ai/usage(managed_ai:usage:read) membaca pemakaian. Profil:fast,balanced,quality; penyedia:auto,openai,anthropic,deepseek. Panggilan memerlukanIdempotency-Key. Kesalahan kunci penyedia milik Anda tidak otomatis memindahkan permintaan ke Managed AI berbayar. - Copilot: membuat saran perubahan reaksi di
/api/reactions/{rootID}/copilot/proposals. Di/api/copilot/proposals/{proposalID}, saran dapat dibaca, diperiksa, diuji, diterapkan, atau ditolak. Menerapkannya membuat draf, bukan langsung menerbitkan reaksi. - Flow Intelligence: menunjukkan jalannya reaksi, contoh pelaksanaan, dan aturan analisis. Pengaturan dan penghitungan ulang terbatas ada di
/api/bots/{botID}/flow-intelligence/*. - Explainable Replay: membaca dan memutar ulang catatan pelaksanaan, membuat contoh uji tanpa data sensitif, dan memeriksa hasil ulang. Agen tidak dapat membuka materi yang dilindungi.
- Vertical Playbooks: katalog alur siap pakai
/api/playbooks/catalog, melanjutkan pengaturan yang terputus, memeriksa kesiapan, memasang, memperbarui, serta melihat hasilnya. - Outcome onboarding: pengaturan awal langkah demi langkah sesuai tujuan. Alamatnya
POST|PATCH /api/onboarding/sessiondanPOST /api/onboarding/session/complete. - Messenger dan Instagram:
/api/meta/connectionsmengembalikan alamat untuk memberi izin Meta di peramban. Setelah itu, akun dan halaman dalam ruang kerja dapat diperiksa, dipilih, dan dihubungkan. Token rahasia tidak dikirim dalam respons.
Hanya administrator tertinggi platform yang dapat mengatur kunci penyedia, pemilihan rute model, harga, dan rekonsiliasi pembayaran. API dan MCP pengguna tidak menyediakan tindakan tersebut.
Copilot, Flow Intelligence, Explainable Replay, dan Vertical Playbooks harus diaktifkan untuk ruang kerja Anda. Jika belum tersedia atau dimatikan, permintaan akan ditolak. MCP mengikuti batas yang sama.
Langkah berikutnya
- Referensi API: daftar alamat dan contoh interaktif.
- Pengaturan, tim, dan akses: membuat token API bot.
- Koleksi dan data: data yang dapat dibaca melalui API.
- Permintaan web dan webhook: menghubungkan layanan ke dua arah.