WhatsApp Business 플랫폼 온프레미스 API

수신된 메시지 알림

인바운드 메시지를 받으면 앱 설정에 설정된 Webhooks URL로 알림이 전송됩니다. 이 문서에서는 수신할 수 있는 인바운드 메시지를 살펴보고 예시를 제공합니다.

알림 개체

수신된 메시지 알림은 다음과 같은 개체를 포함할 수 있습니다.

미디어가 포함된 메시지를 수신하면 WhatsApp Business API 클라이언트가 미디어를 다운로드합니다. 미디어가 다운로드되면 Webhooks로 알림이 전송됩니다. 이 알림에는 미디어 개체를 식별하여 해당 개체를 찾아서 가져올 수 있는 정보가 포함됩니다. 미디어의 id와 함께 미디어 엔드포인트를 사용하여 미디어를 가져옵니다.

수신된 메시지 예시

문자 메시지

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
      },
    "wa_id": "16315551234"
  }],
  "messages":[{
    "from": "16315551234",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1518694235",
    "text": {
      "body": "Hello this is an answer"
    },
    "type": "text"
  }]
}

고정 위치 메시지

{
  "contacts": [{
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
 "messages":[{
   "from":"16315551234",
   "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
   "location":{
      "address":"Main Street Beach, Santa Cruz, CA",
      "latitude":38.9806263495,
      "longitude":-131.9428612257,
      "name":"Main Street Beach",
      "url":"https://foursquare.com/v/4d7031d35b5df7744"},
   "timestamp":"1521497875",
   "type":"location"
 }]
}

연락처 메시지

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "contacts": [{
      "addresses": [{
        "city": "Menlo Park",
        "country": "United States",
        "country_code": "us",
        "state": "CA",
        "street": "1 Hacker Way",
        "type": "WORK",
        "zip": "94025"
      }],
      "birthday": "2012-08-18",
      "emails": [{
        "email": "kfish@fb.com",
        "type": "WORK"
      }],
      "ims": [{
        "service": "AIM",
        "user_id": "kfish"
      }],
      "name": {
        "first_name": "Kerry",
        "formatted_name": "Kerry Fisher",
        "last_name": "Fisher"
      },
      "org": {
        "company": "Meta",
 	"department": "WhatsApp"
      },
      "phones": [{
        "phone": "+1 (940) 555-1234",
        "type": "CELL"
        },
        {
          "phone": "+1 (650) 555-1234",
          "type": "WORK",
          "wa_id": "16505551234"
      }],
      "urls": [{
        "url": "https://www.facebook.com",
        "type": "WORK"
      }]
    }],
    "from": "16505551234",
    "id": "ABGGFlA4dSRvAgo6C4Z53hMh1ugR",
    "timestamp": "1537248012",
    "type": "contacts"
  }]
}

소비자 클라이언트가 iPhone을 사용할 경우 contact_image 설정은 비어 있습니다.

미디어 메시지

이미지를 포함한 메시지:

{
	"messages": [{
		"from": "16315551234",
		"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
		"image": {
			"file": "/usr/local/wamedia/shared/b1cf38-8734-4ad3-b4a1-ef0c10d0d683",
			"id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
			"mime_type": "image/jpeg",
			"sha256": "29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db",
			"caption": "Check out my new phone!",
			"status": "downloaded"
		},
		"timestamp": "1521497954",
		"type": "image"
	}]
}

2.49.1 버전부터 미디어 메시지 Webhooks에는 수신된 메시지의 상태와 ID가 포함됩니다.

다운로드 상태

상태설명

downloaded

미디어가 다운로드되었습니다.

retriable

미디어가 다운로드되지 않았지만 재시도 엔드포인트를 사용하여 다운로드를 다시 시도할 수 있습니다.

undownloaded

미디어가 다운로드되지 않았을 수 있습니다.

미디어 메시지에서 caption 필드는 선택 사항입니다. 사용자가 캡션을 설정한 경우에만 포함됩니다.

문서를 포함한 메시지:

{
  "messages": [{
    "from": "16315551234",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1522189546",
    "type": "document",
    "document": {
      "caption": "80skaraokesonglistartist",
			"file": "/usr/local/wamedia/shared/fc233119-733f-49c-bcbd-b2f68f798e33",
			"id": "fc233119-733f-49c-bcbd-b2f68f798e33",
			"mime_type": "application/pdf",
			"sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e",
			"status": "downloaded"
		}
	}]
}

