メインコンテンツまでスキップ
API docs by Redocly

CWS API Notifications (1.0)

Download OpenAPI specification:Download

CWS APIより外部システムに通知するWebhookを定義します。

Webhookの通知先は通知・アクセス設定で指定してください。

authenticationKeyの利用方法

安全にご利用いただくために、Webhookの送信元がCWS APIであることを、ご確認いただくことを推奨します。

送信元の検証を実施いただけるように、CWS APIでは、Webhookの送信の際に、HMAC SHA256ハッシュのhexdigestをHTTP Headerに付与しています。

ハッシュは、authenticationKeyを発行するで発行したauthenticationKeyと、Webhookで送信するHTTP Request Bodyの値により生成しています。

Webhookを受信した際に、CWS APIと同じ方法で生成したハッシュと比較することで、送信元がCWS APIであることをご検証いただけます。

送信元検証のサンプルプログラム

Webhookを受信するFlaskアプリケーションで、送信元の検証を実施するサンプルプログラムを、以下に例示します。

import hmac
import hashlib
from flask import Flask, request, abort, jsonify


app = Flask(__name__)


@app.route('/device-event', methods=['GET', 'POST'])
def device_event():
    if request.method == 'GET':
        return abort(403)

    key = get_authentication_key()
    data = request.data.decode('utf-8')

    hash = get_hmac_hash_hexdigest(key, data)

    if hash != request.headers.get('X-TLPF-NOTIFICATION-KEY'):
        return abort(403)

    return jsonify(None)


def get_authentication_key():
    return 'CWS APIが発行した authenticationKey'


def get_hmac_hash_hexdigest(key, data):
    return hmac.new(
        bytearray(key, "ASCII"),
        bytearray(data, "ASCII"),
        hashlib.sha256,
    ).hexdigest()

上記プログラムは一例であるため、これによる問題が発生した場合の責任は負いかねます。

Device Event について

通知・アクセス設定で登録した「デバイスイベント通知先URLdeviceEvent」に対して、トランザクションの結果またはデバイス状態変更を通知します。

本通知は デバイスイベントの種別によって外部通知のリクエスト内容が変わります。そのため、本通知では デバイスイベント毎に表記しています。

トランザクション結果通知の再送について

CWSでは、端末がオンラインになった際、以下条件を全て満たすトランザクションを再送します。

上記に一致しない未処理のトランザクションは破棄します。 また、デバイスをディアクティベートするAPI、デバイスの初期化APIを実行した場合には、API実行前に発行した未処理のトランザクションを破棄します。

破棄した場合、その理由と共にトランザクション結果通知(破棄) を通知します。

Sora Event について

通知・アクセス設定で登録した「Soraイベント送信先URLsoraEvent」に対して Sora イベントを通知します。

本通知は Sora イベントの種別によって外部通知のリクエスト内容が変わります。

Device Event(transaction)

デバイスイベント通知(トランザクション結果)

トランザクション結果通知 Webhook

トランザクションの結果を通知します。

関連API

通知タイミング

デバイスで以下処理完了後に通知します

  • アクティベート
  • ディアクティベート
  • 初期化
  • Wifi設定
  • APN設定
  • 言語設定
  • LauncherAppへのKey設定
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

transactionId
required
integer

トランザクションID

operationId
required
string

トランザクション結果通知の種別となるオペレーションID。 オペレーションIDは、トランザクションを発行したCWS APIのAPI操作に応じて異なる値となっている。 APIとoperationIdの値の組み合わせは以下である。

notificationType
required
string

通知種別

  • accepted: デバイスでAPIの指示を受け付けた
  • processed: アップデート完了
result
required
string

トランザクション結果(success:成功, failure:失敗)

message
required
string

トランザクションの処理結果メッセージ。

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
Example
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "transactionId": 1,
  • "operationId": "post-v1-applications-devices",
  • "notificationType": "processed",
  • "result": "success",
  • "message": "",
  • "timestamp": "2020-10-16T00:37:08.260Z"
}

