Platform Pembangun

Bina berdasarkan
Platform Sambungan

Dua API yang berkuasa — API pelayan RESTful untuk pengurusan peranti dan orkestrasi komunikasi dan protokol CBBP peringkat rendah untuk kawalan lencana langsung.

Rujukan API RESTProtokol CBBP
OpenAPI 3.0JSON / RESTBluetooth + WiFiSokongan 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

Pengurusan kitaran hayat peranti penuh — peruntukan, konfigurasi, perisian tegar, komunikasi dan analitik — melalui HTTPS standard.

Terokai API REST →

Protokol CBBP

Protokol Asas Lencana Com — protokol arahan JSON untuk kawalan peranti langsung melalui Bluetooth (aplikasi), WiFi (proksi pelayan) atau penghantaran tempatan.

Terokai CBBP →

Webhook

Langgan peristiwa peranti masa nyata — komunikasi, perubahan status, kemas kini lokasi — dihantar sebagai muatan HTTP POST ke titik akhir anda.

Terokai 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.

Bermula

Pengesahan

API Sambungan menggunakan pengesahan token Bearer. Semua permintaan mesti menyertakan token akses JWT yang sah dalam pengepala Kebenaran.

Dapatkan token

POST kelayakan anda ke titik akhir auth. Anda akan menerima access_token yang berjangka masa pendek dan refresh_token yang berjangka masa lebih lama.

Gunakan token

Sertakan token dalam setiap permintaan:

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

URL Asas & Versi

Semua titik akhir API diversikan di bawah /api/v1/. URL asas bergantung pada penggunaan anda.

Untuk penggunaan yang dihoskan oleh awan, gunakan titik akhir serantau yang diberikan kepada organisasi anda. Untuk penggunaan Pelayan di premis, gunakan nama hos pelayan anda.

Alam SekitarURL Asas
Awan (AS)https://beta.connection.app/api/v1
Di Premishttps://<your-server>/api/v1
Jenis Kandungan
Semua badan permintaan dan respons menggunakan application/json. Sertakan Content-Type: application/json pada permintaan dengan badan.

Kod Ralat & Status

API menggunakan kod status HTTP standard. Respons ralat termasuk kod yang boleh dibaca mesin dan mesej yang boleh dibaca manusia.

StatusMaksudnya
200Kejayaan
201Dicipta
400Permintaan Buruk — parameter tidak sah
401Tidak dibenarkan — token hilang atau tamat tempoh
403Dilarang — kebenaran tidak mencukupi
404Tidak Dijumpai
500Ralat Pelayan Dalaman
Respons Ralat
{
  "error": {
    "code": "device_not_found",
    "message": "No device with that UUID exists in your organization",
    "status": 404
  }
}
API REST

Gambaran Keseluruhan API REST

API REST Pelayan Sambungan menyediakan akses programatik penuh kepada armada peranti, infrastruktur komunikasi dan analitik anda. Ia mengikuti konvensyen RESTful dengan badan permintaan/respons JSON.

Pengesahan API
Pengguna
Peranti
Saluran
Komunikasi
Jambatan Audio
Perbualan
Kandungan
Lokasi
Pemberitahuan Tolak
Penyimpanan
Operasi Pukal
Tarikh & Masa

Pengesahan

Pengesahan berasaskan token. Log masuk mengembalikan token yang mesti dihantar sebagai Pengesahan: Token<token> atas semua permintaan berikutnya.

POST/api/v1/loginSahkan pengguna dan terima token pengesahan
POST/api/v1/login-deviceSahkan peranti melalui UUID dan alamat MAC
POST/api/v1/logoutBatalkan token sesi semasa

Pengguna

Cipta dan uruskan akaun pengguna. Titik akhir GET /users/user mengembalikan pengguna yang sedang disahkan.

GET/api/v1/users/userDapatkan profil pengguna yang sedang log masuk
POST/api/v1/users/userCipta akaun pengguna baharu
PATCH/api/v1/users/user/{uuid}Kemas kini profil pengguna (cth. imej profil)

Peranti

Senaraikan dan periksa peranti, uruskan perkaitan pengguna-peranti, baca dan tulis tetapan dan status setiap peranti, kendalikan perisian tegar dan imej storan serta terima log dan laporan ranap sistem.

GET/api/v1/devices/deviceSenaraikan semua peranti
GET/api/v1/devices/device/{uuid}Dapatkan maklumat peranti terperinci termasuk firmware dan tetapan
PUT/api/v1/devices/association/{uuid}Kemas kini perkaitan antara pengguna dan peranti
DELETE/api/v1/devices/association/{uuid}Alih keluar perkaitan pengguna-peranti dan tetapan yang disimpan
GET/api/v1/devices/device/{device_uuid}/settingsSenaraikan tetapan yang disimpan untuk peranti
POST/api/v1/devices/device/{device_uuid}/settingsSimpan tetapan khusus peranti
GET/api/v1/devices/device/{device_uuid}/statusDapatkan status peranti (kesambungan, bateri, sensor, keadaan audio)
POST/api/v1/devices/device/{device_uuid}/statusSiarkan status peranti daripada peranti
GET/api/v1/devices/device/{device_uuid}/contextSenaraikan nilai konteks yang disimpan untuk peranti
POST/api/v1/devices/device/{device_uuid}/ingest-contextTerima konteks GPS + WiFi daripada peranti
GET/api/v1/devices/firmwareSenaraikan keluaran perisian tegar yang serasi dengan versi perkakasan/perisian yang diberikan
GET/api/v1/devices/firmware/{uuid}/{image_type}/fetchAmbil imej perisian tegar dalam beberapa bahagian
GET/api/v1/devices/languageSenaraikan bahasa dan suara peranti yang disokong
GET/api/v1/devices/storage_imageMuat turun imej storan peranti tersuai untuk penempatan
POST/api/v1/devices/logTerima fail log daripada peranti
POST/api/v1/devices/crashTerima dump teras daripada peranti
PATCH/api/v1/devices/crash/{uuid}Kemas kini rekod ranap sistem

Proksi CBBP

Hantar sebarang arahan CBBP ke peranti melalui pelayan. Pelayan menyampaikan arahan melalui sambungan WiFi peranti dan mengembalikan respons peranti. Respons outgoing-make juga membenamkan CBBPMessage yang akan dilaksanakan oleh peranti dengan segera.

POST/api/v1/devices/device/{device_uuid}/cbbpHantar arahan CBBP ke peranti melalui pelayan
GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}Dapatkan status dan respons arahan CBBP yang dihantar sebelum ini

Badan permintaan ialah sampul arahan CBBP. Objek CBBPCommand yang disimpan menjejaki status penghantaran: UNSET → SENT → RECEIVED atau TIMED_OUT.

Tinjauan GET /cbbp/ untuk menyemak sama ada peranti menerima dan bertindak balas terhadap arahan tersebut.
Permintaan — outgoingMessage
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
Respons — Status CBBPCommand
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

Saluran

Saluran merupakan teras komunikasi primitif. Jenis-jenisnya termasuk ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService dan ChannelRecorder.

GET/api/v1/channels/channelSenaraikan saluran, secara pilihan ditapis mengikut jenis_objek
POST/api/v1/channels/channelCipta saluran (ChannelGroup, ChannelContact atau ChannelExternalNumber)
PATCH/api/v1/channels/channel/{uuid}Kemas kini ChannelGroup atau ChannelContact
DELETE/api/v1/channels/channel/{uuid}Padam saluran
DELETE/api/v1/channels/{uuid}Padam Kumpulan Saluran
DELETE/api/v1/channels/by-type/{channelType}Padam semua saluran daripada jenis yang diberikan (kini ChannelContact)
GET/api/v1/channels/associationSenaraikan perkaitan saluran untuk pengguna semasa
POST/api/v1/channels/associationMinta perkaitan dengan saluran
PATCH/api/v1/channels/association/{uuid}Terima, tolak atau kemas kini tetapan perkaitan
DELETE/api/v1/channels/association/{uuid}Alih keluar perkaitan dengan saluran
GET/api/v1/channels/historyDapatkan sejarah akses saluran berhalaman untuk pengguna semasa
POST/api/v1/channels/historyCipta entri sejarah saluran
GET/api/v1/channels/searchCari saluran mengikut rentetan pertanyaan dan penapis jenis pilihan