음성 메시지:

{
    "messages":[{
        "from": "16315551234",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
        "timestamp": "1521827831",
        "type": "voice",
        "voice": {
            "file": "/usr/local/wamedia/shared/463e/b7ec/ff4e4d9bb1101879cbd411b2",
            "id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
            "mime_type": "audio/ogg; codecs=opus",
            "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710",
            "status": "downloaded"
        }
  }]
}

스티커를 포함한 메시지:

{
  "messages":[{
        "from": "16315551234",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
        "timestamp": "1521827831",
        "type": "sticker",
        "sticker": {
            "id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
            "metadata": {
                "sticker-pack-id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
                "sticker-pack-name" : "Happy New Year",
                "sticker-pack-publisher" : "Kerry Fisher",
                "emojis": ["🐥", "😃"],
                "ios-app-store-link" : "https://apps.apple.com/app/id3133333",
                "android-app-store-link" : "https://play.google.com/store/apps/details?id=com.example",
                "is-first-party-sticker" : 0 | 1 # integer 
            },
            "mime_type": "image/webp",
            "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
        }  
    }]
}

WhatsApp 연결 광고에서 생성된 메시지

{
   "messages":[{
      "from":"12345678",
      "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "image":{
         "id":"b1c68f38-8734-4ad3-b4a1-ef0c10d683",
         "mime_type":"image/jpeg",
         "sha256":"29ed500fa64eb55fc19dc4124acb300e5dcca0f822a301ae99944db"
         "caption": "Check out my product!",
      },
      "timestamp":"1521497954",
      "type":"image",
      "referral" : {
        "headline": "Our new product",
        "body" : "This is a great product",
        "source_type": "<SOURCE_TYPE>",
        "source_id": "<SOURCE_ID>",
        "source_url": "<SOURCE_URL>", //for the moment, this will always be a Facebook owned domain
        "video": {
          "id": "e144be57-12b1-4035-a520-703fcc87ef45",
        "ctwa_clid": "<CTWA_CLID>",
      }     
    }
  }]
}

referral 속성에 대한 자세한 내용을 참조하세요.

예: 지원되지 않는 메시지

unknown 콜백 알림을 수신할 수 있습니다. 고객에게서 수신한 지원되지 않는 메시지 유형의 예는 다음과 같습니다.

{
  "contacts": [{
		"profile": {
			"name": "Kerry Fisher"
		},
		"wa_id": "16315551234"
	}],
  "messages": [{
		"errors": [{
			"code": 501,
			"details": "Message type is not currently supported",
			"title": "Unknown message type"
		}],
		"from": "16315551234",
		"id": "ABGGFRBzFymPAgo6N9KKs7HsN6eB",
		"timestamp": "1531933468",
		"type": "unknown"
	}]
}

전달된 메시지

수신된 메시지가 전달되었거나 자주 전달되는지 여부를 확인할 수 있습니다. 전달된 메시지에 대한 알림은 다음과 같습니다.

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "context": {
      "forwarded": true
    },
    "from": "16315558011",
    "id": "ABGGFmkiWVVPAgo-sOGh7pv13wVJ",
    "text": {
      "body": "Party at Dotty's tonight!"
    },
    "timestamp": "1593068329",
    "type": "text"
  }]
}

자주 전달된 메시지에 대한 알림은 다음과 같습니다.

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "context": {
      "frequently_forwarded": true
    },
    "from": "16315558011",
    "id": "ABGGFmkiWVVPAgo-sBTHfS3swNIl",
    "timestamp": "1593068225",
    "type": "video",
    "video": {
      "id": "e144be57-12b1-4035-a520-703fcc87ef45",
    "mime_type": "video/mp4",
    "sha256": "02c4e68a4f0d6af5ec6ef02120e20d15f520a4dd473b535abec1aab175c4e8b9"
    }
  }]
}

보안 알림 활성화

show_security_notifications 매개변수가 앱 설정에서 true로 설정된 경우 identity 개체에 포함된 사용자 신원에 대한 다음 정보가 모든 인바운드 메시지 알림에 포함됩니다.