トランザクション結果通知(ソフトウェア/ファームウェアのアップデート) Webhook

トランザクションの結果(ソフトウェア/ファームウェアのアップデート)を通知する。

関連API

通知タイミング

  • デバイスで ソフトウェア/ファームウェア のアップデートを受け付けた
  • アップデート中に10秒間隔
  • アップデート完了
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

transactionId
required
integer

トランザクションID

operationId
required
string

トランザクション結果通知の種別となるオペレーションID。 オペレーションIDは、トランザクションを発行したCWS APIのAPI操作に応じて異なる値となっている。 APIとoperationIdの値の組み合わせは以下である。

notificationType
required
string

通知種別。通知タイミング毎に以下値となる。

  • accepted: デバイスで ソフトウェア/ファームウェア のアップデートを受け付けた
  • in_progress: アップデート中
  • processed: アップデート完了
result
required
string

トランザクション結果(success:成功, failure:失敗)

progress
number <float>

端末での、アップデート用データ（FW、アプリ）のダウンロード進捗率（0.0〜1.0） この項目は、MDM v0.6.21 以降を使用する場合に存在します。

進捗率は以下のnotificationTypeと値のパターンで通知します

  • notificationType: accepted
    • 0.0
  • notificationType: in_progress
    • 0.0〜1.0(ダウンロード進捗率)
  • notificationType: processed
    • 0.0
      • 本システムにおいて、ダウンロード前のインストール・アップデート要求受付時に不正なメッセージと判断した場合
    • 1.0
      • ダウンロード失敗時
      • ダウンロード完了後、インストール・アップデート要求の発行に失敗した場合
message
required
string

トランザクションの処理結果メッセージ。

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
Example
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "transactionId": 1,
  • "operationId": "put-v1-applications-devices-apps",
  • "notificationType": "accepted",
  • "result": "success",
  • "progress": 0,
  • "message": "message accepted.",
  • "timestamp": "2020-10-16T00:37:08.260Z"
}

トランザクション結果通知(コマンド実行) Webhook

トランザクションの結果(コマンド実行)を通知します

関連API

通知タイミング

  • 端末内連携先アプリの呼出後
    • CWS APIはコマンド通知先である端末内連携先アプリの呼出結果を1度目に通知します
  • 端末内連携先アプリからの応答受信後
    • CWS APIは端末内連携先アプリでの処理結果を2度目に通知します

特記事項

  • 1度目の通知のsuccessは、端末内連携先アプリの呼出に対する成功、失敗を表します
  • 2度目の通知のsuccessは、端末内連携先アプリでの処理結果の成功、失敗を表します
  • customDataは、ユーザ独自の端末内連携先アプリで任意に定義することができます
  • 2度目の通知は、ユーザ独自の端末内連携先アプリがMDMアプリに対して結果を戻すことで通知されます
    • 連携情報を記載したmd ファイルはご希望の方に都度共有を行なっております。ご希望の方は FairyDevices にお問い合わせください。
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

transactionId
required
integer

トランザクションID

operationId
required
string

トランザクション結果通知の種別となるオペレーションID。 オペレーションIDは、トランザクションを発行したCWS APIのAPI操作に応じて異なる値となっている。 APIとoperationIdの値の組み合わせは以下である。

success
required
boolean

コマンド実行結果(true:成功, false:失敗)

process
required
string

processed(固定値)

message
required
string

トランザクションの処理結果メッセージ。

customData
required
string
Default: ""

端末内連携先アプリからの送信データ（任意項目）
送信データがない場合は、空文字列（””）が設定される

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
Example
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "transactionId": 1,
  • "operationId": "put-v1-applications-devices-commands",
  • "success": true,
  • "process": "processed",
  • "message": "called app.",
  • "customData": "",
  • "timestamp": "2020-10-16T00:37:08.260Z"
}

トランザクション結果通知(Bluetoothデバイス/ネットワークの一覧を取得) Webhook

トランザクションの結果(Bluetoothデバイス/ネットワークの一覧を取得)を通知する。

関連API

