Pagpapatotoo
Gumagamit ang Connection API ng Bearer token authentication. Dapat magsama ang lahat ng kahilingan ng wastong JWT access token sa header ng Authorization.
Kumuha ng token
I-POST ang iyong mga kredensyal sa auth endpoint. Makakatanggap ka ng panandaliang access_token at mas mahabang refresh_token.
Gamitin ang token
Isama ang token sa bawat kahilingan:
{
"email": "admin@yourorg.com",
"password": "••••••••"
}{
"access_token": "eyJhbG...",
"refresh_token": "dGhpcw...",
"expires_in": 3600,
"token_type": "Bearer"
}Base URL at Pag-bersyon
Ang lahat ng API endpoint ay naka-bersyon sa ilalim ng /api/v1/. Ang base URL ay nakadepende sa iyong deployment.
Para sa mga cloud-hosted deployment, gamitin ang regional endpoint na nakatalaga sa iyong organisasyon. Para sa mga on-premises na Server deployment, gamitin ang hostname ng iyong server.
| Kapaligiran | Batayang URL |
|---|---|
| Cloud (US) | https://beta.connection.app/api/v1 |
| Nasa Loob ng Lugar | https://<your-server>/api/v1 |
Lahat ng katawan ng kahilingan at tugon ay gumagamit ng application/json. Isama ang Content-Type: application/json sa mga kahilingang may katawan.
Mga Error at Status Code
Gumagamit ang API ng mga karaniwang HTTP status code. Kasama sa mga tugon sa error ang isang machine-readable code at mensaheng nababasa ng tao.
| Katayuan | Kahulugan |
|---|---|
| 200 | Tagumpay |
| 201 | Nilikha |
| 400 | Masamang Kahilingan — mga hindi wastong parameter |
| 401 | Hindi awtorisado — nawawala o nag-expire na ang token |
| 403 | Bawal — hindi sapat ang mga pahintulot |
| 404 | Hindi Natagpuan |
| 500 | Error sa Panloob na Server |
{
"error": {
"code": "device_not_found",
"message": "No device with that UUID exists in your organization",
"status": 404
}
}Pangkalahatang-ideya ng REST API
Ang Connection Server REST API ay nagbibigay ng ganap na programmatic access sa iyong device fleet, communications infrastructure, at analytics. Sinusundan nito ang mga RESTful convention na may mga JSON request/response bodies.
Pagpapatotoo
Pagpapatotoo batay sa token. Ang pag-login ay nagbabalik ng token na dapat ipadala bilang Awtorisasyon: Token<token> sa lahat ng kasunod na kahilingan.
Mga Gumagamit
Gumawa at mamahala ng mga user account. Ang GET /users/user endpoint ay nagbabalik ng kasalukuyang na-authenticate na user.
Mga Kagamitan
Naglilista at nag-iinspeksyon ng mga device, namamahala sa mga kaugnayan ng user-device, nagbabasa at nagsusulat ng mga setting at status bawat device, nangangasiwa sa mga firmware at storage image, at tumatanggap ng mga log at ulat ng pag-crash.
Proxy ng CBBP
Magpadala ng anumang utos na CBBP sa isang device sa pamamagitan ng server. Ire-relay ng server ang utos sa pamamagitan ng koneksyon sa WiFi ng device at ibabalik ang tugon ng device. Ang tugon na outgoing-make ay nag-e-embed din ng isang CBBPMessage na agad na isinasagawa ng device.
Ang katawan ng kahilingan ay isang CBBP command envelope. Sinusubaybayan ng nakaimbak na CBBPCommand object ang katayuan ng paghahatid: UNSET → SENT → RECEIVED o TIMED_OUT.
{
"outgoingMessage": {
"command": "WiFiScan"
}
}{
"uuid": "a3f2...",
"status": "SENT",
"device": "d7f3a1b2-...",
"dateSent": "2025-09-15T14:22:01Z",
"outgoingMessage": { /* echoed */ },
"incomingMessage": null
}Mga Channel
Ang mga channel ang mga pangunahing primitibong pamamaraan ng komunikasyon. Kabilang sa mga uri nito ang ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService, at ChannelRecorder.
Komunikasyon
Simulan at pamahalaan ang mga aktibong sesyon ng komunikasyon — mga papalabas na tawag, VCP, pagre-record, at pag-stream ng nilalaman. Kasama sa tugon ng papalabas na tawag ang isang CBBPMessage na agad na kikilos ang device.
Tulay ng Audio
I-access ang mga naitalang bridge conversation kabilang ang mga kumpletong transcript, listahan ng mga kalahok, at mga buod na binuo ng AI. Sinusuportahan ang maraming template ng buod (mga tala ng pulong, mga tala sa klase, pangangalagang pangkalusugan, atbp.) at pagbuo ng TTS audio para sa mga buod.
Mga Pag-uusap
Mga sesyon ng pag-uusap na pinapagana ng AI gamit ang ChatGPT, Gemini, o ang native engine. Sinusuportahan ang maraming persona (Doktor, Tutor, Mekaniko, atbp.) at naka-painate na history ng mensahe.
Nilalaman
Mag-browse at magpatugtog ng streaming audio content sa mga device. Ang content ay nakaayos sa isang category tree; maaaring i-filter ang sikat na content ayon sa lungsod, rehiyon, o bansa.
Mga Lokasyon
Lutasin ang mga heograpikong coordinate sa isang nakabalangkas na bagay ng lungsod, rehiyon, at bansa. Ginagamit ng mga device kapag kumukuha ng konteksto.
Mga Push Notification
Magrehistro ng mobile app para makatanggap ng mga push notification ng FCM. Sinusuportahan ang iOS, Android, at mga web target.
Imbakan
Mag-download ng mga file na nakaimbak sa mga object ng modelo, at patakbuhin ang pag-alis ng background ng imahe (ibinabalik ang resultang naka-encode sa base64).
Mga Operasyong Maramihan
Magsagawa ng maraming operasyon ng API sa iisang HTTP request. Ipasa ang single_transaction=true upang ibalot ang lahat ng operasyon sa isang atomic transaction — ang isang pagkabigo sa anumang item ay magre-rollback sa buong batch.
Petsa at Oras
Ibinabalik ang kasalukuyang petsa at oras ng server sa GMT+0. Hindi nangangailangan ng pagpapatotoo. Ginagamit ng mga device upang i-sync ang kanilang internal na orasan.
Pangunahing Protokol ng Com Badge
Ang CBBP ay isang magaan na JSON command protocol para sa direktang pakikipag-ugnayan sa mga Connection badge. Binibigyan ka nito ng ganap na kontrol sa bawat function ng hardware at software sa device.
Format ng Mensahe
Ang bawat interaksyon ng CBBP ay binubuo ng isang mensahe ng utos na ipinapadala sa device at isang mensahe ng resulta na ibinalik ng device.
Ang object field sa parehong request at response ay naglalaman ng command-specific data at maaaring alisin kapag hindi kinakailangan.
{
"command": "command_name",
"object": {
// optional command parameters
}
}{
"result": 0, // 0 = success, -1 = error
"detail": "ok", // human-readable status
"object": { // optional response data
// command-specific fields
}
}Transportasyon
Maaaring ipadala ang mga mensahe ng CBBP sa isang badge sa pamamagitan ng tatlong magkakaibang transportasyon depende sa arkitektura ng iyong integrasyon.
Bluetooth (App)
Magpadala ng mga CBBP command nang direkta mula sa isang mobile app sa pamamagitan ng BLE. Kinakailangan na ang device ay naka-pair at nasa loob ng saklaw.
Mobile SDKWiFi o Bluetooth sa pamamagitan ng Server
Proxy CBBP sa pamamagitan ng REST API — POST /devices//cbbp. Awtomatikong nagruruta ang server papunta sa device sa pamamagitan ng WiFi o Bluetooth depende sa kung paano nakakonekta ang badge. Pinakakaraniwan para sa mga backend integration.
REST APIPanloob na Pagpapadala
Pagpapadala ng CBBP sa device o sa pagitan ng mga proseso. Ginagamit ng firmware ng badge upang iruta ang mga command sa pagitan ng mga internal na subsystem.
Firmware LamangMga Utos ng Kapangyarihan
Kontrolin ang estado ng kuryente ng device — sleep, wake, reboot, at factory reset.
Mga Utos sa WiFi
I-configure ang mga wireless network, i-scan para sa mga AP, suriin ang katayuan ng koneksyon, at pamahalaan ang mga naka-save na kredensyal.
Mga Utos ng Bluetooth
Kontrolin ang BLE advertising, pagpapares, at komunikasyon sa pagitan ng badge at badge.
Mga Utos sa Setting
Basahin at isulat ang configuration ng device — pangalan ng display, time zone, wika, at mga flag ng feature.
Mga Utos ng Firmware
I-trigger ang mga OTA firmware update, tingnan ang status ng update, at i-query ang kasalukuyang bersyon ng firmware sa device.
Mga Utos ng Device
Ikot ng buhay ng device, pagpapatotoo, configuration, pag-log, status, at kontrol sa hardware.
Mga Utos sa Komunikasyon
Magsimula ng mga tawag, magpadala ng mga mensahe, pamahalaan ang mga aktibong sesyon ng komunikasyon, at kontrolin ang pagre-record.
Mga Utos sa Audio
Kontrolin ang volume ng speaker, microphone gain, mga audio profile, at text-to-speech playback.
Mga Utos ng LED
Itakda ang kulay, liwanag, at mga pattern ng animation ng LED sa indicator light ng badge.
Mga Panloob na Utos
Mga panloob na utos sa pagpapadala na ginagamit para sa paghahatid ng konteksto, kasaysayan ng channel, vocalization, at audio decoding.
Mga Utos sa Mobile
Mga utos para sa pag-coordinate ng badge sa isang nakapares na mobile app — mga push notification, pag-sync ng estado ng app, at deep linking.