{
  "contacts": [{
		"profile": {
			"name": "Kerry Fisher"
		},
		"wa_id": "16315551234"
	}],
   "messages": [{
        "from": "16315553601",
        "id": "ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
        "identity": {
            "acknowledged": true,
            "created_timestamp": 1602532300000,
            "hash": "Sjvjlx8G6Z0="
        },
        "text": {
            "body": "Hi from new number 3601"
        },
        "timestamp": "1602532300",
        "type": "text"
    }]
}

빠른 답장 버튼 클릭에서 보낸 메시지

고객이 빠른 답장 버튼을 클릭하면 응답이 전송됩니다. 콜백 형식의 예는 다음과 같습니다. 참고: 고객이 버튼을 클릭하지 않고 인터랙티브 메시지에 답장을 하거나 메시지만 보낼 수도 있습니다. 이런 유형의 시나리오도 지원할 수 있는지 확인하세요. 자세한 내용은 Webhooks 문서를 참조하세요. 
{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16505551234"
        }
    ],
    "messages": [
        {
            "button": {
                "payload": "No-Button-Payload",
                "text": "No"
            },
            "context": {
                "from": "16315558007",
                "id": "gBGGFmkiWVVPAgkgQkwi7IORac0"
            },
            "from": "16505551234",
            "id": "ABGGFmkiWVVPAgo-sKD87hgxPHdF",
            "timestamp": "1591210827",
            "type": "button"
        }
    ]
    # If there are any errors, an errors field (array) will be present        
    "errors": [ { ... } ]
}

전송된 메시지에 대한 인바운드 답장

사용자는 WhatsApp에서 특정 메시지에 답장을 보낼 수 있습니다. 비즈니스가 메시지 답장의 컨텍스트를 이해할 수 있도록 context 개체를 포함합니다. 이 context 개체는 고객이 답장한 메시지의 id, 원본 메시지를 보낸 사람의 WhatsApp ID, 고객이 언급할 수 있는 제품의 ID를 제공합니다.

메시지에 답장하기에 자세한 내용이 나와 있습니다.

예: 고객이 메시지에 답장

비즈니스가 발송한 메시지에 답장을 보낸 인바운드 메시지의 예는 다음과 같습니다. 자세한 내용은 아래의 context 개체 섹션을 참조하세요.

{
  "contacts": [ {
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  } ],
   "messages":[{
      "context":{
         "from":"16315558011",
         "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf"
         },
      "from":"16315551234",
      "id":"gBGGFlA5FpafAgkOuJbRq54qwbM",
      "text":{"body":"Yes, count me in!"},
      "timestamp":"1521499915",
      "type":"text"
  }]
}

미디어 메시지에서 text 필드는 선택 사항입니다. 이 필드가 있을 경우 text 값은 전송된 미디어의 캡션이며, 응답이 문자 메시지일 경우 응답 본문이 됩니다.

예: 고객이 리스트 메시지에 답장