通知タイミング

デバイスで以下処理完了後に通知します

  • Bluetoothデバイスの一覧を取得
  • ネットワークの一覧を取得
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

transactionId
required
integer

トランザクションID

operationId
required
string

トランザクション結果通知の種別となるオペレーションID。 オペレーションIDは、トランザクションを発行したCWS APIのAPI操作に応じて異なる値となっている。 APIとoperationIdの値の組み合わせは以下である。

message
string

メッセージ

networkType
required
string
Enum: "bluetooth" "wifi" "apn"

通知内容の種類

target
required
string
Enum: "all" "connected" "available"

Bluetoothデバイス/ネットワーク の取得対象。 Bluetoothデバイス/ネットワークの一覧を取得する で指定したtarget。
targetの詳細は以下。

  • all: Bluetoothデバイス/ネットワークの一覧を取得するAPIの要求を受け付けた時点で、THINKLETに登録済み(接続中含む) および 検出可能なBluetoothデバイス/ネットワーク
  • connected: Bluetoothデバイス/ネットワークの一覧を取得するAPIの要求を受け付けた時点で、THINKLETに接続中のBluetoothデバイス/ネットワーク
  • available: Bluetoothデバイス/ネットワークの一覧を取得するAPIの要求を受け付けた時点で、THINKLETに登録済み(接続中含む)のBluetoothデバイス/ネットワーク
statusCode
required
integer
Enum: 200 403 500

実行結果コード

Array of objects (TransactionConnectivityDeviceInfo)

Bluetoothデバイスの情報の一覧。networkTypeがbluetoothの場合のみ存在する。

Array of objects (TransactionConnectivityNetworkInfo)

ネットワーク情報の一覧。networkTypeがwifi,apnの場合のみ存在する。

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "transactionId": 1,
  • "operationId": "get-v1-applications-connectivity-list",
  • "message": "",
  • "networkType": "bluetooth",
  • "target": "available",
  • "statusCode": 200,
  • "devices": [
    ],
  • "timestamp": "2020-10-16T00:37:48.771Z"
}

トランザクション結果通知(Bluetooth/ネットワークのON/OFF状態を取得、変更する) Webhook

トランザクションの結果(Bluetooth/ネットワークのON/OFF状態を取得、変更)を通知する。

関連API

通知タイミング

デバイスで以下処理完了後に通知します

  • BluetoothのON/OFF状態を取得
  • BluetoothのON/OFFの切り替え
  • ネットワークのON/OFF状態を取得
  • ネットワークのON/OFFの切り替え
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

transactionId
required
integer

トランザクションID

operationId
required
string

トランザクション結果通知の種別となるオペレーションID。 オペレーションIDは、トランザクションを発行したCWS APIのAPI操作に応じて異なる値となっている。 APIとoperationIdの値の組み合わせは以下である。

message
string

メッセージ

networkType
required
string
Enum: "bluetooth" "wifi" "mobile"

通知内容の種類

statusCode
required
integer
Enum: 200 400 500

実行結果コード

state
required
string
Enum: "enabled" "disabled" "unknown"

ONOFFの状態

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "transactionId": 1,
  • "operationId": "put-v1-applications-connectivity-state",
  • "message": "",
  • "networkType": "bluetooth",
  • "statusCode": 200,
  • "state": "enabled",
  • "timestamp": "2020-10-16T00:37:48.771Z"
}

トランザクション結果通知(Bluetooth/ネットワークの設定を初期化する) Webhook

トランザクションの結果(Bluetooth/ネットワークの設定を初期化)を通知する。

関連API

通知タイミング

デバイスで以下処理完了後に通知します

  • Bluetoothの初期化
  • ネットワークの初期化
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

transactionId
required
integer

トランザクションID

operationId
required
string

トランザクション結果通知の種別となるオペレーションID。 オペレーションIDは、トランザクションを発行したCWS APIのAPI操作に応じて異なる値となっている。 APIとoperationIdの値の組み合わせは以下である。

message
string

メッセージ

