メッセージコールバック API
概要
「メッセージステータス」と「メッセージ応答」のデータを企業の業務システムに送信します。この情報を統計の集計やユーザーへの返信などに利用できます。
コールバック URL
企業は「メッセージステータス」と「メッセージ応答」を受信するコールバック URL を設定する必要があります。詳しくはコールバック設定を参照してください。
コールバック形式
リクエスト方式は POST、リクエストボディは JSON、データ型は Content-Type: application/json です。1 回のリクエストで複数のデータをまとめて送信します。
セキュリティ
提供予定です。現在、コールバックには認証情報が含まれていないため、コールバックを受信する開発者側のエンドポイントに認証を設定しないでください。
応答
EngageLab のコールバックを受信したら、開発者のサービスは 3 秒以内に応答する必要があります。正常に受信した場合は HTTP ステータスコード 200 を返してください。レスポンスボディは不要です。
再試行
提供予定です。
リクエストパラメータ
EngageLab が業務システムのコールバック URL に送信するリクエストパラメータは以下のとおりです。
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| total | int | 必須 | コールバックのデータ件数 |
| rows | JSON Array | 必須 | コールバックの詳細情報 |
rows 内のパラメータ:
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| message_id | string | 任意 | メッセージステータスとメッセージ応答で返されます。 |
| from | string | 任意 | 送信者。メッセージステータスのコールバックでは企業の送信番号です。ユーザーからの受信メッセージのコールバックではユーザー識別子で、電話番号がある場合は電話番号、ない場合は BSUID が返されることがあります。 |
| to | string | 任意 | 受信者。メッセージステータスのコールバックでは電話番号または BSUID です。識別子を取得できない場合は空文字列になります。ユーザーからの受信メッセージのコールバックでは企業の送信番号です。 |
| recipient_phone | string | 任意 | メッセージステータスのコールバックにおける受信者の電話番号。値がない場合は省略されます。 |
| server | string | 必須 | 製品サービス。固定値は whatsapp です。 |
| channel | string | 任意 | ステータスまたは応答が属するチャネル。固定値は whatsapp です。 |
| itime | int | 必須 | コールバックデータが実際に生成されたタイムスタンプ。message_status と組み合わせて、リクエスト、送信、配信、既読の時刻を確認できます。 |
| custom_args | JSON Object | 任意 | メッセージ送信時の任意のカスタムフィールド。メッセージステータスのコールバックでそのまま返されます。 |
| status | JSON Object | 任意 | メッセージステータス |
| response | JSON Object | 任意 | メッセージ応答 |
| notification | JSON Object | 任意 | メッセージ通知 |
BSUID フィールド
BSUID は既存のコールバックボディの以下の任意フィールドで返されます。
| コールバック種別 | JSON パス | 型 | 説明 |
|---|---|---|---|
| メッセージステータス | rows[].status.status_data.recipient_user_id |
String | 受信者の BSUID |
| ユーザーからの受信メッセージ | rows[].response.response_data.contact.user_id |
String | メッセージを送信したユーザーの BSUID |
- BSUID が存在しない、または利用できない場合、該当フィールドは返されません。クライアント側はフィールドの欠落を許容する必要があります。
- 電話番号と BSUID の両方を表示する場合、メッセージステータスのコールバックでは
recipient_phoneとstatus_data.recipient_user_id、受信メッセージのコールバックではcontact.wa_idとcontact.user_idを利用できます。
メッセージステータス - status
コールバックパラメータ
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| message_status | string | 必須 | メッセージのステータス |
| status_data | JSON Object | 任意 | このステータスの詳細データ |
| error_code | int | 任意 | エラーコード。失敗時に返されます。 |
| error_detail | JSON Object | 任意 | エラーの詳細。失敗時に返されます。 |
| loss | JSON Object | 任意 | 失敗が発生した段階と原因元 |
message_status
| 値 | 説明 | 詳細 |
|---|---|---|
| plan | 送信予定 | 指定された受信者番号に含まれる番号について、送信予定の対象を 1 件記録します。 |
| target_valid | 有効な対象 | 検証に合格した番号です。EngageLab と Meta WhatsApp サービスで有効と判定されます。 |
| sent | 送信成功 | EngageLab が番号を Meta WhatsApp サービスに送信し、成功が返されました。 |
| delivered | 配信成功 | Meta WhatsApp サービスがユーザーへの配信を確認しました。 |
| read | 既読 | Meta WhatsApp サービスがユーザーの既読を確認しました。 |
| target_invalid | 無効な対象 | EngageLab または Meta WhatsApp サービスが番号を無効と判定しました。 |
| sent_failed | 送信失敗 | 番号を Meta WhatsApp サービスに送信した後、失敗が返されました。 |
| delivered_failed | 配信失敗 | Meta WhatsApp サービスへの送信は成功しましたが、Meta のコールバックで失敗が通知されました。 |
| delivered_timeout | 配信タイムアウト | Meta WhatsApp サービスへの送信後、5 分以内に Meta から成功・失敗のコールバックがなかったため、タイムアウトとなりました。 |
status_data
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| msg_time | int | 必須 | メッセージ送信 API の呼び出しが成功した時刻 |
| channel_message_id | String | 必須 | WhatsApp が返すメッセージ ID |
| whatsapp_business_account_id | String | 必須 | 送信番号が属する WhatsApp Business Account (WABA) の ID |
| timezone | String | 必須 | 組織のタイムゾーン |
| plan_user_total | int | 任意 | 送信予定の対象総数。message_status=plan の場合のみ値があります。 |
| country_code | String | 必須 | 受信者の電話番号の国・地域コード |
| from_phone_id | String | 必須 | 送信番号(from)の ID |
| recipient_user_id | String | 任意 | 受信者の BSUID。値がある場合に返され、ない場合は省略されます。 |
| conversation | JSON Object | 任意 | 会話情報 |
| pricing | JSON Object | 任意 | 料金情報 |
recipient_user_id は、受信者の BSUID を取得済みの sent、delivered、read などのコールバックで通常返されます。前処理や失敗のステータス、過去のメッセージ、旧処理経路のデータでは返されない場合があります。
conversation
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| id | String | 任意 | このメッセージが属する Meta の会話 ID |
| origin | JSON Object | 任意 | 会話を開始した側を type で指定します。例:"origin":{"type":"business_initiated"}。 business_initiated:企業が顧客に最初のメッセージを送信して開始する会話。顧客の最後のメッセージから 24 時間を超えた場合に適用されます。 customer_initiated:顧客のメッセージから 24 時間以内に企業が返信して開始する会話。 referral_conversion:無料エントリーポイントから開始する会話。常に顧客が開始します。 |
pricing
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| pricing_model | String | 任意 | 固定値は CBP です。 |
| category | String | 任意 | 会話の料金カテゴリ。business_initiated:企業主導の会話。customer_initiated:ユーザー主導の会話。referral_conversion:無料エントリーポイントからの会話。 |
error_detail
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| message | String | 必須 | エラーの原因 |
loss
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| loss_step | int | 必須 | 失敗が発生した段階。 1:送信予定の対象から有効な対象になるまで(無効な対象)。 2:有効な対象から送信まで(送信失敗)。 3:送信から配信まで(配信失敗)。 |
| loss_source | String | 必須 | 原因元。engagelab:EngageLab WhatsApp サービスの検証に起因する失敗。meta:Meta が返したエラー。 |
コールバック例
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861",
"from": "",
"to": "US.13491208655302741918",
"recipient_phone": "12025550123",
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579,
"custom_args": {},
"status": {
"message_status": "delivered",
"status_data": {
"msg_time": 1663432355,
"channel_message_id": "wamid.123321abcdefed==",
"whatsapp_business_account_id": "",
"timezone": "",
"plan_user_total": 2007,
"country_code": "US",
"from_phone_id": "111111",
"recipient_user_id": "US.13491208655302741918",
"conversation": {
"id": "ebe2398cdaa37a0899ca5268b987b0c8",
"origin": {
"type": "business_initiated"
}
},
"pricing": {
"pricing_model": "CBP",
"category": "business_initiated"
}
},
"error_code": 0,
"error_detail": {
"message": ""
},
"loss": {
"loss_step": 1,
"loss_source": "aa"
}
}
}
]
}
メッセージ応答 - response
コールバックパラメータ
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| event | string | 任意 | 応答イベント |
| response_data | JSON Object | 任意 | 受信した返信または対話型メッセージの内容 |
event
| 値 | 説明 | 詳細 |
|---|---|---|
| received | ユーザーメッセージを受信 | ユーザーが直接メッセージを送信しました。 |
| reply | ユーザーからの返信 | 企業が先に送ったメッセージにユーザーが返信しました。 |
| order | ユーザーの注文 | - |
| deleted | ユーザーがメッセージを削除 | ユーザーが自分の送信メッセージを削除しました(提供予定)。 |
response_data
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| channel_message_id | String | 必須 | WhatsApp が返すメッセージ ID |
| whatsapp_business_account_id | String | 必須 | 送信番号が属する WhatsApp Business Account (WABA) の ID |
| contact | JSON Object | 任意 | 送信者情報 |
| message | JSON Object | 必須 | メッセージの内容 |
| message_context | JSON Object | 任意 | メッセージのコンテキスト。reply イベントに含まれ、返信対象のメッセージを示します。 |
contact
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| profile | JSON Object | 任意 | 送信者(顧客)のプロフィール。name は顧客の名前、username はユーザーネーム(User Username)を表し、name とは異なります。username に値がない場合は省略されます。 例:"profile": {"name": "bob", "username": "example_user"} |
| wa_id | String | 任意 | 送信者の電話番号識別子。BSUID のみの場合は空文字列になることがあります。 |
| user_id | String | 任意 | メッセージを送信したユーザーの BSUID。値がある場合に返され、ない場合は省略されます。 |
contact.wa_id は従来どおり電話番号を表し、contact.user_id は BSUID を返します。BSUID でユーザーを識別する場合は contact.user_id を優先して読み取り、contact.wa_id を BSUID として使用しないでください。
message
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| type | String | 必須 | 値:text、image、audio、video、document、sticker、button、interactive、unknown、order |
| text | JSON Object | 任意 | text オブジェクトの説明を参照してください。 |
| image | JSON Object | 任意 | image オブジェクトの説明を参照してください。 |
| audio | JSON Object | 任意 | audio オブジェクトの説明を参照してください。 |
| video | JSON Object | 任意 | video オブジェクトの説明を参照してください。 |
| document | JSON Object | 任意 | document オブジェクトの説明を参照してください。 |
| sticker | JSON Object | 任意 | sticker オブジェクトの説明を参照してください。 |
message_context
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| origin_from_phone | String | 必須 | 参照されたメッセージの送信番号。空白や + 記号は含みません。 |
| origin_channel_message_id | String | 必須 | 参照されたメッセージの一意の ID |
| origin_from_phone_id | String | 任意 | 参照されたメッセージの送信番号 ID。通常はこのフィールドが含まれます。 |
| origin_message_id | String | 任意 | 参照されたメッセージのメッセージ ID。通常はこのフィールドが含まれます。 |
コールバック例
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861",
"from": "",
"to": "",
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579,
"response": {
"event": "",
"response_data": {
"channel_message_id": "wamid.123321abcdefed==",
"whatsapp_business_account_id": "123321",
"contact": {
"profile": {
"name": "bob",
"username": "example_user"
},
"wa_id": "8613800138000",
"user_id": "ID.1234567890123456"
},
"message": {
"type": "text",
"text": {
"body": "here is the message content text"
}
}
}
}
}
]
}
メッセージ通知 - notification
コールバックパラメータ
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| event | string | 任意 | 応答イベント |
| notification_data | JSON Object | 任意 | システムメッセージ通知の詳細内容 |
event
| 値 | 説明 | 詳細 |
|---|---|---|
| insufficient_balance | 残高不足 | 現在の残高が設定したしきい値(デフォルトは 10 米ドル)を下回りました。 |
| template_update | テンプレートの変更 | テンプレートのステータスまたは品質が変更されました。 |
| phone_number_update | 送信番号の変更 | 現在 Meta がサポートしているのはメッセージ送信上限の変更のみです。 TIER_50:50 人/24 時間 TIER_250:250 人/24 時間 TIER_1K:1,000 人/24 時間 TIER_10K:10,000 人/24 時間 TIER_100K:100,000 人/24 時間 TIER_UNLIMITED:上限なし |
| whatsapp_business_update | WABA の変更 | WABA の利用停止、警告など。 |
notification_data
| フィールド | 型 | 必須/任意 | 説明 |
|---|---|---|---|
| whatsapp_business_account_id | String | 必須 | WhatsApp Business Account (WABA) の ID |
| remain_balance | int | 任意 | event=insufficient_balance の場合に含まれます。現在の残高(米ドル)。 |
| balance_threshold | int | 任意 | event=insufficient_balance の場合に含まれます。設定した残高アラートのしきい値(米ドル)。 |
| template_id | String | 任意 | event=template_update の場合に含まれます。テンプレート ID。 |
| template_name | String | 任意 | event=template_update の場合に含まれます。テンプレート名。 |
| template_language | String | 任意 | event=template_update の場合に含まれます。テンプレートの言語。 |
| template_status | String | 任意 | event=template_update の場合に含まれます。値:APPROVED/REJECTED/PENDING/DISABLED/FLAGGED/REINSTATED。 |
| template_status_reason | String | 任意 | event=template_update の場合に含まれます。変更理由。通常はテンプレートの審査拒否時に使用され、それ以外は文字列 NONE または省略されます。 |
| template_quality_score | String | 任意 | event=template_update の場合に含まれます。品質評価:GREEN(高)、YELLOW(中)、RED(低)、UNKNOWN(未確定)。 |
| new_category | String | 任意 | event=template_update の場合に含まれます。更新後のテンプレートカテゴリ。 |
| phone_number_id | String | 任意 | event=phone_number_update の場合に含まれます。送信番号 ID。 |
| display_phone_number | String | 任意 | event=phone_number_update の場合に含まれます。送信電話番号。例:+1 320-302-7083、+86 183 7981 2430。 |
| current_limit | String | 任意 | event=phone_number_update の場合に含まれます。送信番号の現在の上限。値:TIER_50/TIER_250/TIER_1K/TIER_10K/TIER_100K/TIER_UNLIMITED。 |
| waba_event | String | 任意 | event=whatsapp_business_update の場合に含まれます。DISABLED_UPDATE:アカウント無効化。ACCOUNT_VIOLATION:アカウントの違反。 |
| ban_state | String | 任意 | event=whatsapp_business_update かつ waba_event=DISABLED_UPDATE の場合に値があります。現在の値は DISABLE(無効化)です。 |
| violation_type | String | 任意 | event=whatsapp_business_update かつ waba_event=ACCOUNT_VIOLATION の場合に値があります。SPAM:スパム・迷惑メッセージ。SCAM:詐欺メッセージ。 |
| decision | String | 任意 | 送信番号の表示名更新の結果。APPROVED:承認。DEFERRED:審査判断の延期。PENDING:追加審査待ち。REJECTED:拒否。 |
| requested_verified_name | String | 任意 | ビジネス電話番号の作成時に入力した表示名、または承認済みの表示名の編集時に申請した名前。 |
| rejection_reason | String | 任意 | ビジネス電話番号の表示名が拒否された理由。 NAME_EMPLOYEE_ISSUE:個人名または従業員番号を含む。 NAME_ENDCLIENT_NOTRELATED:無関係な企業名を含む。 NAME_FORMAT_UNACCEPTABLE:許可されない形式。 NAME_INDIVIDUAL_ISSUE:個人名または従業員番号を含む。 NAME_NOT_CONSISTENT:企業ブランドと一致しない。 null:承認済み。 UNKNOWN:不明な理由。サポートにお問い合わせください。 |
コールバック例
{
"total": 1,
"rows": [
{
"server": "whatsapp",
"itime": 1640707579,
"notification": {
"event": "insufficient_balance",
"notification_data": {
"whatsapp_business_account_id": "",
"remain_balance": 5.1234,
"balance_threshold": 10
}
}
}
]
}
メッセージテンプレートのステータス更新コールバック
WhatsApp メッセージテンプレートのステータスが変更されると、以下の構造の Webhook データが送信されます。
発生条件
- テンプレートが承認された。
- テンプレートが拒否された。
- テンプレートが無効化された。
コールバックデータ構造
disable_info はテンプレートが無効化された場合のみ、other_info はテンプレートがロックまたはロック解除された場合のみ含まれます。rejection_info は INVALID_FORMAT による拒否の場合のみ含まれます。
{
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"time": <WEBHOOK_TRIGGER_TIMESTAMP>,
"changes": [
{
"value": {
"event": "<EVENT>",
"message_template_id": <TEMPLATE_ID>,
"message_template_name": "<TEMPLATE_NAME>",
"message_template_language": "<TEMPLATE_LANGUAGE_AND_LOCALE_CODE>",
"reason": "<REASON>",
"message_template_category": <TEMPLATE_CATEGORY>,
"disable_info": {
"disable_date": "<DISABLE_TIMESTAMP>"
},
"other_info": {
"title": "<TITLE>",
"description": "<DESCRIPTION>"
}
},
"rejection_info": {
"reason": "<REASON_INFO>",
"recommendation": "<RECOMMENDATION_INFO>"
},
"field": "message_template_status_update"
}
]
}
],
"object": "whatsapp_business_account"
}
パラメータの説明
| プレースホルダー | 型 | 説明 | 例 |
|---|---|---|---|
<DESCRIPTION> |
String | テンプレートのロック・解除の理由 | WhatsApp メッセージテンプレートが再び利用可能になりました。 |
<DISABLE_TIMESTAMP> |
Integer | テンプレートが無効化された Unix タイムスタンプ | 1751234563 |
<EVENT> |
String | テンプレートのステータスイベント。以下を参照。 | APPROVED |
<TEMPLATE_ID> |
Integer | テンプレート ID | 1689556908129832 |
<TEMPLATE_NAME> |
String | テンプレート名 | order_confirmation |
<TEMPLATE_LANGUAGE_AND_LOCALE_CODE> |
String | テンプレートの言語と地域コード | en-US |
<REASON> |
String | テンプレートの拒否・無効化の理由。以下を参照。 | INVALID_FORMAT |
<TITLE> |
String | 一時停止・再開イベントのタイトル。以下を参照。 | FIRST_PAUSE |
<WEBHOOK_TRIGGER_TIMESTAMP> |
Integer | Webhook 発生時の Unix タイムスタンプ | 1739321024 |
<WHATSAPP_BUSINESS_ACCOUNT_ID> |
String | WhatsApp Business Account (WABA) の ID | 102290129340398 |
<MESSAGE_TEMPLATE_CATEGORY> |
String | テンプレートのカテゴリ。以下を参照。 | MARKETING |
<REASON_INFO> |
String | テンプレートが審査に通らなかった詳細な理由 | Your template has parameters placed next to each other ... |
<RECOMMENDATION_INFO> |
String | 審査に通るための修正案 | Separate parameters with descriptive text ... |
<EVENT> の値
| 値 | 説明 |
|---|---|
| APPROVED | 承認済み。メッセージ送信に使用できます。 |
| ARCHIVED | アーカイブ済み |
| DELETED | 削除済み |
| DISABLED | ユーザーの反応により無効化 |
| FLAGGED | 否定的な反応があり、無効化される可能性があります。 |
| IN_APPEAL | 異議申し立て中 |
| LIMIT_EXCEEDED | テンプレート数の上限に到達 |
| LOCKED | ロック中。編集できません。 |
| PAUSED | 一時停止中 |
| PENDING | 審査中 |
| REINSTATED | フラグ・無効化が解除され、再び送信できます。 |
| PENDING_DELETION | 削除され、完全消去待ち |
| REJECTED | 拒否。編集して再申請、または異議申し立てができます。 |
<REASON> の値
| 値 | 説明 |
|---|---|
| ABUSIVE_CONTENT | 違反コンテンツを含む |
| CATEGORY_NOT_AVAILABLE | 非対応地域向け認証テンプレート(廃止) |
| INCORRECT_CATEGORY | 内容と指定カテゴリが一致しない |
| INVALID_FORMAT | 形式が無効 |
| NONE | テンプレートが一時停止された |
| PROMOTIONAL | 許可されない販促コンテンツ |
| SCAM | 詐欺コンテンツ |
| TAG_CONTENT_MISMATCH | 内容と指定カテゴリが一致しない |
| null | 削除予定 |
<TITLE> の値
| 値 | 説明 |
|---|---|
| FIRST_PAUSE | 初回の一時停止 |
| SECOND_PAUSE | 2 回目の一時停止 |
| RATE_LIMITING_PAUSE | レート制限による一時停止 |
| UNPAUSE | 一時停止解除 |
| DISABLED | 無効化済み |
<MESSAGE_TEMPLATE_CATEGORY> の値
| 値 | 説明 |
|---|---|
| MARKETING | マーケティング |
| UTILITY | 実用的な通知 |
| AUTHENTICATION | 認証 |
例
テンプレート承認の Webhook 例
{
"entry": [
{
"id": "102290129340398",
"time": 1751247548,
"changes": [
{
"value": {
"event": "APPROVED",
"message_template_id": 1689556908129832,
"message_template_name": "order_confirmation",
"message_template_language": "en-US",
"reason": "NONE",
"message_template_category": "UTILITY"
},
"field": "message_template_status_update"
}
]
}
],
"object": "whatsapp_business_account"
}
INVALID_FORMAT によるテンプレート拒否の Webhook 例
{
"entry": [
{
"id": "102290129340398",
"time": 1751247548,
"changes": [
{
"value": {
"event": "REJECTED",
"message_template_id": 1689556908129835,
"message_template_name": "abandoned_cart",
"message_template_language": "en",
"reason": "INVALID_FORMAT",
"message_template_category": "MARKETING",
"rejection_info": {
"reason": "Your template has parameters placed next to each other (like ) without text or punctuation between them.",
"recommendation": "Separate parameters with descriptive text and ensure each parameter is clearly contextualized."
}
},
"field": "message_template_status_update"
}
]
}
],
"object": "whatsapp_business_account"
}










