logoドキュメント
WebPush
ドキュメントホーム
ユーザーガイド開発者ガイドベストプラクティス
検索
日本語
English
繁體中文
简体中文
日本語
ภาษาไทย
Español
ログイン
開発者ガイド / REST API / コールバック API

Callback API

最新更新：2025-07-22

概要

メッセージ状態データは企業の業務システムにコールバックされ、この情報に基づいて統計分析を行うことができます。

コールバックアドレス

企業はメッセージ状態の変更を受信するためのコールバックアドレスを設定する必要があります。現在、Webインターフェースは提供されていません。Engagelabの技術担当者に連絡してコールバックアドレスを設定してください。

コールバックアドレスの有効性検証

アプリケーション設定の下にあるプッシュバックエンド管理でコールバックアドレスを構成するとき、ランダムに生成された8文字の文字列がechostrリクエストボディパラメータとして送信されるPOSTリクエストが行われます。以下の形式に従って、レスポンスボディにechostrの値を返す必要があります：

リクエストボディ：

{ "echostr": "12345678" }
              
              {
    "echostr": "12345678"
}
このコードブロックはフローティングウィンドウ内に表示されます

レスポンスボディ：

12345678
              
              12345678
このコードブロックはフローティングウィンドウ内に表示されます

セキュリティメカニズム

クライアントの認証に使用され、オプションです。

メッセージの送信元がEngagelabであることを確認するために、POSTデータの送信元を認証することを選択できます。または、認証せずに直接POSTデータを解析することも可能です。

認証方法は以下のとおりです：

  • Engagelabコンソールでコールバックアドレスに対して、コールバックユーザー名（username）とコールバックシークレット（secret）を設定します。

リクエストヘッダーからX-CALLBACK-IDを取得します。例を以下に示します：

X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b
              
              X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b
このコードブロックはフローティングウィンドウ内に表示されます

ここで：

  • timestampはコールバックメッセージのタイムスタンプ（標準形式）です。
  • nonceはランダムな数値です。
  • signatureは署名情報です。

署名方法は以下のとおりです：

signature=HMAC-SHA256(secret, timestamp+nonce+username)
              
              signature=HMAC-SHA256(secret, timestamp+nonce+username)
このコードブロックはフローティングウィンドウ内に表示されます

レスポンスメカニズム

開発者サービスがEngagelabからのコールバックを受信した後、3秒以内に以下の要件に従って応答する必要があります：

  • 正常に受信： HTTPレスポンスステータスコードは200または204を返す必要があり、レスポンスメッセージは不要です。
  • 受信に失敗： HTTPレスポンスステータスコードは5XXまたは4XXを返す必要があり、レスポンスメッセージを返します。形式は以下のとおりです：
{ "code": 2002, "message": "error" }
              
              {
    "code": 2002,
    "message": "error"
}
このコードブロックはフローティングウィンドウ内に表示されます
フィールド 型 必須/オプション 説明
code int オプション エラーコード
message string オプション エラー詳細

コールバックフィールドの説明

メッセージボディ

フィールド名 型 必須/オプション 説明
total int 必須 このコールバックに含まれるメッセージの数
rows array 必須 メッセージ状態変更の詳細情報のリストで、以下のフィールドを含みます：

rows配列フィールド

フィールド名 型 必須/オプション 説明
message_id string 必須 メッセージの一意の識別子
from string オプション 送信者、デフォルトはappkey
to string オプション 受信者の識別子（例：registrationID）
server string 必須 メッセージサービス名、可能な値：WebPush
channel string 必須 メッセージチャネル、可能な値：EngageLab、Chrome、Firefox、Safari、Edge、Opera、Other
custom_args object オプション メッセージ作成時に送信されたカスタムパラメータ、そのまま返されます
itime int 必須 メッセージ状態が発生した実際のタイムスタンプで、message_statusと共に使用して各メッセージ状態のタイムスタンプを取得できます
status object 必須 メッセージ状態情報で、以下のフィールドを含みます：

statusオブジェクトフィールド

フィールド名 型 必須/オプション 説明
message_status string 必須 メッセージ状態、可能な値：target_valid、sent、delivered、click、target_invalid、sent_failed、delivered_failed、no_click
status_data object オプション カスタム状態データで、以下のフィールドを含みます：
channel_message_id string オプション サードパーティチャネルからのメッセージID
ntf_msg int 必須 メッセージタイプ、可能な値：1: Notification、2: Custom Message、7: In-App Message
platform string 必須 プッシュプラットフォーム、可能な値：b: Web
uid int 必須 プッシュメッセージの受信者のUID
app_version string 必須 SDK統合アプリバージョン、SDKレポートデータから取得
channel string 必須 SDK統合アプリチャネル、SDKレポートデータから取得
msg_time int 必須 メッセージ配信時間、メッセージを送信するAPIリクエストが成功した時間
time_zone string 必須 組織のタイムゾーン
loss_valid_type int オプション このフィールドには実際の意味がなく、処理する必要はありません
plan_user_total int オプション このフィールドには実際の意味がなく、処理する必要はありません
callback_type int オプション このフィールドには実際の意味がなく、処理する必要はありません
error_code int オプション エラーコード、失敗した場合にのみ提供
error_detail object オプション 詳細なエラー情報、失敗した場合にのみ提供し、以下のフィールドを含みます：
message string オプション 詳細なエラー理由を説明、FCMチャネルにのみ適用
loss object オプション 損失情報で、以下のフィールドを含みます：
loss_source string オプション 損失のソース、可能な値：EngageLab、Chrome、Firefox、Safari、Edge、Opera、Other
loss_step int オプション 損失段階、可能な値：1: Plan Target → Valid Target、2: Valid Target → Sent Quantity、3: Sent Quantity → Delivered Quantity、4: Delivered Quantity → Click Quantity