networkType
required
string
Enum: "bluetooth" "wifi" "mobile"

通知内容の種類

statusCode
required
integer
Enum: 200 500

実行結果コード

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "transactionId": 1,
  • "operationId": "delete-v1-applications-connectivity-reset",
  • "message": "",
  • "networkType": "bluetooth",
  • "statusCode": 200,
  • "timestamp": "2020-10-16T00:37:48.771Z"
}

トランザクション結果通知(Bluetoothペアリング) Webhook

以下トランザクションの結果を通知する。

  • Bluetoothデバイスのペアリングを行う
  • ペアリング済みBluetoothデバイスを接続/切断する
  • Bluetoothデバイスのペアリングを解除する

関連API

通知タイミング

デバイスで以下処理完了後に通知します

  • Bluetoothデバイスのペアリング
  • Bluetoothデバイスのペアリングを解除
  • Bluetoothデバイスの接続
  • Bluetoothデバイスの切断
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

transactionId
required
integer

トランザクションID

operationId
required
string

トランザクション結果通知の種別となるオペレーションID。 オペレーションIDは、トランザクションを発行したCWS APIのAPI操作に応じて異なる値となっている。 APIとoperationIdの値の組み合わせは以下である。

message
string

メッセージ

networkType
required
string
Value: "bluetooth"

通知内容の種類

statusCode
required
integer
Enum: 200 400 403 404 409 500

実行結果コード

required
Array of objects (TransactionBluetoothDeviceInfo)

デバイスの情報

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "transactionId": 1,
  • "operationId": "put-v1-applications-bluetooth-device",
  • "message": "",
  • "networkType": "bluetooth",
  • "statusCode": 200,
  • "devices": [
    ],
  • "timestamp": "2020-10-16T00:37:48.771Z"
}

トランザクション結果通知(トランザクションの破棄) Webhook

破棄したトランザクションを通知します。

トランザクションが破棄される条件に関しては、トランザクション結果通知の再送について を参照してください。

通知タイミング

デバイスがオンラインになった際

Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

transactionId
required
integer

トランザクションID

operationId
required
string

トランザクション結果通知の種別となるオペレーションID。 オペレーションIDは、トランザクションを発行したCWS APIのAPI操作に応じて異なる値となっている。

notificationType
required
string

通知種別

  • accepted: デバイスでAPIの指示を受け付けた
result
required
string

トランザクション結果。必ず failure:失敗 となる。

message
required
string

トランザクションの処理結果メッセージ。

端末がオンラインになった際にCWSが破棄したトランザクションは、以下のメッセージを送信する。

  • 再送が一定回数を超えたトランザクション
    The transaction was canceled because the retry limit was exceeded.
  • 同一オペレーションIDの古いトランザクション
    The transaction was canceled because there is a new transaction.
  • デバイスをディアクティベートするAPI実行前に発行したトランザクション
    The transaction was canceled because it occurred before deactivation.
  • デバイスの初期化API実行前に発行したトランザクション
    The transaction was canceled because it occurred before reset.

Request samples

Content type
application/json
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "transactionId": 1,
  • "operationId": "put-v1-applications-devices-apps",
  • "notificationType": "accepted",
  • "result": "failure",
  • "message": "The transaction was canceled because the retry limit was exceeded."
}

Device Event(notify device state)

デバイスイベント通知(デバイス状態)

任意アプリからの任意文字列通知 Webhook

THINKLETデバイスへインストールしたユーザ独自の任意アプリから、任意の文字列を通知します

通知タイミング

  • MDMアプリが、任意文字列通知のBroadcast Intentを受信し、CWS APIへ接続可能となった時に通知します

特記事項

  • 本イベントは、ユーザ独自の任意アプリがMDMアプリに対して、任意文字列通知を要求することで通知されます
    • 連携情報を記載したmd ファイルはご希望の方に都度共有を行なっております。ご希望の方は FairyDevices にお問い合わせください。
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

operationId
required
string
Value: "notify-custom-data"

通知の種別となるオペレーションID

success
required
boolean
Default: false

