Platform Pengembang

Bangunlah di atas
Platform Koneksi

Dua API yang ampuh — API server RESTful untuk manajemen perangkat dan orkestrasi komunikasi, serta protokol CBBP tingkat rendah untuk kontrol lencana langsung.

Referensi API RESTProtokol CBBP
OpenAPI 3.0JSON / RESTBluetooth + WiFiDukungan Webhook
Connection Studio
Explorer
examples
send_command.http
response.json
list_devices.http
webhooks.http
src
docs
send_command.http
response.json
# Send a CBBP command via the server
POST /api/v1/devices/{uuid}/cbbp

{
  "command": "speak",
  "object": {
    "text": "Shift starts in 5 minutes",
    "volume": 85,
    "language": "en-US"
  }
}

# Response
{
  "result": 0,
  "detail": "ok"
}
main
HTTPUTF-8Ln 2, Col 1

API REST

Manajemen siklus hidup perangkat secara lengkap — penyediaan, konfigurasi, firmware, komunikasi, dan analitik — melalui HTTPS standar.

Jelajahi REST API →

Protokol CBBP

Protokol Dasar Com Badge — protokol perintah JSON untuk kontrol perangkat langsung melalui Bluetooth (aplikasi), WiFi (proksi server), atau pengiriman lokal.

Jelajahi CBBP →

Webhooks

Berlangganan peristiwa perangkat secara real-time — komunikasi, perubahan status, pembaruan lokasi — yang dikirim sebagai payload HTTP POST ke endpoint Anda.

Jelajahi Webhooks →

Early Access: The Connection API is currently available by special request to select partners. Contact us to apply for access.

Pro or Plus plan required: Badges must be on the Pro or Plus plan to be controlled via the API.

Memulai

Autentikasi

API Connection menggunakan autentikasi token Bearer. Semua permintaan harus menyertakan token akses JWT yang valid di header Authorization.

Dapatkan token

Kirimkan kredensial Anda ke endpoint otentikasi menggunakan metode POST. Anda akan menerima access_token yang berlaku singkat dan refresh_token yang berlaku lebih lama.

Gunakan token

Sertakan token di setiap permintaan:

Authorization: Bearer <access_token>
POST/api/v1/auth/login
Meminta
{
  "email": "admin@yourorg.com",
  "password": "••••••••"
}
Respons 200
{
  "access_token": "eyJhbG...",
  "refresh_token": "dGhpcw...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

URL Dasar & Pembuatan Versi

Semua endpoint API diberi versi di bawah /api/v1/. URL dasar bergantung pada implementasi Anda.

Untuk penerapan berbasis cloud, gunakan titik akhir regional yang ditetapkan untuk organisasi Anda. Untuk penerapan Server lokal, gunakan nama host server Anda.

LingkunganURL Dasar
Awan (AS)https://beta.connection.app/api/v1
Di Lokasihttps://<your-server>/api/v1
Jenis Konten
Semua isi permintaan dan respons menggunakan application/json. Sertakan Content-Type: application/json pada permintaan yang memiliki isi.

Kesalahan & Kode Status

API ini menggunakan kode status HTTP standar. Respons kesalahan mencakup kode yang dapat dibaca mesin dan pesan yang dapat dibaca manusia.

StatusArti
200Kesuksesan
201Dibuat
400Permintaan Buruk — parameter tidak valid
401Tidak sah — token hilang atau kedaluwarsa
403Dilarang — izin tidak mencukupi
404Tidak Ditemukan
500Kesalahan Server Internal
Respons Kesalahan
{
  "error": {
    "code": "device_not_found",
    "message": "No device with that UUID exists in your organization",
    "status": 404
  }
}
API REST

Gambaran Umum API REST

API REST Connection Server menyediakan akses terprogram penuh ke armada perangkat Anda, infrastruktur komunikasi, dan analitik. API ini mengikuti konvensi RESTful dengan badan permintaan/respons JSON.

Autentikasi API
Pengguna
Perangkat
Saluran
Komunikasi
Jembatan Audio
Percakapan
Isi
Lokasi
Notifikasi Push
Penyimpanan
Operasi Massal
Tanggal & Waktu

Autentikasi

Autentikasi berbasis token. Login mengembalikan token yang harus dikirim sebagai Otorisasi: Token<token> pada semua permintaan selanjutnya.

POST/api/v1/loginOtentikasi pengguna dan terima token otentikasi.
POST/api/v1/login-deviceOtentikasi perangkat berdasarkan UUID dan alamat MAC.
POST/api/v1/logoutMembatalkan token sesi saat ini

Pengguna

Buat dan kelola akun pengguna. Endpoint GET /users/user mengembalikan pengguna yang saat ini terautentikasi.

GET/api/v1/users/userAmbil profil pengguna yang saat ini sedang login.
POST/api/v1/users/userBuat akun pengguna baru
PATCH/api/v1/users/user/{uuid}Perbarui profil pengguna (misalnya, gambar profil)

Perangkat

Mencantumkan dan memeriksa perangkat, mengelola asosiasi pengguna-perangkat, membaca dan menulis pengaturan dan status per perangkat, menangani firmware dan citra penyimpanan, serta menerima log dan laporan kerusakan.

GET/api/v1/devices/deviceDaftar semua perangkat
GET/api/v1/devices/device/{uuid}Dapatkan informasi perangkat secara detail termasuk firmware dan pengaturan.
PUT/api/v1/devices/association/{uuid}Perbarui hubungan antara pengguna dan perangkat.
DELETE/api/v1/devices/association/{uuid}Hapus asosiasi pengguna-perangkat dan pengaturan yang tersimpan.
GET/api/v1/devices/device/{device_uuid}/settingsDaftar pengaturan yang tersimpan untuk suatu perangkat
POST/api/v1/devices/device/{device_uuid}/settingsSimpan pengaturan khusus perangkat
GET/api/v1/devices/device/{device_uuid}/statusDapatkan status perangkat (konektivitas, baterai, sensor, status audio)
POST/api/v1/devices/device/{device_uuid}/statusTampilkan status perangkat dari perangkat tersebut.
GET/api/v1/devices/device/{device_uuid}/contextDaftar nilai konteks yang tersimpan untuk suatu perangkat.
POST/api/v1/devices/device/{device_uuid}/ingest-contextMenerima konteks GPS + WiFi dari perangkat.
GET/api/v1/devices/firmwareDaftar rilis firmware yang kompatibel dengan versi perangkat keras/perangkat lunak tertentu.
GET/api/v1/devices/firmware/{uuid}/{image_type}/fetchMengambil citra firmware secara bertahap.
GET/api/v1/devices/languageDaftar bahasa dan suara perangkat yang didukung
GET/api/v1/devices/storage_imageUnduh citra penyimpanan perangkat yang disesuaikan untuk wilayah tertentu.
POST/api/v1/devices/logMenerima berkas log dari sebuah perangkat
POST/api/v1/devices/crashMenerima core dump dari sebuah perangkat.
PATCH/api/v1/devices/crash/{uuid}Perbarui catatan kecelakaan

Proksi CBBP

Kirimkan perintah CBBP apa pun ke perangkat melalui server. Server meneruskan perintah tersebut melalui koneksi WiFi perangkat dan mengembalikan respons perangkat. Respons outgoing-make juga menyertakan CBBPMessage yang akan langsung dieksekusi oleh perangkat.

POST/api/v1/devices/device/{device_uuid}/cbbpKirim perintah CBBP ke perangkat melalui server.
GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}Mengambil status dan respons dari perintah CBBP yang sebelumnya dikirim.

Isi permintaan berupa amplop perintah CBBP. Objek CBBPCommand yang tersimpan melacak status pengiriman: UNSET → SENT → RECEIVED atau TIMED_OUT.

Lakukan polling GET /cbbp/ untuk memeriksa apakah perangkat telah menerima dan merespons perintah tersebut.
Permintaan — pesan keluar
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
Respons — Status Perintah CBBP
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

Saluran

Saluran adalah elemen dasar komunikasi. Jenis-jenisnya meliputi ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService, dan ChannelRecorder.

GET/api/v1/channels/channelDaftar saluran, opsional difilter berdasarkan object_type
POST/api/v1/channels/channelBuat saluran (ChannelGroup, ChannelContact, atau ChannelExternalNumber)
PATCH/api/v1/channels/channel/{uuid}Perbarui ChannelGroup atau ChannelContact
DELETE/api/v1/channels/channel/{uuid}Hapus saluran
DELETE/api/v1/channels/{uuid}Menghapus Grup Saluran
DELETE/api/v1/channels/by-type/{channelType}Hapus semua saluran dengan tipe tertentu (saat ini ChannelContact)
GET/api/v1/channels/associationDaftar asosiasi saluran untuk pengguna saat ini
POST/api/v1/channels/associationAjukan permohonan untuk bergabung dengan sebuah saluran.
PATCH/api/v1/channels/association/{uuid}Terima, tolak, atau perbarui pengaturan asosiasi.
DELETE/api/v1/channels/association/{uuid}Hapus hubungan dengan saluran.
GET/api/v1/channels/historyDapatkan riwayat akses saluran yang dipaginasi untuk pengguna saat ini.
POST/api/v1/channels/historyBuat entri riwayat saluran.
GET/api/v1/channels/searchCari saluran berdasarkan string kueri dan filter tipe opsional.

Komunikasi

Memulai dan mengelola sesi komunikasi aktif — panggilan keluar, VCP, perekaman, dan streaming konten. Respons panggilan keluar mencakup CBBPMessage yang akan segera ditindaklanjuti oleh perangkat.

POST/api/v1/communicate/outgoing-makeBuat saluran keluar ke ChannelPeople, ChannelGroup, ChannelContact, atau ChannelContactNumber.
POST/api/v1/communicate/incoming-acceptanceTerima atau tolak permintaan bergabung ke saluran yang masuk.
POST/api/v1/communicate/closeTutup saluran komunikasi aktif saat ini pada perangkat.
POST/api/v1/communicate/vcp-activateMulai Protokol Komunikasi Suara (VCP) pada server dan perangkat.
POST/api/v1/communicate/vcp-deactivateNonaktifkan VCP, kembali ke saluran sebelumnya.
POST/api/v1/communicate/recording-activateAktifkan mode perekaman pada server dan perangkat.
POST/api/v1/communicate/content-startBuka saluran streaming untuk konten audio.
POST/api/v1/communicate/request-vocalizationMenghasilkan audio TTS untuk teks yang diberikan, dan secara opsional menerjemahkannya.

Jembatan Audio

Akses rekaman percakapan di ruang rapat, termasuk transkrip lengkap, daftar peserta, dan ringkasan yang dihasilkan AI. Mendukung berbagai templat ringkasan (catatan rapat, catatan kelas, layanan kesehatan, dll.) dan pembuatan audio TTS untuk ringkasan.

GET/api/v1/bridge/conversationsDaftar semua percakapan jembatan
GET/api/v1/bridge/conversations/{uuid}Dapatkan percakapan terperinci termasuk transkrip, peserta, dan ringkasan.
POST/api/v1/bridge/conversations/{conversation_uuid}/summaryMenghasilkan ringkasan percakapan oleh AI.
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audioHasilkan audio untuk ringkasan percakapan.

Percakapan

Sesi percakapan berbasis AI menggunakan ChatGPT, Gemini, atau mesin bawaan. Mendukung berbagai persona (Dokter, Tutor, Mekanik, dll.) dan riwayat pesan yang dipaginasi.

GET/api/v1/conversations/conversationDaftar sesi generator AI, dapat difilter berdasarkan persona dan alat.
POST/api/v1/conversations/conversationBuat sesi percakapan AI baru
GET/api/v1/conversations/conversation/{uuid}Ambil kembali sesi percakapan dengan ringkasan/pembaruan status tidak aktif opsional.
DELETE/api/v1/conversations/conversation/{uuid}Hapus sesi percakapan
GET/api/v1/conversations/conversation/{uuid}/messagesDaftar pesan dalam percakapan
POST/api/v1/conversations/conversation/{uuid}/messagesTambahkan pesan pengguna dan terima balasan dari AI.

Isi