メッセージ状態値

状態値 意味 説明
target_valid 有効なターゲット 過去365日間にアクティブであれば有効と見なされます
sent 送信成功 サーバーに正常に送信されました
delivered 配信成功 実際のコールバックに基づいて配信されました
click ユーザークリック SDKによって報告されたユーザーのクリック
target_invalid 無効なターゲット 定義された損失段階1に基づいて無効と見なされます
sent_failed 送信失敗 定義された損失段階2に基づいて無効と見なされます
delivered_failed 配信失敗 定義された損失段階3に基づいて失敗と見なされます
no_click クリック失敗 定義された損失段階4に基づいて失敗と見なされ、インアプリメッセージにのみ適用されます

コールバックコンテンツ

コールバック方法：POST
Content-Type：application/json

例

リクエストヘッダー
POST /developer_define_url HTTP/1.1 Content-Type: application/json
              
              POST /developer_define_url HTTP/1.1
Content-Type: application/json
このコードブロックはフローティングウィンドウ内に表示されます
リクエストボディ
{ "total": 1, "rows": [ { "message_id": "1666165485030094861", // EngageLab側のメッセージID "from": "", // 送信者 "to": "", // 受信者、registrationID "server": "WebPush", "channel": "Chrome", "custom_args": {}, // このメッセージの作成時に送信されたパラメータ "itime": 1640707579, // 例：メッセージが配信された時間 "status": { // 成功時に返されるフィールド "message_status": "delivered", // メッセージ状態 "status_data": { // カスタムデータ "channel_message_id": "wamid.123321abcdefed==", // オプション、サードパーティチャネルのメッセージID "ntf_msg": 1, // メッセージタイプ "platform": "a", // プッシュプラットフォーム "uid": 100, // プッシュ通知のユーザーID "app_version": "", // SDKと統合されたアプリバージョン "channel": "", // SDKと統合されたアプリチャネル "msg_time": 1640707579, // メッセージ配信時間 "time_zone": "+8", // 組織のタイムゾーン "loss_valid_type": 0, // このフィールドは重要ではありません "plan_user_total": 0, // このフィールドは重要ではありません "callback_type": 0 // このフィールドは重要ではありません }, // 失敗時に返されるフィールド "error_code": 0, // エラーコード - ライフサイクルエラーコードに対応 "error_detail": { "message": "" // エラー理由 }, "loss": { "loss_source": "vivo", "loss_step": 1 } // 損失フェーズと損失ソース } } ] }
              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861", // EngageLab側のメッセージID
            "from": "", // 送信者
            "to": "", // 受信者、registrationID
            "server": "WebPush",
            "channel": "Chrome",
            "custom_args": {}, // このメッセージの作成時に送信されたパラメータ
            "itime": 1640707579, // 例：メッセージが配信された時間
            "status": {
                // 成功時に返されるフィールド
                "message_status": "delivered", // メッセージ状態    
                "status_data": { // カスタムデータ
                    "channel_message_id": "wamid.123321abcdefed==", // オプション、サードパーティチャネルのメッセージID
                    "ntf_msg": 1, // メッセージタイプ
                    "platform": "a", // プッシュプラットフォーム
                    "uid": 100, // プッシュ通知のユーザーID    
                    "app_version": "", // SDKと統合されたアプリバージョン 
                    "channel": "", // SDKと統合されたアプリチャネル   
                    "msg_time": 1640707579, // メッセージ配信時間
                    "time_zone": "+8", // 組織のタイムゾーン 
                    "loss_valid_type": 0, // このフィールドは重要ではありません
                    "plan_user_total": 0, // このフィールドは重要ではありません 
                    "callback_type": 0 // このフィールドは重要ではありません
                },
                // 失敗時に返されるフィールド
                "error_code": 0, // エラーコード - ライフサイクルエラーコードに対応
                "error_detail": {
                    "message": "" // エラー理由
                },
                "loss": {
                    "loss_source": "vivo",
                    "loss_step": 1
                } // 損失フェーズと損失ソース
            }
        }
    ]
}
このコードブロックはフローティングウィンドウ内に表示されます

パラメータの説明

値 意味
target_valid 有効なターゲット
sent 送信成功
delivered 配信成功
click ユーザークリック
target_invalid 無効なターゲット
sent_failed 送信失敗
delivered_failed 配信失敗

損失フェーズ

  1. 計画ターゲット → 有効なターゲット
  2. 有効なターゲット → 送信数
  3. 送信数 → 配信数
  4. 配信数 → クリック数

注：
1. 一部のチャネルでのクリックと配信は重複する可能性があり、自分で重複排除を行うことができます。
2. 配信成功後5日間は、配信数と表示数は調整されません。

icon
お問い合わせ