任意アプリケーションからのBroadcast Intent連携時の指定Boolean値

message
required
string
Default: "notify ACTION_SEND_CUSTOM_DATA message."

処理結果メッセージ(固定値)

customData
required
string
Default: ""

任意アプリケーションからのBroadcast Intent連携時の指定送信データ（任意項目）
送信データがない場合は、空文字列（””）が設定される

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "operationId": "notify-custom-data",
  • "success": false,
  • "message": "notify ACTION_SEND_CUSTOM_DATA message.",
  • "customData": "",
  • "timestamp": "2020-10-16T00:37:08.260Z"
}

デバイス状態変更通知(端末起動状態) Webhook

デバイス状態変更(端末起動状態)を通知する。

通知タイミング

  • デバイス起動完了後に通知します
  • デバイス電源シャットダウン前に通知します
    • 電源ボタンからのシャットダウン要求時のみ
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

operationId
required
string
Value: "notify-app-status"

デバイス変更通知の種別となるオペレーションID

type
required
string

メッセージ種別。必ず app_status となります。

appType
required
string

メッセージ種別。必ず device となります。

appStatus
required
string

メッセージ種別。started/finished のどちらかとなります。

timestamp
required
string

イベント発生時のタイムスタンプ

text
required
string

デバイス変更通知で受け取った詳細を表す自由文字列

Request samples

Content type
application/json
Example
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "operationId": "notify-app-status",
  • "type": "app_status",
  • "appType": "device",
  • "appStatus": "started",
  • "timestamp": "2020-10-16T00:37:08.260Z",
  • "text": "device booted"
}

デバイス状態変更通知(端末装着状態) Webhook

デバイス状態変更(端末装着状態)を通知する。

通知タイミング

  • デバイスでの近接センサー値の変化時に通知します
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

operationId
required
string
Enum: "notify-battery-charging" "notify-device-wearing-status"

デバイス変更通知の種別となるオペレーションID

usage
required
string

端末で発生したイベント。 端末の装着状態の通知では、device_wear または device_takeoff、 端末の充電状態の通知では、start_charging または stop_charging となります。

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
Example
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "operationId": "notify-device-wearing-status",
  • "usage": "device_wear",
  • "timestamp": "2020-10-16T00:37:08.260Z"
}

デバイス状態変更通知(充電状態) Webhook

デバイス状態変更(充電状態)を通知する。

通知タイミング

  • デバイスでの充電状態の変化時に通知します
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

operationId
required
string
Enum: "notify-battery-charging" "notify-device-wearing-status"

デバイス変更通知の種別となるオペレーションID

usage
required
string

端末で発生したイベント。 端末の装着状態の通知では、device_wear または device_takeoff、 端末の充電状態の通知では、start_charging または stop_charging となります。

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
Example
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "operationId": "notify-battery-charging",
  • "usage": "start_charging",
  • "timestamp": "2020-10-16T00:37:08.260Z"
}

デバイス状態変更通知(ネットワーク状態) Webhook

デバイス状態変更(ネットワーク状態)を通知する。

通知タイミング

  • status: connectivity_online の通知は、ネットワークがオンラインになったときに通知します
  • status: connectivity_offline の通知は、ネットワークがオフラインになったときに通知します
  • デバイスがアクティベートされていない場合には、通知しません
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

operationId
required
string
Value: "notify-network-connection-status"

デバイス変更通知の種別となるオペレーションID

status
required
string

デバイスで発生したイベント種類。 ネットワーク状態の通知では、connectivity_online または connectivity_offline。

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
Example
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "operationId": "notify-network-connection-status",
  • "status": "connectivity_online",
  • "timestamp": "2020-10-16T00:37:48.771Z"
}

デバイス状態変更通知(バッテリー残量) Webhook

デバイス状態変更(バッテリー残量)を通知する。

通知タイミング

  • デバイスでのバッテリー残量(%)変化時に通知します
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

operationId
required
string
Value: "notify-battery-percentage-changed"

デバイス変更通知の種別となるオペレーションID

