認証
Connection APIはベアラートークン認証を使用します。すべてのリクエストには、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の概要
Connection Server REST APIは、デバイス群、通信インフラ、および分析機能への完全なプログラムアクセスを提供します。JSON形式のリクエスト/レスポンスボディを用いたRESTfulな規約に準拠しています。
認証
トークンベース認証。ログインするとトークンが返されます。このトークンは認証情報として送信する必要があります: トークン<token>以降のすべてのリクエストに対して。
ユーザー
ユーザーアカウントを作成および管理します。GET /users/userエンドポイントは、現在認証されているユーザーを返します。
デバイス
デバイスの一覧表示と検査、ユーザーとデバイスの関連付けの管理、デバイスごとの設定とステータスの読み書き、ファームウェアとストレージイメージの処理、ログとクラッシュレポートの受信を行います。
CBBPプロキシ
サーバー経由でデバイスにCBBPコマンドを送信します。サーバーはデバイスのWi-Fi接続を介してコマンドを中継し、デバイスからの応答を返します。送信するmake応答には、デバイスが即座に実行する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による要約を含む）にアクセスできます。複数の要約テンプレート（会議メモ、授業メモ、医療関連など）に対応し、要約音声の音声合成も可能です。
会話
ChatGPT、Gemini、またはネイティブエンジンを使用したAI搭載の会話セッション。複数のペルソナ（医師、家庭教師、整備士など）とページ分割されたメッセージ履歴をサポートします。
コンテンツ
デバイス上でストリーミングオーディオコンテンツを閲覧・再生できます。コンテンツはカテゴリツリーで整理されており、都市、地域、国で人気コンテンツを絞り込むことができます。
場所
地理座標を構造化された都市、地域、国オブジェクトに解決します。デバイスがコンテキストを取り込む際に使用されます。
プッシュ通知
FCMプッシュ通知を受信するには、モバイルアプリを登録してください。iOS、Android、およびWebに対応しています。
ストレージ
モデルオブジェクトに保存されているファイルをダウンロードし、画像の背景除去を実行します（結果はbase64エンコードされます）。
大量処理
複数のAPI操作を単一のHTTPリクエストで実行します。すべての操作を1つのアトミックトランザクションでラップするには、single_transaction=trueを渡します。いずれかの操作でエラーが発生すると、バッチ全体がロールバックされます。
日時
現在のサーバーの日時（GMT+0）を返します。認証は不要です。デバイスが内部時計を同期するために使用します。
通信バッジ基本プロトコル
CBBPは、コネクションバッジと直接やり取りするための軽量な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メッセージは、統合アーキテクチャに応じて、3つの異なるトランスポートを介してバッジに配信できます。
Bluetooth（アプリ）
モバイルアプリからBLE経由でCBBPコマンドを直接送信します。デバイスがペアリング済みで、通信範囲内にある必要があります。
モバイルSDKサーバー経由のWiFiまたはBluetooth
REST API を介して CBBP をプロキシします — POST /devices//cbbp。サーバーは、バッジの接続方法に応じて、WiFi または Bluetooth 経由でデバイスに自動的にルーティングします。バックエンド統合で最もよく使用されます。
REST API内部配車
デバイス内またはプロセス間CBBPディスパッチ。バッジファームウェアが内部サブシステム間でコマンドをルーティングするために使用します。
ファームウェアのみパワーコマンド
デバイスの電源状態（スリープ、ウェイクアップ、再起動、工場出荷時設定へのリセット）を制御します。
WiFiコマンド
無線ネットワークの設定、アクセスポイントのスキャン、接続状態の確認、保存済み認証情報の管理を行います。
Bluetoothコマンド
BLEの広告、ペアリング、およびバッジ間の通信を制御します。
設定コマンド
デバイス設定（表示名、タイムゾーン、言語、機能フラグなど）の読み書きを行います。
ファームウェアコマンド
OTAファームウェアアップデートをトリガーし、アップデート状況を確認し、デバイスの現在のファームウェアバージョンを照会します。
デバイスコマンド
デバイスのライフサイクル、認証、構成、ログ記録、ステータス、およびハードウェア制御。
通信コマンド
通話の開始、メッセージの送信、アクティブな通信セッションの管理、および録音の制御を行います。
音声コマンド
スピーカーの音量、マイクのゲイン、オーディオプロファイル、テキスト読み上げ再生を制御します。
LEDコマンド
バッジ表示灯のLEDの色、明るさ、アニメーションパターンを設定します。
内部コマンド
コンテキスト配信、チャネル履歴、音声生成、および音声デコードに使用される内部ディスパッチコマンド。
モバイルコマンド
バッジとペアリングされたモバイルアプリを連携させるためのコマンド（プッシュ通知、アプリの状態同期、ディープリンクなど）。