Komunikasi

Mulakan dan uruskan sesi komunikasi aktif — panggilan keluar, VCP, rakaman dan penstriman kandungan. Respons keluar-buat termasuk Mesej CBBP yang akan bertindak balas dengan segera oleh peranti.

POST/api/v1/communicate/outgoing-makeMulakan saluran keluar ke ChannelPeople, ChannelGroup, ChannelContact atau ChannelContactNumber
POST/api/v1/communicate/incoming-acceptanceTerima atau tolak permintaan penyertaan saluran masuk
POST/api/v1/communicate/closeTutup saluran komunikasi aktif semasa pada peranti
POST/api/v1/communicate/vcp-activateMulakan Protokol Komunikasi Suara (VCP) pada pelayan dan peranti
POST/api/v1/communicate/vcp-deactivateNyahaktifkan VCP, kembali ke mana-mana saluran sebelumnya
POST/api/v1/communicate/recording-activateAktifkan mod rakaman pada pelayan dan peranti
POST/api/v1/communicate/content-startBuka saluran penstriman ke kandungan audio
POST/api/v1/communicate/request-vocalizationJana audio TTS untuk teks yang diberikan, secara pilihan menterjemahkannya

Jambatan Audio

Akses perbualan jambatan yang dirakam termasuk transkrip penuh, senarai peserta dan ringkasan yang dijana AI. Menyokong berbilang templat ringkasan (nota mesyuarat, nota kelas, penjagaan kesihatan, dsb.) dan penjanaan audio TTS untuk ringkasan.

GET/api/v1/bridge/conversationsSenaraikan semua perbualan jambatan
GET/api/v1/bridge/conversations/{uuid}Dapatkan perbualan terperinci termasuk transkrip, peserta dan ringkasan
POST/api/v1/bridge/conversations/{conversation_uuid}/summaryJana ringkasan AI untuk perbualan
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audioJana audio untuk ringkasan perbualan

Perbualan

Sesi perbualan berkuasa AI menggunakan ChatGPT, Gemini atau enjin natif. Menyokong berbilang persona (Doktor, Tutor, Mekanik, dll.) dan sejarah mesej berhalaman.

GET/api/v1/conversations/conversationSenaraikan sesi penjana AI, boleh ditapis mengikut persona dan alat
POST/api/v1/conversations/conversationCipta sesi perbualan AI baharu
GET/api/v1/conversations/conversation/{uuid}Dapatkan sesi perbualan dengan ringkasan/kemas kini pilihan
DELETE/api/v1/conversations/conversation/{uuid}Padam sesi perbualan
GET/api/v1/conversations/conversation/{uuid}/messagesSenaraikan mesej dalam perbualan
POST/api/v1/conversations/conversation/{uuid}/messagesTambah mesej pengguna dan terima balasan AI

Kandungan

Layari dan mainkan penstriman kandungan audio pada peranti. Kandungan disusun dalam pokok kategori; kandungan popular boleh ditapis mengikut bandar, wilayah atau negara.

GET/api/v1/content/categoriesDapatkan pokok kategori kandungan
GET/api/v1/content/contentSenaraikan kandungan yang tersedia dalam kategori
GET/api/v1/content/popularSenaraikan kandungan popular untuk bandar, rantau atau negara tertentu

Lokasi

Selesaikan koordinat geografi kepada objek bandar, wilayah dan negara yang berstruktur. Digunakan oleh peranti apabila mengambil konteks.