status
required
string

デバイス状態変更通知の種別。バッテリー残量通知では必ずbattery_changedとなります。

batteryPercentage
required
integer

バッテリー残量[%]

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "operationId": "notify-battery-percentage-changed",
  • "status": "battery_changed",
  • "batteryPercentage": 99,
  • "timestamp": "2020-10-16T00:37:48.771Z"
}

デバイス状態変更通知(位置情報) Webhook

デバイス状態変更(位置情報)を通知する。

通知タイミング

  • デバイスでの位置情報変化時に通知します
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

operationId
required
string
Value: "notify-location"

デバイス変更通知の種別となるオペレーションID

status
required
string

デバイス状態変更通知の種別。位置情報変更通知では必ずlocationとなります。

lat
required
string

位置情報変更通知の緯度

lon
required
string

位置情報変更通知の経度

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "operationId": "notify-location",
  • "status": "XXX.XXXXX",
  • "lat": "XXX.XXXXX",
  • "lon": "location",
  • "timestamp": "2020-10-16T00:37:48.771Z"
}

デバイス状態変更通知(電波状況変化) Webhook

デバイス状態変更(電波状況変化時)を通知する。

通知タイミング

  • デバイスでのネットワーク電波強度（Wi-Fi or mobile）変化時に通知します
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

operationId
required
string
Value: "notify-network-level"

デバイス変更通知の種別となるオペレーションID

status
required
string

デバイス状態変更通知の種別。電波状況変更通知では必ずnetwork_levelとなります。

networkType
required
string

電波状況変更通知のネットワーク種別。Wi-Fi もしくは mobile となります。

active
required
boolean

networkTypeで指定したnetworkを使用している場合は true となります。

networkName
string

電波状況が変化した対象のnetwork名（Wi-Fiの場合はSSID/mobileの場合はAPN名）

networkLevel
required
integer [ 0 .. 4 ]

電波状況変更通知のネットワークレベル

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "operationId": "notify-network-level",
  • "status": "network_level",
  • "networkType": "wifi",
  • "active": true,
  • "networkName": "SSID1234",
  • "networkLevel": 1,
  • "timestamp": "2020-10-16T00:37:48.771Z"
}

デバイス状態変更通知(音量変更) Webhook

デバイス状態変更(音量変更時)を通知する。

通知タイミング

  • デバイスでの音量変化時に通知します
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

operationId
required
string
Value: "notify-volume"

デバイス変更通知の種別となるオペレーションID

status
required
string

デバイス状態変更通知の種別。音量変更通知では必ずvolumeとなります。

volumeType
required
string

音量の種別。media固定

stream
required
string

端末で受け取ったVolumeStream。music 固定

min
required
integer

最小音量

max
required
integer

最大音量

current
required
integer

現在の音量

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "operationId": "notify-volume",
  • "status": "volume",
  • "volumeType": "media",
  • "stream": "music",
  • "min": 0,
  • "max": 16,
  • "current": 8,
  • "timestamp": "2020-10-16T00:37:48.771Z"
}

デバイス状態変更通知(Bluetoothデバイス接続/切断) Webhook

デバイス状態変更(Bluetoothデバイス接続/切断時)を通知する。

通知タイミング

  • Bluetoothデバイスに接続した
  • Bluetoothデバイスと切断した
Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
applicationId
required
string

アプリケーションID

deviceId
required
string

THINKLETのIMEI NO

transactionId
integer

トランザクションID

operationId
required
string
Value: "notify-bluetooth-connection"

デバイス変更通知の種別となるオペレーションID

message
string

メッセージ

networkType
required
string
Value: "bluetooth"

通知内容の種類

statusCode
required
integer
Enum: 200 500

実行結果コード

required
Array of objects (NotificationBluetoothDeviceInfo)

デバイスの情報

timestamp
required
string

イベント発生時のタイムスタンプ

Request samples