Jelajahi dan putar konten audio streaming di berbagai perangkat. Konten diatur dalam struktur kategori; konten populer dapat difilter berdasarkan kota, wilayah, atau negara.

GET/api/v1/content/categoriesDapatkan struktur pohon kategori konten.
GET/api/v1/content/contentDaftar konten yang tersedia dalam suatu kategori
GET/api/v1/content/popularCantumkan konten populer untuk kota, wilayah, atau negara tertentu.

Lokasi

Mengkonversi koordinat geografis ke objek kota, wilayah, dan negara yang terstruktur. Digunakan oleh perangkat saat menerima konteks.

POST/api/v1/location/determineMenguraikan garis lintang/garis bujur menjadi kota, wilayah, dan negara.

Notifikasi Push

Daftarkan aplikasi seluler untuk menerima notifikasi push FCM. Mendukung iOS, Android, dan platform web.

POST/api/v1/push-notifications/pushDaftarkan aplikasi seluler untuk notifikasi push FCM (iOS, Android, web)

Penyimpanan

Unduh file yang tersimpan pada objek model, dan jalankan penghapusan latar belakang gambar (mengembalikan hasil yang dikodekan base64).

GET/api/v1/storage/retrieve/{path}Unduh file yang tersimpan berdasarkan jalur.
POST/api/v1/storage/remove-backgroundMenghapus latar belakang dari gambar (mengembalikan base64)

Operasi Massal

Eksekusi beberapa operasi API dalam satu permintaan HTTP. Berikan parameter single_transaction=true untuk membungkus semua operasi dalam satu transaksi atomik — kegagalan pada item apa pun akan membatalkan seluruh batch.

POST/api/v1/bulkEksekusi beberapa operasi API dalam satu permintaan, opsional sebagai satu transaksi atomik.

Tanggal & Waktu

Mengembalikan tanggal dan waktu server saat ini dalam format GMT+0. Tidak memerlukan otentikasi. Digunakan oleh perangkat untuk menyinkronkan jam internalnya.

GET/api/v1/current-datetimeMenampilkan tanggal dan waktu saat ini dalam format GMT+0
Protokol CBBP

Protokol Dasar Lencana Kom

CBBP adalah protokol perintah JSON ringan untuk interaksi langsung dengan lencana Koneksi. Protokol ini memberi Anda kendali penuh atas setiap fungsi perangkat keras dan perangkat lunak pada perangkat tersebut.

Format Pesan

Setiap interaksi CBBP terdiri dari pesan perintah yang dikirim ke perangkat dan pesan hasil yang dikembalikan oleh perangkat.

Kolom objek baik dalam permintaan maupun respons berisi data spesifik perintah dan dapat dihilangkan jika tidak diperlukan.

Dokumentasi protokol lengkap tersedia untuk mitra terdaftar. Hubungi perwakilan bisnis Connection Anda atau hubungi developer@connectionbadge.com untuk meminta akses ke referensi perintah CBBP lengkap, termasuk skema permintaan/respons lengkap, kode kesalahan, dan panduan integrasi.
Pesan Perintah
{
  "command": "command_name",
  "object": {
    // optional command parameters
  }
}
Pesan Hasil
{
  "result": 0,          // 0 = success, -1 = error
  "detail": "ok",      // human-readable status
  "object": {          // optional response data
    // command-specific fields
  }
}

Mengangkut

Pesan CBBP dapat dikirimkan ke lencana melalui tiga cara pengiriman yang berbeda, tergantung pada arsitektur integrasi Anda.

Bluetooth (Aplikasi)

Kirim perintah CBBP langsung dari aplikasi seluler melalui BLE. Membutuhkan perangkat yang sudah dipasangkan dan berada dalam jangkauan.

SDK Seluler

WiFi atau Bluetooth melalui Server

Gunakan proxy CBBP melalui REST API — POST /devices//cbbp. Server secara otomatis mengarahkan ke perangkat melalui WiFi atau Bluetooth tergantung pada cara lencana terhubung. Paling umum digunakan untuk integrasi backend.

API REST

Pengiriman Internal

Pengiriman CBBP di perangkat atau antar proses. Digunakan oleh firmware lencana untuk mengarahkan perintah antar subsistem internal.