POST/api/v1/location/determineTentukan latitud/longitud kepada bandar, wilayah dan negara

Pemberitahuan Tolak

Daftar aplikasi mudah alih untuk menerima pemberitahuan tolak FCM. Menyokong iOS, Android dan sasaran web.

POST/api/v1/push-notifications/pushDaftar aplikasi mudah alih untuk pemberitahuan tolak FCM (iOS, Android, web)

Penyimpanan

Muat turun fail yang disimpan pada objek model dan jalankan penyingkiran latar belakang imej (mengembalikan hasil yang dikodkan base64).

GET/api/v1/storage/retrieve/{path}Muat turun fail yang disimpan mengikut laluan
POST/api/v1/storage/remove-backgroundAlih keluar latar belakang daripada imej (mengembalikan base64)

Operasi Pukal

Laksanakan berbilang operasi API dalam satu permintaan HTTP. Lulus single_transaction=true untuk membungkus semua operasi dalam satu transaksi atom — kegagalan pada mana-mana item akan mengembalikan keseluruhan kelompok.

POST/api/v1/bulkLaksanakan berbilang operasi API dalam satu permintaan, secara pilihan sebagai satu transaksi atomik

Tarikh & Masa

Mengembalikan tarikh dan masa pelayan semasa dalam GMT+0. Tidak memerlukan pengesahan. Digunakan oleh peranti untuk menyegerakkan jam dalamannya.

GET/api/v1/current-datetimeKembalikan tarikh dan masa semasa dalam GMT+0
Protokol CBBP

Protokol Asas Lencana Com

CBBP ialah protokol arahan JSON ringan untuk interaksi langsung dengan lencana Sambungan. Ia memberi anda kawalan penuh ke atas setiap fungsi perkakasan dan perisian pada peranti.

Format Mesej

Setiap interaksi CBBP terdiri daripada mesej arahan yang dihantar ke peranti dan mesej hasil yang dikembalikan oleh peranti.

Medan objek dalam kedua-dua permintaan dan respons membawa data khusus arahan dan boleh diabaikan apabila tidak diperlukan.

Dokumentasi protokol penuh tersedia untuk rakan kongsi berdaftar. Hubungi wakil perniagaan Connection anda atau hubungi developer@connectionbadge.com untuk meminta akses kepada rujukan arahan CBBP yang lengkap, termasuk skema permintaan/respons penuh, kod ralat dan panduan integrasi.
Mesej Perintah
{
  "command": "command_name",
  "object": {
    // optional command parameters
  }
}
Mesej Keputusan
{
  "result": 0,          // 0 = success, -1 = error
  "detail": "ok",      // human-readable status
  "object": {          // optional response data
    // command-specific fields
  }
}

Pengangkutan

Mesej CBBP boleh dihantar ke lencana melalui tiga pengangkutan berbeza bergantung pada seni bina integrasi anda.

Bluetooth (Aplikasi)

Hantar arahan CBBP terus daripada aplikasi mudah alih melalui BLE. Memerlukan peranti yang dipasangkan dan dalam julat.

SDK Mudah Alih

WiFi atau Bluetooth melalui Pelayan

Proksi CBBP melalui REST API — POST /devices//cbbp. Pelayan akan menghala ke peranti secara automatik melalui WiFi atau Bluetooth bergantung pada cara lencana disambungkan. Paling biasa untuk integrasi bahagian belakang.

API REST

Penghantaran Dalaman

Penghantaran CBBP pada peranti atau antara proses. Digunakan oleh firmware lencana untuk menghalakan arahan antara subsistem dalaman.

Firmware Sahaja

Perintah Kuasa

Kawal keadaan kuasa peranti — tidur, bangun, but semula dan tetapan semula kilang.

PowerRebootBut semula peranti dengan segera.
PowerDeepsleepMasuk ke mod tidur nyenyak (kuasa rendah).
FactoryResetPadam semua konfigurasi dan tetapkan semula kepada tetapan lalai kilang.

Perintah WiFi

Konfigurasikan rangkaian tanpa wayar, imbas AP, semak status sambungan dan uruskan kelayakan yang disimpan.

WiFiScanImbas titik akses WiFi yang tersedia.
WiFiAPTestUji kesambungan ke titik akses WiFi tertentu.
WiFiAPJoinSertai titik akses WiFi dengan kelayakan yang diberikan.

Perintah Bluetooth

Kawal pengiklanan BLE, pasangan dan komunikasi lencana-ke-lencana.

BTScanBTImbas untuk peranti Bluetooth klasik.
BTScanBLEImbas peranti BLE.
DeviceBLEServiceAvailableTandakan perkhidmatan BLE sebagai tersedia.
DeviceBLEServiceUnavailableTandakan perkhidmatan BLE sebagai tidak tersedia.
DeviceBLEActiveTetapkan radio BLE kepada keadaan aktif.
DeviceBLEIdleTetapkan radio BLE kepada keadaan melahu.
DeviceBLEAdvChannelAddTambahkan saluran pada muatan pengiklanan BLE.
DeviceBTScanMulakan imbasan peranti Bluetooth.
DeviceBTA2DStartMulakan penstriman audio Bluetooth A2DP.
DeviceBTA2DEndTamatkan penstriman audio Bluetooth A2DP.
DeviceBTNativeAssistStartMulakan pembantu suara Bluetooth asli.
DeviceBTNativeAssistEndTamatkan pembantu suara Bluetooth asli.

Perintah Tetapan

Baca dan tulis konfigurasi peranti — nama paparan, zon waktu, bahasa dan bendera ciri.

SettingsListGetDapatkan semua tetapan sebagai senarai nilai kunci.
SettingsListSetTulis berbilang nilai tetapan sekaligus.
SettingsGetDapatkan nilai bagi satu tetapan dengan kekunci.
SettingsSetTetapkan nilai bagi satu tetapan sahaja.
SettingsSendTolak tetapan semasa ke pelayan.
SettingsClearKosongkan nilai tetapan tertentu.
SettingsErasePadam semua tetapan yang disimpan.

Perintah Firmware

Cetuskan kemas kini perisian tegar OTA, semak status kemas kini dan tanyakan versi perisian tegar semasa pada peranti.

FirmwareCheckSemak sama ada kemas kini perisian tegar tersedia.
FirmwareUpdateMulakan kemas kini perisian tegar OTA.
FirmwareValidateSahkan integriti imej perisian tegar yang dimuat turun.

Perintah Peranti

Kitaran hayat peranti, pengesahan, konfigurasi, pengelogan, status dan kawalan perkakasan.

NoOpTiada operasi / kekal hidup.
TestUjian ketersambungan asas.
DeviceDateTimeDapatkan atau tetapkan tarikh dan masa peranti.
DeviceAuthenticateSahkan peranti dengan pelayan.
DeviceConfigureGunakan muatan konfigurasi pada peranti.
DevicePostConnectionTasksJalankan tugas permulaan pasca sambungan.
DeviceStorageLoadMuatkan data daripada storan pada peranti.
DeviceLoadCustomAudioMuatkan fail audio tersuai ke peranti.
DeviceCoredumpSendMuat naik dump teras ranap ke pelayan.
DeviceAttachLampirkan peranti ke sesi pelayan.
DeviceDetachTanggalkan peranti daripada sesi pelayan.
DeviceLogSendMuat naik log peranti ke pelayan.
DeviceConnectionTestUji kesambungan pelayan.
DeviceStatusSendTolak status peranti ke pelayan.
DeviceStatusGetDapatkan status peranti semasa.
DeviceInteractionCetuskan peristiwa interaksi peranti.
DeviceSetAPIHostTetapkan hos pelayan API.
DeviceTestMicsJalankan ujian kendiri mikrofon.
HardwareI2CCommandHantar arahan I2C mentah ke peranti persisian perkakasan.

Perintah Komunikasi

Mulakan panggilan, hantar mesej, uruskan sesi komunikasi aktif dan kawal rakaman.

