WhatsApp Business APIクライアントは、ユーザーとやり取りするメッセージのstatus
についての通知を送信します。この通知は、statuses
オブジェクトを通じて送信されます。
ビジネスが送信するすべてのメッセージについて、メッセージのステータスに関する通知を受け取ります。以下の表で、左の列にある矢印をクリックし、各ステータスがWhatsAppアプリでどのように表示されるかを確認してください。
名前 | 説明 |
---|---|
| ユーザーが送信したメッセージが、ユーザーにより削除されました。この通知を受け取った場合、メッセージがサーバーからダウンロードされているなら、システムからも確実に削除されるようにしてください。 |
| ビジネスから送信されたメッセージがユーザーのデバイスに配信されました。 |
| ビジネスからのメッセージの送信が失敗しました。失敗の理由がコールバックに含まれます。デバッグについては、以下のエラーメッセージのドキュメントを確認してください。
|
| ビジネスから送信されたメッセージが、ユーザーによって既読になりました。 |
| ビジネスが送信したメッセージが、システム内で転送されています。 オンプレミスAPIユーザーの場合: メッセージの |
| ビジネスが送信したメッセージに、利用できないか存在しないカタログのアイテムが含まれています。 |
アプリでの通知の順序には、メッセージステータスの実際のタイミングが反映されない場合があります。タイミングを調べるには、必要に応じてタイムスタンプを確認してください。
ステータスがread
になるためには、delivered
になっていなければなりません。ユーザーがチャット画面を開いている間にメッセージが到着した場合などは、メッセージが配信(delivered
)されるとほぼ同時に既読(read
)になります。そのような場合、delivered
の通知は戻されません。既読になった時点でメッセージが配信済みであることは明らかだからです。このような動作になっているのは、内部最適化のためです。
2022年2月1日以降、アウトバウンド通知のstatuses
オブジェクトに、conversation
とpricing
という新しい2つのネストされたオブジェクトが含まれるようになりました。スレッドと価格設定のオブジェクトコンポーネントは、スレッドがどこで開始されたかに応じて異なります。スレッドには、ユーザーが開始したもの、ビジネスが開始したもの、無料エントリーポイントから開始されたものがあります。以下の詳細をご覧ください。
次の例では、recipient_id
をgroup_id
フィールドにすることも可能です。それは、メッセージが個人に送信されたか、グループに送信されたかで異なります。
ビジネスが、利用者側が開始した会話の一部としてメッセージを送信すると(無料エントリーポイントに由来する会話ではない場合)、以下のwebhookを受け取ります。
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "sent", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "expiration_timestamp": TIMESTAMP, "origin": { "type": "user_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "user_initiated" } }] }
ビジネスが、メディアメッセージで、利用者側が開始した会話の一部としてメッセージを送信すると(無料エントリーポイントに由来する会話ではない場合)、以下のwebhookを受け取ります。
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "sent", "timestamp": "TIMESTAMP", "type": "message", "message": { "media_id": "98d14c8e-0310-4061-8f99-2d148274c286", "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "expiration_timestamp": TIMESTAMP, "origin": { "type": "user_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "user_initiated" } }] }
ビジネスが、ビジネス側が開始した会話の一部としてメッセージを送信すると、以下のwebhookを受け取ります。
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "sent", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "expiration_timestamp": TIMESTAMP, "origin": { "type": "business_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "business_initiated" } }] }
ビジネスが無料エントリーポイントに由来するユーザー開始スレッドへの返信としてメッセージを送信すると、以下のwebhookを受け取ります。
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "sent", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "expiration_timestamp": TIMESTAMP, "origin": { "type": "referral_conversion", } }, "pricing": { "pricing_model": "CBP", "billable": false, "category": "referral_conversion" } }] }
ビジネスのメッセージが配信され、そのメッセージがユーザー開始スレッドの一部である場合、以下のwebhookを受け取ります(スレッドが無料エントリーポイントに由来するものではない場合)。
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "delivered", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "origin": { "type": "user_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "user_initiated" } }] }
ビジネスのメッセージが配信され、そのメッセージがビジネス開始スレッドの一部である場合、以下のwebhookを受け取ります。
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "delivered", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id": "WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "origin": { "type": "business_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "business_initiated" } }] }
ビジネスのメッセージが配信され、そのメッセージが無料エントリーポイントに由来するユーザー開始スレッドの一部である場合、以下のwebhookを受け取ります。
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "delivered", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id": "WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "origin": { "type": "referral_conversion", } }, "pricing": { "pricing_model": "CBP", "billable": false, "category": "referral_conversion" } }] }
既読メッセージに対する標準のコールバック:
{ "statuses":[{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "read", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id": "WHATSAPP_ID" } }] }
{ "statuses": [{ "errors": [{ "code": 470, "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider." }], "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "failed", "timestamp": "TIMESTAMP" }] }
{ "statuses": [{ "errors": [{ "code": 480, "title": "Failed to send message since we detect an identity change of the contact" }], "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "failed", "timestamp": "TIMESTAMP" }] }
メッセージが失敗した場合、スレッドサブセクションはコールバックに含められません。請求やスレッドのアクティベーションは例外です。
削除済みメッセージに対する標準のコールバック:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "deleted", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id": "WHATSAPP_ID" } }] }
メッセージが削除された場合、スレッドサブセクションはコールバックに含められません。請求やスレッドのアクティベーションは例外です。
詳しくは、概要、メッセージをご覧ください。
Yes, there is a specific scenario where you can get pricing information on your webhook alert for read messages. For each sent message, there can be 3 scenarios:
Scenario | When it Happens |
---|---|
You get a webhook alert when the message is delivered (including pricing information) and another webhook alert when the message is read (not including pricing information). | This is the most common scenario. |
You get a webhook alert when the message is delivered (including pricing information). You do not get a webhook alert that the message has been read. | Common when a customer has turned off the feature that lets people know they have read a message. |
You get a webhook alert when the message is read (including pricing information). You do not get a webhook alert that the message has been delivered. | Only triggered when the user is already reading the thread with the business when the message comes in. |