Hanya Firmware

Perintah Daya

Mengontrol status daya perangkat — tidur, bangun, mulai ulang, dan pengaturan ulang pabrik.

PowerRebootSegera mulai ulang perangkat.
PowerDeepsleepMasuk ke mode tidur nyenyak (hemat daya).
FactoryResetHapus semua konfigurasi dan atur ulang ke pengaturan pabrik.

Perintah WiFi

Konfigurasikan jaringan nirkabel, pindai AP (Access Point), periksa status koneksi, dan kelola kredensial yang tersimpan.

WiFiScanPindai titik akses WiFi yang tersedia.
WiFiAPTestUji konektivitas ke titik akses WiFi tertentu.
WiFiAPJoinHubungkan ke titik akses WiFi menggunakan kredensial yang diberikan.

Perintah Bluetooth

Mengontrol periklanan BLE, pemasangan, dan komunikasi antar lencana.

BTScanBTPindai perangkat Bluetooth klasik.
BTScanBLEPindai perangkat BLE.
DeviceBLEServiceAvailableTandai layanan BLE sebagai tersedia.
DeviceBLEServiceUnavailableTandai layanan BLE sebagai tidak tersedia.
DeviceBLEActiveAktifkan radio BLE.
DeviceBLEIdleAtur radio BLE ke status siaga.
DeviceBLEAdvChannelAddTambahkan saluran ke muatan iklan BLE.
DeviceBTScanMulai pemindaian perangkat Bluetooth.
DeviceBTA2DStartMulai streaming audio Bluetooth A2DP.
DeviceBTA2DEndHentikan streaming audio Bluetooth A2DP.
DeviceBTNativeAssistStartAktifkan asisten suara Bluetooth bawaan.
DeviceBTNativeAssistEndHentikan asisten suara Bluetooth bawaan.

Perintah Pengaturan

Membaca dan menulis konfigurasi perangkat — nama tampilan, zona waktu, bahasa, dan flag fitur.

SettingsListGetAmbil semua pengaturan sebagai daftar pasangan kunci-nilai.
SettingsListSetTulis beberapa nilai pengaturan sekaligus.
SettingsGetDapatkan nilai dari satu pengaturan berdasarkan kunci.
SettingsSetTetapkan nilai untuk satu pengaturan.
SettingsSendKirim pengaturan saat ini ke server.
SettingsClearHapus nilai pengaturan tertentu.
SettingsEraseHapus semua pengaturan yang tersimpan.

Perintah Firmware

Memicu pembaruan firmware OTA, memeriksa status pembaruan, dan menanyakan versi firmware saat ini pada perangkat.

FirmwareCheckPeriksa apakah pembaruan firmware tersedia.
FirmwareUpdateMulai pembaruan firmware OTA.
FirmwareValidateMemvalidasi integritas citra firmware yang diunduh.

Perintah Perangkat

Siklus hidup perangkat, otentikasi, konfigurasi, pencatatan log, status, dan kontrol perangkat keras.

NoOpTidak ada operasi / tetap hidup.
TestTes konektivitas dasar.
DeviceDateTimeDapatkan atau atur tanggal dan waktu perangkat.
DeviceAuthenticateLakukan otentikasi perangkat dengan server.
DeviceConfigureTerapkan muatan konfigurasi ke perangkat.
DevicePostConnectionTasksJalankan tugas inisialisasi pasca-koneksi.
DeviceStorageLoadMuat data dari penyimpanan internal perangkat.
DeviceLoadCustomAudioMuat file audio kustom ke perangkat.
DeviceCoredumpSendUnggah file dump core crash ke server.
DeviceAttachHubungkan perangkat ke sesi server.
DeviceDetachLepaskan perangkat dari sesi server.
DeviceLogSendUnggah log perangkat ke server.
DeviceConnectionTestUji konektivitas server.
DeviceStatusSendKirim status perangkat ke server.
DeviceStatusGetDapatkan status perangkat saat ini.
DeviceInteractionMemicu peristiwa interaksi perangkat.
DeviceSetAPIHostTetapkan host server API.
DeviceTestMicsJalankan uji mandiri mikrofon.
HardwareI2CCommandMengirim perintah I2C mentah ke perangkat periferal perangkat keras.

