WhatsApp Business API 클라이언트는 비즈니스와 사용자 사이의 메시지 status
에 대한 알림을 전송합니다. 이러한 알림은 statuses
개체를 통해 전송됩니다.
비즈니스가 메시지를 보낼 때마다 메시지 상태에 대한 알림을 받게 됩니다. 아래의 표에서 WhatsApp 앱의 각 상태에 해당하는 왼쪽 열의 화살표를 클릭하세요(해당하는 경우).
이름 | 설명 |
---|---|
| 사용자가 본인이 보낸 메시지를 삭제했습니다. 이 알림을 받은 경우 메시지가 서버에서 다운로드되었다면 시스템에서 해당 메시지가 삭제되었는지 확인해야 합니다. |
| 비즈니스에서 보낸 메시지를 사용자 기기로 전달했습니다. |
| 비즈니스에서 보낸 메시지가 전송되지 않았습니다. 전송 실패 원인은 콜백에 포함됩니다. 디버깅 관련 도움말은 오류 메시지 문서를 참조하세요. |
| 사용자가 비즈니스에서 보낸 메시지를 읽었습니다. |
| 비즈니스에서 보낸 메시지가 시스템 내에서 전송 중입니다. 온프레미스 API 사용자: |
| 비즈니스가 보낸 메시지에 사용할 수 없거나 존재하지 않는 카탈로그 항목이 포함되어 있습니다. |
앱에서 이 알림을 받는 순서는 메시지 상태의 실제 시간을 반영하지 않을 수 있습니다. 필요한 경우 타임스탬프에서 시간을 확인하세요.
상태가 read
가 되려면 delivered
되어야 합니다. 사용자가 채팅 화면에 있을 때 메시지가 도착하는 경우와 같이 어떤 경우에는 메시지가 거의 delivered
되는 동시에 read
상태가 됩니다. 이 경우 또는 다른 유사한 경우에는 메시지를 읽으면 전달된 것으로 간주되므로 delivered
알림이 반송되지 않습니다. 이렇게 동작하는 이유는 내부 최적화 때문입니다.
2022년 2월 1일부터 아웃바운드 알림의 statuses
개체에 두 개의 중첩된 새 개체(conversation
및 pricing
)가 포함됩니다. 대화 및 가격 개체 구성 요소는 대화가 시작된 위치에 따라 달라집니다. 대화는 사용자 또는 비즈니스가 시작하거나 무료 진입점에서 시작할 수 있습니다. 아래에서 자세한 정보를 확인하세요.
다음 예시에서 recipient_id
는 group_id
필드로 대신할 수 있습니다. 메시지를 전송하는 대상이 개인인지 그룹인지에 따라 달라집니다.
비즈니스에서 사용자가 시작한 대화(해당 대화가 무료 진입점에서 시작되지 않은 경우)의 일부로 메시지를 전송하면 다음과 같은 Webhooks를 수신합니다.
{ "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" } }] }
비즈니스에서 미디어 메시지에 대해 사용자가 시작한 대화(해당 대화가 무료 진입점에서 시작되지 않은 경우)의 일부로 메시지를 전송하면 다음과 같은 Webhooks를 수신합니다.
{ "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" } }] }
비즈니스에서 비즈니스가 시작한 대화의 일부로 메시지를 전송하면 다음과 같은 Webhooks를 수신합니다.
{ "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" } }] }
비즈니스가 무료 진입점에서 발생한 사용자가 시작한 대화에 대한 답장으로 메시지를 전송하면 다음과 같은 Webhooks를 수신합니다.
{ "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" } }] }
비즈니스의 메시지가 전달되고 해당 메시지가 사용자가 시작한 대화(해당 대화가 무료 진입점에서 시작되지 않은 경우)의 일부인 경우 다음과 같은 Webhooks를 수신합니다.
{ "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" } }] }
비즈니스의 메시지가 전달되고 해당 메시지가 비즈니스가 시작한 대화의 일부인 경우 다음과 같은 Webhooks를 수신합니다.
{ "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" } }] }
비즈니스의 메시지가 전달되고 해당 메시지가 무료 진입점에서 발생한 사용자가 시작한 대화의 일부인 경우 다음과 같은 Webhooks를 수신합니다.
{ "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. |