{
   "messages": [ {
      "context": {
        "from": "sender_wa_id_of_context_message",
        "group_id": "group_id_of_context_message",
        "id": "message_id_of_context_message",
        "mentions": [ "wa_id1", "wa_id2" ]
      },
      "from": "sender_wa_id",
      "group_id": "group_id",
      "id": "message_id",
      "timestamp": "message_timestamp",
      "type": "interactive",
      "interactive": {
          "type": "list_reply",
          "list_reply": {
            "title": "row-title-content-here",
            "id": "unique-row-identifier-here",
            "description": "row-description-content-here"
          }
      }
   }

예: 고객이 답장 버튼 메시지에 답장

{
  "messages": [ 
    {
      "context": {
        "from": "sender_wa_id_of_context_message",
        "group_id": "group_id_of_context_message",
        "id": "message_id_of_context_message",
        "mentions": [ "wa_id1", "wa_id2" ]
      },
      "from": "sender_wa_id",
      "group_id": "group_id",
      "id": "message_id",
      "timestamp": "message_timestamp",
      "type": "interactive",
      "interactive": {
        "type": "button_reply",
        "button_reply": {
          "id": "unique-button-identifier",
          "title": "button-text"
        }
      } # end interactive node
    } # end message item
  ] # end messages array
}

예: 고객이 특정 제품에 대한 정보 문의

{
  "contacts": [
    {
      "profile": {
        "name": "customer-name"
      },
      "wa_id": "customer-whatsapp-ID"
    }
  ],
  "messages": [
    {
      "from": "customer-whatsapp-ID",
      "id": "message-ID",
      "text": {
        "body": "Can I get this in another color?"
      },
      "context": {
        "referred_product": {
          "catalog_id": "catalog-ID",
          "product_retailer_id": "product-ID"
        }
      },
      "timestamp": "message-received-timestamp",
      "type": "text"
    }
  ]
}

예: 고객이 다중 또는 단일 제품 메시지를 받은 후 주문

{
   "messages": [ {
      "from": "customer-whatsapp-id",
      "group_id": "group-id",
      "id": "message-ID",
      "timestamp": "message-timestamp",
      "type": "order"
      "order": {
         "catalog_id": "catalog_id",
         "product_items": [
            {
            "product_retailer_id":"product-ID",
            "quantity":"number-of-items",
            "item_price":"unitary-price-of-item",
            "currency":"price-currency"
            },
                 ...
         ],
         "text":"text-message-sent-along-with-the-order"
      }
   }
}

인바운드 시스템 메시지

시스템 메시지는 어떤 이벤트가 발생하였을 때 시스템에서 생성합니다.

예: 사용자의 번호 변경

앱 설정에서 notify_user_change_number 매개변수가 true로 설정된 경우 사용자가 전화번호를 변경하면 인바운드 시스템 메시지를 수신합니다.

{
    "messages": [
        {
            "from": "16315558889",
            "id": "ABGGFjFVWIifAzNzeXMtMTYzMTU1NTg4ODlAcy53aGF0c2FwcC5uZXQtMTU3NDA4MDEwMjIxMy1jaGFuZ2U",
            "system": {
                "body": "‎User A changed from ‎+1 (631) 555-8889 to ‎+1 (631) 555-8890‎",
                "new_wa_id": "16315558890",
                "type": "user_changed_number"
            },
            "timestamp": "1574080102",
            "type": "system"
        }
    ]
}

예: 사용자가 변경된 가능성이 있을 경우

앱 설정에서 show_security_notifications 매개변수가 true로 설정되어 있는 경우 WhatsApp에서 (대화 중인) 사용자가 변경되었을 가능성이 있으면 인바운드 시스템 메시지를 수신합니다.

identity 엔드포인트를 사용하여 이 알림을 확인할 때까지 이 사용자에게 발송하는 모든 메시지가 차단됩니다. 수신 메시지는 평소와 같이 계속 수신됩니다.

{
    "messages": [
        {
            "from": "16315553601",
            "id": "ABGGFjFVU2AfAzVzeXMtMTYzMTU1NTM2MDFAcy53aGF0c2FwcC5uZXQtMTYwMjUzNTM1NjMzMi1pZGVudGl0eQ",
            "system": {
  		"body": "Test security code change",
                "identity": "Rc/eg9Rl0JA=",
                "type": "user_identity_changed",
                "user": "16315553601"
            },
            "timestamp": "1602535356",
            "type": "system"
        }
    ]
}

시스템 메시지 유형

시스템 메시지 유형설명

user_changed_number

사용자의 전화번호가 변경되었습니다.

user_identity_changed

WhatsApp에서 사용자가 변경되었을 수 있습니다.

메시지에서 사용자 언급

특정 WhatsApp ID를 직접 언급하는 메시지를 보내고 누군가 이 메시지에 답장을 보내면 context 개체와 mentions 배열에 언급된 ID가 표시됩니다. 전화번호를 두 개 이상 언급할 수 있기 때문에 mentions 필드는 전화번호가 하나만 언급되었더라도 전화번호로 구성된 배열이 됩니다.

예: 고객이 메시지에 답장

언급을 포함한 메시지에 고객이 답장을 보내는 예시는 다음과 같습니다. context 개체에는 원본 메시지에 언급된 번호가 포함됩니다. text 개체의 답장에 같은 번호가 다시 언급됩니다.

{   
  "messages": [{
    "context": {
      "from": "16315555544",
      "id": "gBGGFlA5FpafAgkOuJbRq54qwbM",
      "mentions": [
        "16315551000",
        "16315551099"
      ]
    },
    "from": "16315551234 ",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1504902988",
    "text": {
      "body": "@16315551000 and @16315551099 are mentioned"
    },
    "type": "text"
  }]
}