CommunicateChannelJoinSertai saluran komunikasi.
CommunicateChannelLeaveTinggalkan saluran komunikasi.
CommunicateChannelChangeTukar ke saluran lain.
CommunicateChannelCloseTutup saluran komunikasi.
CommunicateReceiveIncomingMaklumkan peranti tentang komunikasi masuk.
CommunicateRequestOutgoingMinta komunikasi keluar.
CommunicateVCPActivateAktifkan sesi Protokol Komunikasi Suara.
CommunicateVCPDeactivateNyahaktifkan sesi VCP.
CommunicateRecordingActivateMula merakam komunikasi aktif.
CommunicateIncomingAcceptTerima panggilan masuk.
CommunicateIncomingRejectTolak panggilan masuk.
CommunicateHFPCallStartMulakan panggilan telefon Bluetooth HFP.
CommunicateHFPCallEndTamatkan panggilan telefon Bluetooth HFP.
CommunicateContentStartMulakan penstriman kandungan audio ke peranti.
CommunicateContentStopHentikan penstriman kandungan audio.
SocketReceiveStatusTerima kemas kini status WebSocket.

Perintah Audio

Kawal kelantangan pembesar suara, penguatan mikrofon, profil audio dan main balik teks-ke-pertuturan.

AudioPlayStorageMainkan fail audio daripada storan pada peranti.
AudioPlayContentMainkan kandungan audio yang distrim.
AudioSetVolumeTetapkan kelantangan output pembesar suara.

Perintah LED

Tetapkan warna LED, kecerahan dan corak animasi pada lampu penunjuk lencana.

DeviceIlluminationSetTetapkan warna dan corak pencahayaan LED.

Perintah Dalaman

Arahan penghantaran dalaman yang digunakan untuk penghantaran konteks, sejarah saluran, penyuaraan dan penyahkodan audio.

InternalSendContextHantar data konteks kepada pengendali konteks dalaman.
InternalSendChannelHistoryHantar sejarah saluran kepada pengendali dalaman.
InternalRequestVocalizationMinta penyuaraan teks-ke-pertuturan secara dalaman.
InternalHandleVocalizationRTPKendalikan strim RTP penyuaraan masuk.
InternalDecodeAudioNyahkod strim audio masuk.

Perintah Mudah Alih

Perintah untuk menyelaraskan lencana dengan aplikasi mudah alih yang dipasangkan — pemberitahuan tolak, penyegerakan keadaan aplikasi dan pautan dalam.

MobileServiceStatusLaporkan status perkhidmatan mudah alih ke peranti. (Mudah Alih → Peranti)
MobileSocketOpenArahkan aplikasi mudah alih untuk membuka sambungan WebSocket. (Peranti → Mudah Alih)
MobileSocketCloseArahkan aplikasi mudah alih untuk menutup sambungan WebSocket. (Peranti → Mudah Alih)
MobileSocketStatusLaporkan status WebSocket ke aplikasi mudah alih. (Peranti → Mudah Alih)
MobileReceiveStatusLaporkan status penerimaan ke aplikasi mudah alih. (Peranti → Mudah Alih)
MobileSocketUpdateHantar kemas kini data WebSocket ke aplikasi mudah alih. (Peranti → Mudah Alih)
MobilePTTStartMaklumkan aplikasi mudah alih bahawa penghantaran PTT telah bermula. (Peranti → Mudah Alih)
MobilePTTStopMaklumkan aplikasi mudah alih bahawa penghantaran PTT telah tamat. (Peranti → Mudah Alih)
MobileContextSetTetapkan data konteks pada aplikasi mudah alih. (Peranti → Mudah Alih)
MobileEchoArahan Echo untuk menguji sambungan mudah alih. (Peranti → Mudah Alih)

Bersedia untuk membina?

Sertai komuniti pembangun Connection dan dapatkan akses kepada peranti kotak pasir, SDK dan sokongan khusus.

Hubungi Kami