Perintah Komunikasi

Memulai panggilan, mengirim pesan, mengelola sesi komunikasi aktif, dan mengontrol perekaman.

CommunicateChannelJoinBergabunglah dengan saluran komunikasi.
CommunicateChannelLeaveTinggalkan saluran komunikasi.
CommunicateChannelChangeBeralihlah ke saluran lain.
CommunicateChannelCloseTutup saluran komunikasi.
CommunicateReceiveIncomingBeri tahu perangkat tentang komunikasi yang masuk.
CommunicateRequestOutgoingMinta pengiriman komunikasi keluar.
CommunicateVCPActivateAktifkan sesi Protokol Komunikasi Suara.
CommunicateVCPDeactivateNonaktifkan sesi VCP.
CommunicateRecordingActivateMulailah merekam komunikasi yang sedang berlangsung.
CommunicateIncomingAcceptTerima panggilan masuk.
CommunicateIncomingRejectTolak panggilan masuk.
CommunicateHFPCallStartMulai panggilan telepon Bluetooth HFP.
CommunicateHFPCallEndAkhiri panggilan telepon Bluetooth HFP.
CommunicateContentStartMulai melakukan streaming konten audio ke perangkat.
CommunicateContentStopHentikan pemutaran konten audio.
SocketReceiveStatusMenerima pembaruan status WebSocket.

Perintah Audio

Mengontrol volume speaker, penguatan mikrofon, profil audio, dan pemutaran teks ke ucapan.

AudioPlayStorageMemutar file audio dari penyimpanan internal perangkat.
AudioPlayContentMemutar konten audio yang di-streaming.
AudioSetVolumeAtur volume output speaker.

Perintah LED

Atur warna LED, kecerahan, dan pola animasi pada lampu indikator lencana.

DeviceIlluminationSetAtur warna LED dan pola pencahayaan.

Perintah Internal

Perintah pengiriman internal digunakan untuk penyampaian konteks, riwayat saluran, vokalisasi, dan dekode audio.

InternalSendContextKirim data konteks ke penangan konteks internal.
InternalSendChannelHistoryKirim riwayat saluran ke penangan internal.
InternalRequestVocalizationMinta pengubahan suara menjadi teks secara internal.
InternalHandleVocalizationRTPMenangani aliran RTP vokalisasi yang masuk.
InternalDecodeAudioMenerjemahkan aliran audio yang masuk.

Perintah Seluler

Perintah untuk mengkoordinasikan lencana dengan aplikasi seluler yang dipasangkan — notifikasi push, sinkronisasi status aplikasi, dan tautan langsung (deep linking).

MobileServiceStatusLaporkan status layanan seluler ke perangkat. (Seluler → Perangkat)
MobileSocketOpenInstruksikan aplikasi seluler untuk membuka koneksi WebSocket. (Perangkat → Seluler)
MobileSocketClosePerintahkan aplikasi seluler untuk menutup koneksi WebSocket. (Perangkat → Seluler)
MobileSocketStatusLaporkan status WebSocket ke aplikasi seluler. (Perangkat → Seluler)
MobileReceiveStatusLaporkan status penerimaan ke aplikasi seluler. (Perangkat → Seluler)
MobileSocketUpdateKirim pembaruan data WebSocket ke aplikasi seluler. (Perangkat → Seluler)
MobilePTTStartBeri tahu aplikasi seluler bahwa transmisi PTT telah dimulai. (Perangkat → Seluler)
MobilePTTStopBeri tahu aplikasi seluler bahwa transmisi PTT telah berakhir. (Perangkat → Seluler)
MobileContextSetAtur data konteks pada aplikasi seluler. (Perangkat → Seluler)
MobileEchoPerintah Echo untuk menguji konektivitas seluler. (Perangkat → Seluler)

Siap untuk membangun?

Bergabunglah dengan komunitas pengembang Connection dan dapatkan akses ke perangkat sandbox, SDK, dan dukungan khusus.

Hubungi kami