Content type
application/json
{
  • "applicationId": "abcdefghigklmnopqrstuvwxyz012345",
  • "deviceId": "123456789101234",
  • "transactionId": 1,
  • "operationId": "notify-bluetooth-connection",
  • "message": "",
  • "networkType": "bluetooth",
  • "statusCode": 200,
  • "devices": [
    ],
  • "timestamp": "2020-10-16T00:37:48.771Z"
}

Sora Event

Soraイベント通知

Soraイベント通知 Webhook

以下Sora のイベントを通知します。 Soraからのイベント通知をそのまま転送していますが、キー項目をスネークケースからキャメルケースに変換しています。

  • 接続通知 (connection.created)
  • 接続状態更新通知 (connection.updated)
  • 切断通知 (connection.destroyed)
  • 録画保存ファイル出力通知 (archive.available)
  • 録画ファイル保存失敗通知 (archive.failed)

各イベントの詳細は、WebRTC SFU Sora ドキュメントのイベントウェブフック を参照してください。

Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Sora Recorded Event

Sora録画イベント通知

録画データ通知 Webhook

通知・アクセス設定で登録した「Sora録画データ通知先URLsoraFileSendEvent」に対して、録画データ（録画ファイル、メタデータファイル）のアップロードが完了したことを通知します。

通知・アクセス設定にて「録画データ（Sora）用署名付きURL取得URLsoraRecGetPresignedUrl 」を登録した場合、当通知の受領時点で、Sora録画データのアップロードは完了しています。

通知・アクセス設定にて「録画データ（Sora）用署名付きURL取得URL（マルチパート対応）soraRecGetMultiPresignedUrl 」を登録した場合、当通知を受領後、マルチパートのファイルアップロードの完了処理を行ってください。

マルチパートのファイルアップロードの完了処理を実施後、アップロードしたファイルをAmazon S3で確認できます。

本通知には、アップロードに成功したファイルの情報のみ含まれます。アップロードに失敗したファイルの情報は、本通知には含まれません。

通知・アクセス設定で、「録画データ（Sora）用署名付きURL取得URLsoraRecGetPresignedUrl 」と「録画データ（Sora）用署名付きURL取得URL（マルチパート対応）soraRecGetMultiPresignedUrl 」の両方が登録されていた場合は、CWS APIでは、「録画データ（Sora）用署名付きURL取得URL（マルチパート対応）soraRecGetMultiPresignedUrl 」の設定を優先します。

Soraが提供している指定したチャネルの録画を停止するAPIを使用した際のドメインと、WebRTCエンドポイント取得で発行したエンドポイントのドメインが異なっていた場合、録画ファイルのアップロードは行われません。

また、「録画データ（Sora）用署名付きURL取得URLsoraRecGetPresignedUrl 」、「録画データ（Sora）用署名付きURL取得URL（マルチパート対応）soraRecGetMultiPresignedUrl 」からステータスコード:200 以外が返却された場合も、録画ファイルのアップロードは行われません。

Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
channel
required
object

チャネル

message
string

メッセージ

Request samples

Content type
application/json
Example
{
  • "channel": {
    }
}

File Upload Event

ファイルアップロードイベント通知

ファイルアップロードイベント通知 Webhook

ファイルアップロードの成功/失敗イベントを通知します。

本項での仕様は、下記へ設定されたURLが対象となります。

  • fileUploadEvent (ファイルアップロード用イベント通知先URL)

上記の設定、取得に関しては、CWS APIリファレンスの下記を参照ください。

Authorizations:
X-TLPF-NOTIFICATION-KEY
header Parameters
X-TLPF-NOTIFICATION-KEY
required
string

署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)

Request Body schema: application/json
result
string

アップロードの成功/失敗

  • success
  • failure
file
string

アップロードファイルのパス

（例 = '<利用者様アプリケーションID>/<利用者様端末のデバイスID>/upload_files/<任意のパス/ファイル名>'

message
string

アップロード結果に対するメッセージ

Responses

Request samples

Content type
application/json
Example
{
  • "result": "success",
  • "file": "<application_id>/<device_id>/upload_files/hogehoge.log",
  • "message": "upload complete"
}