입증
Connection API는 Bearer 토큰 인증을 사용합니다. 모든 요청에는 Authorization 헤더에 유효한 JWT 액세스 토큰이 포함되어야 합니다.
토큰을 획득하세요
인증 엔드포인트로 자격 증명을 POST 방식으로 전송하세요. 그러면 단기 액세스 토큰과 장기 갱신 토큰을 받게 됩니다.
토큰을 사용하세요
모든 요청에 토큰을 포함하세요:
{
"email": "admin@yourorg.com",
"password": "••••••••"
}{
"access_token": "eyJhbG...",
"refresh_token": "dGhpcw...",
"expires_in": 3600,
"token_type": "Bearer"
}기본 URL 및 버전 관리
모든 API 엔드포인트는 /api/v1/ 아래에 버전이 지정되어 있습니다. 기본 URL은 배포 환경에 따라 다릅니다.
클라우드 호스팅 배포의 경우 조직에 할당된 지역 엔드포인트를 사용하십시오. 온프레미스 서버 배포의 경우 서버 호스트 이름을 사용하십시오.
| 환경 | 기본 URL |
|---|---|
| 클라우드(미국) | https://beta.connection.app/api/v1 |
| 구내 | https://<your-server>/api/v1 |
모든 요청 및 응답 본문은 application/json 형식을 사용합니다. 본문이 있는 요청에는 Content-Type: application/json을 포함하십시오.
오류 및 상태 코드
이 API는 표준 HTTP 상태 코드를 사용합니다. 오류 응답에는 기계가 읽을 수 있는 코드와 사람이 읽을 수 있는 메시지가 포함됩니다.
| 상태 | 의미 |
|---|---|
| 200 | 성공 |
| 201 | 생성됨 |
| 400 | 잘못된 요청 — 잘못된 매개변수 |
| 401 | 권한 없음 — 토큰이 없거나 만료되었습니다 |
| 403 | 접근 금지 — 권한 부족 |
| 404 | 찾을 수 없음 |
| 500 | 내부 서버 오류 |
{
"error": {
"code": "device_not_found",
"message": "No device with that UUID exists in your organization",
"status": 404
}
}REST API 개요
연결 서버 REST API는 디바이스 플릿, 통신 인프라 및 분석 기능에 대한 완벽한 프로그래밍 방식 액세스를 제공합니다. 이 API는 JSON 형식의 요청/응답 본문을 사용하는 RESTful 규칙을 따릅니다.
입증
토큰 기반 인증입니다. 로그인 시 토큰이 반환되며, 이 토큰은 인증: 토큰 형식으로 전송해야 합니다.<token> 이후의 모든 요청에 대해.
사용자
사용자 계정을 생성하고 관리합니다. GET /users/user 엔드포인트는 현재 인증된 사용자를 반환합니다.
기기
장치 목록을 표시하고 검사하고, 사용자-장치 연결을 관리하고, 장치별 설정 및 상태를 읽고 쓰고, 펌웨어 및 저장소 이미지를 처리하고, 로그 및 충돌 보고서를 수신할 수 있습니다.
CBBP 프록시
서버를 통해 기기에 CBBP 명령을 전송합니다. 서버는 기기의 Wi-Fi 연결을 통해 명령을 중계하고 기기의 응답을 반환합니다. 전송 응답에는 기기가 즉시 실행하는 CBBPMessage도 포함됩니다.
요청 본문은 CBBP 명령 봉투입니다. 저장된 CBBPCommand 객체는 전달 상태(UNSET → SENT → RECEIVED 또는 TIMED_OUT)를 추적합니다.
{
"outgoingMessage": {
"command": "WiFiScan"
}
}{
"uuid": "a3f2...",
"status": "SENT",
"device": "d7f3a1b2-...",
"dateSent": "2025-09-15T14:22:01Z",
"outgoingMessage": { /* echoed */ },
"incomingMessage": null
}채널
채널은 핵심적인 통신 기본 요소입니다. 채널 유형에는 ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService 및 ChannelRecorder가 있습니다.
의사소통
활성 통신 세션(발신 통화, VCP, 녹음 및 콘텐츠 스트리밍)을 시작하고 관리합니다. 발신 통화 응답에는 기기가 즉시 처리하는 CBBPMessage가 포함됩니다.
오디오 브리지
전체 녹취록, 참가자 목록, AI 기반 요약을 포함한 브리지 회의 대화 내용을 확인할 수 있습니다. 다양한 요약 템플릿(회의록, 수업록, 의료 관련 내용 등)을 지원하며, 요약 내용을 텍스트 음성 변환(TTS)으로 불러올 수 있습니다.
대화
ChatGPT, Gemini 또는 자체 엔진을 사용하는 AI 기반 대화 세션입니다. 다양한 직업군(의사, 과외 선생님, 정비사 등)을 지원하며, 메시지 기록을 페이지별로 볼 수 있습니다.
콘텐츠
다양한 기기에서 스트리밍 오디오 콘텐츠를 검색하고 재생하세요. 콘텐츠는 카테고리 트리 구조로 정리되어 있으며, 인기 콘텐츠는 도시, 지역 또는 국가별로 필터링할 수 있습니다.
위치
지리적 좌표를 도시, 지역 및 국가 객체로 변환합니다. 기기에서 컨텍스트 정보를 수집할 때 사용됩니다.
푸시 알림
FCM 푸시 알림을 수신하려면 모바일 앱을 등록하세요. iOS, Android 및 웹을 지원합니다.
저장
모델 객체에 저장된 파일을 다운로드하고 이미지 배경 제거를 실행합니다(결과는 base64로 인코딩됩니다).
대량 작업
단일 HTTP 요청으로 여러 API 작업을 실행할 수 있습니다. single_transaction=true를 전달하면 모든 작업이 하나의 원자적 트랜잭션으로 묶입니다. 어느 한 항목에서 오류가 발생하면 전체 배치가 롤백됩니다.
날짜 및 시간
현재 서버 날짜와 시간을 GMT+0 기준으로 반환합니다. 인증이 필요하지 않습니다. 기기에서 내부 시계를 동기화하는 데 사용됩니다.
Com 배지 기본 프로토콜
CBBP는 Connection 배지와 직접 상호 작용하기 위한 경량 JSON 명령 프로토콜입니다. 이를 통해 장치의 모든 하드웨어 및 소프트웨어 기능을 완벽하게 제어할 수 있습니다.
메시지 형식
모든 CBBP 상호 작용은 장치로 전송되는 명령 메시지와 장치에서 반환되는 결과 메시지로 구성됩니다.
요청과 응답 모두에서 객체 필드는 명령별 데이터를 담고 있으며, 필요하지 않을 경우 생략할 수 있습니다.
{
"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
}
}수송
CBBP 메시지는 통합 아키텍처에 따라 세 가지 서로 다른 전송 방식을 통해 배지로 전달될 수 있습니다.
블루투스(앱)
모바일 앱에서 BLE를 통해 CBBP 명령을 직접 전송할 수 있습니다. 기기가 페어링되어 있고 범위 내에 있어야 합니다.
모바일 SDK서버를 통한 WiFi 또는 Bluetooth
REST API를 통해 CBBP에 프록시 요청을 보냅니다. 요청 주소는 POST /devices//cbbp입니다. 서버는 배지의 연결 방식에 따라 Wi-Fi 또는 Bluetooth를 통해 자동으로 장치로 연결합니다. 주로 백엔드 통합에 사용됩니다.
REST API내부 배송
기기 내 또는 프로세스 간 CBBP 디스패치. 배지 펌웨어에서 내부 하위 시스템 간 명령을 라우팅하는 데 사용됩니다.
펌웨어 전용파워 커맨드
기기의 전원 상태 제어 - 절전, 절전 해제, 재부팅 및 공장 초기화.
와이파이 명령어
무선 네트워크를 구성하고, AP를 검색하고, 연결 상태를 확인하고, 저장된 자격 증명을 관리할 수 있습니다.
블루투스 명령
BLE 광고, 페어링 및 배지 간 통신을 제어합니다.
설정 명령
장치 구성(표시 이름, 시간대, 언어 및 기능 플래그)을 읽고 쓸 수 있습니다.
펌웨어 명령
OTA 펌웨어 업데이트를 시작하고, 업데이트 상태를 확인하고, 기기의 현재 펌웨어 버전을 조회할 수 있습니다.
장치 명령
장치 수명 주기, 인증, 구성, 로깅, 상태 및 하드웨어 제어.
통신 명령
통화 시작, 메시지 전송, 활성 통신 세션 관리 및 녹음 제어 기능을 제공합니다.
음성 명령
스피커 볼륨, 마이크 게인, 오디오 프로필 및 텍스트 음성 변환 재생을 제어합니다.
LED 명령
배지 표시등의 LED 색상, 밝기 및 애니메이션 패턴을 설정합니다.
내부 명령
컨텍스트 전달, 채널 기록, 음성 인식 및 오디오 디코딩에 사용되는 내부 디스패치 명령입니다.
모바일 명령
배지를 연동된 모바일 앱과 연동하기 위한 명령어 - 푸시 알림, 앱 상태 동기화 및 딥 링크.