Số điện thoại

Hướng dẫn này sẽ chỉ cho bạn cách xác minh số điện thoại và định dạng bắt buộc của số điện thoại đối với API Đám mây.

Chúng tôi có đưa ra tiêu chí về loại số điện thoại mà bạn có thể thêm vào Tài khoản WhatsApp Business (WABA). Vui lòng xem phần Số điện thoại để biết thêm thông tin.

Đối với một số lệnh gọi API được liệt kê, bạn cần phải biết ID số điện thoại của mình. Hãy tham khảo phần Lấy tất cả số điện thoại để biết cách lấy những số điện thoại được liên kết với WABA của bạn. Phản hồi API sẽ bao gồm ID của từng số điện thoại được kết nối với Tài khoản WhatsApp Business của bạn. Hãy lưu ID của số điện thoại mà bạn muốn dùng với bất kỳ lệnh gọi /PHONE_NUMBER_ID nào.

Xác minh số điện thoại

Bạn cần xác minh số điện thoại mà mình muốn dùng để gửi tin nhắn cho khách hàng. Số điện thoại phải được xác minh bằng mã mà chúng tôi gửi qua SMS/cuộc gọi thoại. Bạn có thể thực hiện quy trình xác minh này thông qua lệnh gọi API Đồ thị được chỉ định ở bên dưới.

Để xác minh số điện thoại bằng API Đồ thị, bạn cần gửi yêu cầu POST đến PHONE_NUMBER_ID/request_code. Trong lệnh gọi này, hãy thêm phương thức xác minh và ngôn ngữ bạn đã chọn.

Thông số

Ví dụ

Yêu cầu mẫu:

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'

Sau khi thực hiện lệnh gọi API này, bạn sẽ nhận được mã xác minh qua phương thức mình đã chọn. Để hoàn tất quy trình xác minh, bạn cần thêm mã đó vào yêu cầu POST đến PHONE_NUMBER_ID/verify_code.

Thông số

Ví dụ

Yêu cầu mẫu:

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

Phản hồi thành công có dạng như sau:

{
  "success": true
}

Kiểm tra thay đổi danh tính

Bạn nên yêu cầu chúng tôi xác minh danh tính của khách hàng trước khi chúng tôi phân phối tin nhắn của bạn cho họ. Bạn có thể yêu cầu chúng tôi làm vậy bằng cách bật cài đặt kiểm tra thay đổi danh tính trên số điện thoại của doanh nghiệp bạn.

Nếu khách hàng thực hiện một hành động trong WhatsApp mà chúng tôi xem là sự thay đổi danh tính, chúng tôi sẽ tạo một hash danh tính mới cho người dùng đó. Bạn có thể lấy hash này mỗi khi nhắn tin cho khách hàng bằng cách bật cài đặt kiểm tra thay đổi danh tính trên số điện thoại của doanh nghiệp bạn. Sau khi bạn bật cài đặt này, mỗi khi khách hàng nhắn tin cho bạn hoặc bạn nhắn tin cho khách hàng mà không có hash danh tính, chúng tôi sẽ thêm hash của khách hàng vào mọi webhook tin nhắn đến hoặc webhook trạng thái phân phối. Sau đó, bạn có chụp và lưu trữ hash này để sử dụng trong tương lai.

Nếu bạn muốn sử dụng hash nêu trên, hãy thêm hash đó vào yêu cầu gửi tin nhắn. Chúng tôi sẽ so sánh hash trong yêu cầu với hash hiện tại của khách hàng. Nếu hash khớp, hệ thống sẽ phân phối tin nhắn. Nếu hash không khớp thì tức là khách hàng đã thay đổi danh tính kể từ lần gần nhất bạn nhắn tin cho họ. Trong trường hợp này, chúng tôi sẽ không phân phối tin nhắn. Thay vào đó, chúng tôi sẽ gửi cho bạn webhook trạng thái tin nhắn có chứa mã lỗi 137000 để thông báo về lỗi và tình trạng không khớp.

Khi bạn nhận được webhook hash không khớp, hãy xem như số điện thoại của khách hàng không còn đáng tin cậy nữa. Để khôi phục độ tin cậy, hãy xác minh lại danh tính của khách hàng bằng các kênh khác không phải WhatsApp. Sau khi bạn khôi phục độ tin cậy, hãy gửi lại tin nhắn bị lỗi cho danh tính mới (nếu có) mà không cần hash. Sau đó, hãy lưu trữ hash mới của khách hàng có trong webhook trạng thái phân phối tin nhắn.

Cú pháp yêu cầu

Gửi yêu cầu POST đến điểm cuối Số điện thoại WhatsApp Business > Cài đặt để bật hoặc tắt cài đặt kiểm tra thay đổi danh tính.

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/settings

Nội dung yêu cầu POST

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

Đặt <ENABLE_IDENTITY_KEY_CHECK> là true để bật cài đặt kiểm tra danh tính hoặc đặt là false để tắt cài đặt đó.

Ví dụ về yêu cầu bật

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
  }
}'

Ví dụ về phản hồi bật

{
  "success": true
}

Ví dụ về yêu cầu gửi tin nhắn có kiểm tra

Hệ thống sẽ chỉ phân phối tin nhắn mẫu dưới đây nếu giá trị hash recipient_identity_key_hash khớp với hash hiện tại của khách hàng.

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... "
    }
}'

Ví dụ về webhook tin nhắn đến

Trong webhook tin nhắn đến, hash của khách hàng được chỉ định cho thuộc tính 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"
        }
      ]
    }
  ]
}

Ví dụ về webhook trạng thái phân phối

Trong webhook trạng thái phân phối, hash của khách hàng được chỉ định cho thuộc tính 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"
        }
      ]
    }
  ]
}

Ví dụ về webhook trạng thái phân phối không thành công

Trong webhook trạng thái phân phối, hash của khách hàng được chỉ định cho thuộc tính 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"
        }
      ]
    }
  ]
}

Lấy mức thông lượng

Sử dụng điểm cuối Số điện thoại WhatsApp Business để lấy mức thông lượng hiện tại của một số điện thoại:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput