Trạng thái nhắn tin

Tài liệu này mô tả cách xác định xem bạn có thể gửi tin nhắn thành công bằng một tài nguyên API cụ thể hay không.

Dưới đây là các nút có trường health_status:

• Tài khoản WhatsApp Business
• Số điện thoại WhatsApp Business
• Mẫu tin nhắn WhatsApp

Nếu bạn yêu cầu trường health_status trên bất kỳ nút nào trong số này, API sẽ trả về phần tóm tắt tình trạng nhắn tin của tất cả các nút liên quan đến yêu cầu nhắn tin trong trường hợp sử dụng nút được nhắm mục tiêu. Phần tóm tắt này cho biết liệu bạn có thể sử dụng API để gửi tin nhắn thành công hay không, khả năng bạn gửi thành công có bị hạn chế do một số giới hạn trên một/nhiều nút hay không hoặc bạn có bị chặn nhắn tin hoàn toàn hay không.

Cú pháp yêu cầu

GET /<NODE_ID>?fields=health_status

Phản hồi

{
  "health_status": {
    "can_send_message": "<OVERALL_MESSAGING_STATUS>",
    "entities": [
    
      /* Only included if targeting a business phone number */
      {
        "entity_type": "PHONE_NUMBER",
        "id": "<BUSINESS_PHONE_NUMBER_ID>",
        "can_send_message": "<BUSINESS_PHONE_NUMBER_MESSAGING_STATUS>"
      },
      
      /* Only included if targeting a template */
      {
        "entity_type": "MESSAGE_TEMPLATE",
        "id": "<TEMPLATE_ID>",
        "can_send_message": "<TEMPLATE_MESSAGING_STATUS>"
      },
      
      /* WABA, business, and app always included */
      {
        "entity_type": "WABA",
        "id": "<WABA_ID>",
        "can_send_message": "<WABA_MESSAGING_STATUS>"
      },
      {
        "entity_type": "BUSINESS",
        "id": "<BUSINESS_PORTFOLIO_ID>",
        "can_send_message": "<BUSINESS_PORTFOLIO_MESSAGING_STATUS>"
      },
      {
        "entity_type": "APP",
        "id": "<APP_ID>",
        "can_send_message": "<APP_MESSAGING_STATUS>"
      }
    ]
  },
  "id": "<NODE_ID>"
}

Nội dung phản hồi

Trạng thái nhắn tin

Khi bạn cố gửi một tin nhắn, nhiều nút sẽ có liên quan, bao gồm cả ứng dụng, hồ sơ doanh nghiệp sở hữu hoặc đã xác nhận quyền sở hữu ứng dụng đó, một WABA, một số điện thoại của doanh nghiệp và một mẫu (trong trường hợp gửi tin nhắn mẫu).

Thuộc tính can_send_message của mỗi nút trong số này có thể được chỉ định một trong những trạng thái sau đây:

• AVAILABLE: Cho biết nút này đáp ứng tất cả các yêu cầu nhắn tin.
• LIMITED: Cho biết nút này đáp ứng các yêu cầu nhắn tin nhưng có một số giới hạn. Nếu một nút cụ thể có giá trị này, phản hồi sẽ có cả thuộc tính thông tin bổ sung.
• BLOCKED: Cho biết nút này không đáp ứng một hoặc nhiều yêu cầu nhắn tin. Nếu một nút cụ thể có giá trị này, phản hồi sẽ có cả thuộc tính lỗi. Thuộc tính này mô tả lỗi và giải pháp khả thi.

Trạng thái chung

Thuộc tính trạng thái chung (health_status.can_send_message) sẽ được đặt như sau:

• Nếu một hoặc nhiều nút bị chặn, thuộc tính này sẽ được đặt thành BLOCKED.
• Nếu không có nút nào bị chặn nhưng một hoặc nhiều nút bị giới hạn, thuộc tính này sẽ được đặt thành LIMITED.
• Nếu tất cả các nút đều hoạt động, thuộc tính này sẽ được đặt thành AVAILABLE.

Yêu cầu mẫu

curl 'https://graph.facebook.com/v21.0/106540352242922?fields=health_status' \
-H 'Authorization: Bearer EAAJB'

Phản hồi mẫu

{
  "health_status": {
    "can_send_message": "AVAILABLE",
    "entities": [
      {
        "entity_type": "PHONE_NUMBER",
        "id": "106540352242922",
        "can_send_message": "AVAILABLE"
      },
      {
        "entity_type": "WABA",
        "id": "102290129340398",
        "can_send_message": "AVAILABLE"
      },
      {
        "entity_type": "BUSINESS",
        "id": "506914307656634",
        "can_send_message": "AVAILABLE"
      },
      {
        "entity_type": "APP",
        "id": "634974688087057",
        "can_send_message": "AVAILABLE"
      }
    ]
  },
  "id": "106540352242922"
}

Thuộc tính thông tin bổ sung

Nếu thuộc tính can_send_message của một nút cụ thể được đặt thành LIMITED, phản hồi sẽ có cả thuộc tính additional_info. Thuộc tính này cung cấp ngữ cảnh bổ sung cho giới hạn.

Phản hồi mẫu cho trường hợp bị giới hạn

Dưới đây là phản hồi mẫu cho yêu cầu trên một số điện thoại của doanh nghiệp. Số này có thể được dùng để gửi tin nhắn, nhưng bị giới hạn số lượng tin nhắn có thể gửi do tên hiển thị của số đó chưa được phê duyệt.

{
  "health_status": {
    "can_send_message": "LIMITED",
    "entities": [
      {
        "entity_type": "PHONE_NUMBER",
        "id": "106540352242922",
        "can_send_message": "LIMITED",
        "additional_info": [
          "Your display name has not been approved yet. Your message limit will increase after the display name is approved."
        ]
      },
      {
        "entity_type": "WABA",
        "id": "102290129340398",
        "can_send_message": "AVAILABLE"
      },
      {
        "entity_type": "BUSINESS",
        "id": "506914307656634",
        "can_send_message": "AVAILABLE"
      },
      {
        "entity_type": "APP",
        "id": "634974688087057",
        "can_send_message": "AVAILABLE"
      }
    ]
  },
  "id": "105154286024403"
}

Thuộc tính lỗi

Nếu thuộc tính can_send_message của một nút cụ thể được đặt thành BLOCKED, phản hồi sẽ có cả thuộc tính errors. Thuộc tính này mô tả nguyên nhân dẫn đến trạng thái đó và giải pháp khả thi.

Phản hồi mẫu cho trường hợp bị chặn

Dưới đây là phản hồi mẫu cho yêu cầu trên một mẫu. Mẫu này không gửi được trong tin nhắn mẫu do mẫu vẫn ở trạng thái đang chờ.

{
  "health_status": {
    "can_send_message": "BLOCKED",
    "entities": [
      {
        "entity_type": "MESSAGE_TEMPLATE",
        "id": "2632273056924580",
        "can_send_message": "BLOCKED",
        "errors": [
          {
            "error_code": 141002,
            "error_description": "Message templates can only be sent out if they are approved.",
            "possible_solution": "Edit or appeal the message template review decision."
          }
        ]
      },
      {
        "entity_type": "WABA",
        "id": "102290129340398",
        "can_send_message": "AVAILABLE"
      },
      {
        "entity_type": "BUSINESS",
        "id": "506914307656634",
        "can_send_message": "AVAILABLE"
      },
      {
        "entity_type": "APP",
        "id": "634974688087057",
        "can_send_message": "AVAILABLE"
      }
    ]
  },
  "id": "2632273056924580"
}