전화번호

이 가이드에서는 전화번호 및 클라우드 API 필요 형식을 인증하는 방법을 설명합니다.

WhatsApp Business 계정(WABA)에 추가할 수 있는 전화번호의 유형에는 기준이 있습니다. 자세한 내용은 전화번호를 참조하세요.

리스트에 있는 일부 API의 경우 호출을 보낼 때 전화번호 ID를 알아야 합니다. WABA와 연결된 전화번호를 가져오는 방법은 모든 전화번호 가져오기를 참조하세요. API 호출 응답에는 WhatsApp Business 계정과 연결된 각 전화번호의 ID가 포함되어 있습니다. /PHONE_NUMBER_ID 호출과 함께 사용할 전화번호의 ID를 저장하세요.

전화번호 인증

고객에게 메시지를 보내는 데 사용하려는 전화번호를 인증해야 합니다. 전화번호는 SMS/음성 통화를 통해 전송된 코드를 사용하여 인증해야 합니다. 인증 절차는 아래에 지정된 그래프 API 호출을 통해 처리할 수 있습니다.

그래프 API를 사용하여 전화번호를 인증하려면 PHONE_NUMBER_ID/request_code로 POST 요청을 보내세요. 호출 시 선택한 인증 방법과 언어를 포함하세요.

매개변수

예

요청 샘플:

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/request_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code_method=SMS' 
  -F 'locale=en_US'

API 호출을 보내고 나면 선택한 방법을 통해 인증 코드를 받게 됩니다. 인증 절차를 완료하려면 PHONE_NUMBER_ID/verify_code로 보내는 POST 요청에 코드를 포함하세요.

매개변수

예

요청 샘플:

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/verify_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code=000000'

성공적인 응답은 다음과 같습니다.

{
  "success": true
}

신원 변경 확인

고객에게 메시지를 전달하기 전에 고객의 신원을 확인해야 할 수도 있습니다. 비즈니스 전화번호에서 신원 변경 확인 설정을 활성화하여 WhatsApp에서 이를 대신 처리하도록 할 수 있습니다.

고객이 WhatsApp에서 신원 변경에 해당하는 작업을 수행할 경우 해당 사용자에 대해 새로운 신원 해시가 생성됩니다. 비즈니스 전화번호에서 신원 변경 확인 설정을 활성화하면 고객에게 메시지를 보낼 때마다 이 해시를 받을 수 있습니다. 신원 변경 확인 설정이 활성화되면 신원 해시 없이 고객이 비즈니스에 메시지를 보내거나 비즈니스가 고객에게 메시지를 보낼 때 WhatsApp가 수신되는 메시지 Webhooks 또는 전송 상태 Webhooks에 해시를 포함합니다. 그러면 나중에 사용할 수 있도록 이 해시를 캡처하고 저장할 수 있습니다.

해시를 사용하려면 메시지 전송 요청에 포함하세요. WhatsApp에서 요청의 해시와 고객의 현재 해시를 비교합니다. 해시가 일치하면 메시지가 전송됩니다. 해시가 일치하지 않는 경우 비즈니스가 고객에게 마지막으로 메시지를 보낸 이후 고객이 신원을 변경했다는 것을 의미하며, WhatsApp이 메시지를 전송하지 않습니다. 대신 오류 코드 137000가 포함된 메시지 상태 Webhooks를 보내서 전송 실패 및 불일치에 대해 알려드립니다.

일치하지 않는 해시 Webhooks를 받으면 고객의 전화번호를 더 이상 신뢰할 수 없다고 간주하세요. 다시 신뢰 관계를 구축하려면 WhatsApp이 아닌 다른 채널을 사용하여 고객의 신원을 다시 확인하세요. 신뢰를 다시 구축하고 나면 실패한 메시지를 해시 없이 새로운 신원(있는 경우)으로 다시 보내세요. 그런 다음, 메시지 상태 전송 Webhooks에 포함된 고객의 새로운 해시를 저장하세요.

요청 구문

WhatsApp Busisness 전화번호 > 설정 엔드포인트로 POST 요청을 보내서 신원 변경 확인 설정을 활성화하거나 비활성화합니다.

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/settings

POST 본문

{
  "user_identity_change" : {
    "enable_identity_key_check": <ENABLE_IDENTITY_KEY_CHECK>
}

<ENABLE_IDENTITY_KEY_CHECK>를 true로 설정하면 신원 확인이 활성화되고 false로 설정하면 비활성화됩니다.

활성화 요청 예시

curl 'https://graph.facebook.com/v21.0/106850078877666/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "user_identity_change": {
    "enable_identity_key_check": true
  }
}'

활성화 응답 예시

{
  "success": true
}

확인을 포함한 메시지 전송 예시

이 예시 메시지는 recipient_identity_key_hash 해시 값이 고객의 현재 해시와 일치하는 경우에만 전달됩니다.

curl 'https://graph.facebook.com/v21.0/106850078877666/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "+16505551234",
    "recipient_identity_key_hash": "DF2lS5v2W6x=",
    "type": "text",
    "text": {
        "preview_url": false,
        "body": "Your latest statement is attached. See... "
    }
}'

수신되는 메시지 Webhooks 예시

수신되는 메시지 Webhooks에서 고객의 해시가 identity_key_hash 속성에 할당됩니다.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo Morales"
                },
                "wa_id": "16505551234",
                "identity_key_hash": "DF2lS5v2W6x="
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUMyNTA4M0VGN0Q4RjdDNDVCMAA=",
                "timestamp": "1686591695",
                "text": {
                  "body": "Your latest statement is attached. See... "
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

전송 상태 Webhooks 예시

전송 상태 Webhooks에서 고객의 해시가 recipient_identity_key_hash 속성에 할당됩니다.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJGODlDQjZBNjUxMUQ5NEU0MEUA",
                "status": "delivered",
                "timestamp": "1686591922",
                "recipient_id": "16505551234",
                "recipient_identity_key_hash": "DF2lS5v2W6x=",
                "conversation": {
                  "id": "6c84493f3de086c7c68d5a39248f72c0",
                  "origin": {
                    "type": "service"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "service"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

실패한 전송 상태 Webhooks 예시

전송 상태 Webhooks에서 고객의 해시가 recipient_identity_key_hash 속성에 할당됩니다.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJDQzA0OEU4OTdEQUE5REVCQTgA",
                "status": "failed",
                "timestamp": "1686594665",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 137000,
                    "title": "Confirm the correct Recipient Identity Key Hash or send without any identity key hash"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

처리량 수준 가져오기

WhatsApp Business 전화번호 엔드포인트를 사용하여 전화번호의 현재 처리량 수준을 가져옵니다.

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput