Phân tích

Tài liệu này mô tả cách lấy dữ liệu phân tích nhắn tin, dữ liệu phân tích cuộc trò chuyện và dữ liệu phân tích mẫu, chẳng hạn như số lượng tin nhắn được gửi từ số điện thoại của doanh nghiệp, số lượng cuộc trò chuyện và chi phí cuộc trò chuyện của Tài khoản WhatsApp Business (WABA) hoặc số lần đọc một mẫu cụ thể.

Phản hồi sẽ chỉ có số liệu về số điện thoại của doanh nghiệp và mẫu được liên kết với WABA của bạn tại thời điểm yêu cầu.

Lấy dữ liệu

Hãy sử dụng điểm cuối Tài khoản WhatsApp Business để lấy dữ liệu phân tích.

Cú pháp truy vấn

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>
  ?fields=<FIELDS>.<FILTERING_PARAMETER>

Thông số chuỗi truy vấn

Dữ liệu phân tích nhắn tin

Trường analytics cung cấp số lượng và loại tin nhắn mà số điện thoại liên kết với một WABA cụ thể đã gửi và phân phối. Hãy xem phần Dữ liệu phân tích cuộc trò chuyện để biết các số liệu về cuộc trò chuyện. Khi gọi /{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters}, bạn có thể đính kèm các thông số dưới đây.

Thông số cho dữ liệu phân tích

Ví dụ

Tình huống: Bạn cần lấy số lượng tin nhắn mà tất cả số điện thoại liên kết với WABA của mình đã gửi và phân phối.

Giải pháp gợi ý:Tập hợp URL bạn muốn gọi rồi thêm các thông số lọc sau: start, end, granularity. Sau đó, gửi yêu cầu GET đến URL đó:

curl -i -X GET \ 
"https://graph.facebook.com/v19.0/{whatsapp-business-account-ID}
      ?fields=analytics
      .start(1543543200)
      .end(1544148000)
      .granularity(DAY)
      &access_token={access-token}"

Phản hồi thành công sẽ trả về đối tượng analytics cùng với dữ liệu bạn đã yêu cầu:

{
  "analytics": {
    "phone_numbers": [
      "16505550111",
      "16505550112",
      "16505550113"
    ],
    "country_codes": [
      "US",
      "BR"
    ],
    "granularity": "DAY",
    "data_points": [
      {
        "start": 1543543200,
        "end": 1543629600,
        "sent": 196093,
        "delivered": 179715
      },
      {
        "start": 1543629600,
        "end": 1543716000,
        "sent": 147649,
        "delivered": 139032
      },
      {
        "start": 1543716000,
        "end": 1543802400,
        "sent": 61988,
        "delivered": 58830
      },
      {
        "start": 1543802400,
        "end": 1543888800,
        "sent": 132465,
        "delivered": 124392
      }
      # more data points
    ]
  },
  "id": "102290129340398"
}

Dữ liệu phân tích cuộc trò chuyện

Trường conversation_analytics cung cấp thông tin về chi phí và cuộc trò chuyện cho một WABA cụ thể. Khi gọi /{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters}, bạn có thể đính kèm các thông số dưới đây.

Thông số cho dữ liệu phân tích cuộc trò chuyện

Ví dụ

Trong một khoảng thời gian, bạn có thể lấy thông tin về cuộc trò chuyện và chi phí liên quan đến WABA của mình. Nếu muốn, bạn có thể lọc và chia nhỏ kết quả. Hãy xem các ví dụ về mã mẫu ở bên dưới.

Lấy dữ liệu hàng tháng, sử dụng tất cả số liệu chia nhỏ

Tình huống: Trong một tháng, bạn muốn truy xuất toàn bộ thông tin về cuộc trò chuyện và chi phí cho tất cả số điện thoại được liên kết với một WABA.

Giải pháp gợi ý:Tập hợp URL bạn muốn gọi rồi thêm các thông số lọc sau:

• start: Bắt đầu khoảng thời gian của bạn. Trường hợp này là đầu tháng mà bạn muốn lấy số liệu.
• end: Kết thúc khoảng thời gian của bạn. Trường hợp này là cuối tháng mà bạn muốn lấy số liệu.
• granularity: Mức độ chi tiết của điểm dữ liệu mà bạn muốn lấy. Trong ví dụ bên dưới, chúng tôi sử dụng MONTHLY nên mỗi điểm dữ liệu sẽ biểu thị một giá trị dữ liệu trong tháng.
• phone_numbers: Hãy gửi một mảng trống và chúng tôi sẽ trả về thông tin cho tất cả số điện thoại được liên kết với WABA đó.
• dimensions: Hãy đặt thông số này thành tất cả số liệu chia nhỏ có sẵn: "CONVERSATION_CATEGORY", "CONVERSATION_TYPE", "COUNTRY" và "PHONE".

Trong trường hợp này, bạn không cần chỉ định country_codes, metric_types, conversation_types và conversation_categories. Nếu bạn không gửi giá trị nào cho những trường đó, chúng tôi sẽ trả về tất cả tùy chọn có sẵn. Sau khi bạn thiết lập URL, hãy gửi yêu cầu GET:

curl -i -X GET
"https://graph.facebook.com/v19.0/{whatsapp-business-account-id}
  ?fields=conversation_analytics
  .start(1685602800).end(1688194800)
  .granularity(MONTHLY)
  .phone_numbers([])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY","PHONE"])
  &access_token={access-token}"

Phản hồi thành công sẽ trả về đối tượng conversation_analytics cùng với dữ liệu bạn đã yêu cầu. Trong ví dụ dưới đây, WABA chỉ chứa một số điện thoại.

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1558,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "AUTHENTICATION",
            "cost": 15.58
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2636,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "MARKETING",
            "cost": 26.36
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2238,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "SERVICE",
            "cost": 22.38
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1782,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "UTILITY",
            "cost": 17.82
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1568,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "AUTHENTICATION",
            "cost": 15.68
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2716,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "MARKETING",
            "cost": 27.16
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2180,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "SERVICE",
            "cost": 21.8
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1465,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "UTILITY",
            "cost": 14.65
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1433,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_ENTRY_POINT",
            "conversation_category": "SERVICE",
            "cost": 14.33
          }
        ]
      }
    ]
  },
  "id": "102290129340398",
}

Lấy dữ liệu cho một số điện thoại cụ thể, sử dụng tất cả số liệu chia nhỏ và mức độ chi tiết là nửa giờ

Tình huống: Trong một khoảng thời gian, bạn muốn truy xuất toàn bộ thông tin về cuộc trò chuyện và chi phí cho một số điện thoại cụ thể được liên kết với WABA. Trong kết quả, bạn muốn sử dụng tất cả số liệu chia nhỏ có thể. Bạn cần có từng điểm dữ liệu để biểu thị một giá trị dữ liệu trong nửa giờ.

Giải pháp gợi ý: Tập hợp URL bạn muốn gọi rồi thêm các thông số lọc sau:

• start: Bắt đầu khoảng thời gian của bạn.
• end: Kết thúc khoảng thời gian của bạn.
• granularity: Mức độ chi tiết của điểm dữ liệu mà bạn muốn lấy. Trong ví dụ bên dưới, chúng tôi sử dụng HALF_HOUR nên mỗi điểm dữ liệu sẽ biểu thị một giá trị dữ liệu trong nửa giờ.
• phone_numbers: Số điện thoại mà bạn cần thông tin.
• dimensions: Hãy đặt thông số này thành tất cả số liệu chia nhỏ có sẵn: CONVERSATION_CATEGORY, CONVERSATION_TYPE, COUNTRY và PHONE.

Trong trường hợp này, bạn không cần chỉ định country_codes, metric_types, conversation_types hoặc conversation_categories. Nếu bạn không gửi giá trị nào cho những trường đó, chúng tôi sẽ trả về tất cả tùy chọn có sẵn. Sau khi bạn thiết lập URL, hãy gửi yêu cầu GET:

curl -i -X GET \
"https://graph.facebook.com/v19.0/{whatsapp-business-account-id}
  ?fields=conversation_analytics
  .start(1685602800)
  .end(1685689200)
  .granularity(HALF_HOUR)
  .phone_numbers(["19195552584"])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY,PHONE"])
  &access_token=your-access-token"

Phản hồi thành công sẽ trả về đối tượng conversation_analytics cùng với dữ liệu bạn đã yêu cầu:

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685602800,
            "end": 1685604600,
            "conversation": 4,
            "phone_number": "19195552584",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "SERVICE",
            "cost": 0.0232
          },
          {
            "start": 1685602800,
            "end": 1685604600,
            "conversation": 4,
            "phone_number": "19195552584",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "MARKETING",
            "cost": 0.0232
          },
         # ... more data points
        ]
      }
    ]
  },
  "id": "102290129340398"
}

Lấy dữ liệu hàng tháng, sử dụng số liệu chia nhỏ theo loại cuộc trò chuyện

Tình huống: Trong một khoảng thời gian, bạn muốn truy xuất toàn bộ thông tin về cuộc trò chuyện và chi phí cho tất cả số điện thoại được liên kết với một WABA. Trong kết quả, bạn muốn chia nhỏ theo loại cuộc trò chuyện.

Giải pháp gợi ý: Tập hợp URL bạn muốn gọi rồi thêm các thông số lọc sau:

• start: Bắt đầu khoảng thời gian của bạn.
• end: Kết thúc khoảng thời gian của bạn.
• granularity: Mức độ chi tiết của điểm dữ liệu mà bạn muốn lấy. Trong ví dụ bên dưới, chúng tôi sử dụng MONTHLY nên mỗi điểm dữ liệu sẽ biểu thị một giá trị dữ liệu trong nửa tháng.
• phone_numbers: Hãy gửi một mảng trống và chúng tôi sẽ trả về thông tin cho tất cả số điện thoại được liên kết với WABA đó.
• dimensions: Hãy đặt thông số này thành CONVERSATION_TYPE.

Trong trường hợp này, bạn không cần chỉ định country_codes, metric_types, conversation_types, conversation_directions hoặc conversation_categories. Nếu bạn không gửi giá trị nào cho những trường này, chúng tôi sẽ trả về tất cả tùy chọn có sẵn. Sau khi bạn thiết lập URL, hãy gửi yêu cầu GET:

curl -i -X GET
"https://graph.facebook.com/v19.0/{whatsapp-buiness-account-id}
      ?fields=conversation_analytics
      .start(1643702400).end(1646121600)
      .granularity(MONTHLY)
      .phone_numbers([])
      .dimensions([CONVERSATION_TYPE])
      &access_token={access-token}"

Phản hồi thành công sẽ trả về đối tượng conversation_analytics cùng với dữ liệu bạn đã yêu cầu:

{
  "data": [
    {
      "data_points": [
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation": 8500,
          "conversation_type": "REGULAR",
          "cost": 88.1010
        },
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation”: 1000,
          "conversation_type": "FREE_TIER",
          "cost": 0.0000
        }
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation”: 250,
          "conversation_type": "FREE_ENTRY_POINT",
          "cost": 0.0000
        }
      ]
    }
  ]
}

Chia nhỏ dữ liệu trong nửa giờ theo hạng mục cuộc trò chuyện

Yêu cầu:

curl -i -X GET \
 "https://graph.facebook.com/v19.0/{whatsapp-buiness-account-id}
  ?fields=conversation_analytics
  .start(1685527200)
  .end(1685613600)
  .granularity(HALF_HOUR)
  .conversation_categories(["MARKETING","AUTHENTICATION"])
  .dimensions(["CONVERSATION_CATEGORY"])
  &access_token={access-token}"  

Phản hồi:

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685529000,
            "end": 1685530800,
            "conversation": 2,
            "conversation_category": "AUTHENTICATION",
            "cost": 0.0128
          },
          {
            "start": 1685527200,
            "end": 1685529000,
            "conversation": 3,
            "conversation_category": "MARKETING",
            "cost": 0.0432
          }
        ]
      }
    ]
  },
  "id": "102290129340398"
}

#### Chia nhỏ dữ liệu trong nửa giờ theo loại cuộc trò chuyện và hạng mục cuộc trò chuyện

Yêu cầu:

curl -i -X GET \
 "https://graph.facebook.com/v19.0/{whatsapp-buiness-account-id}
  ?fields=conversation_analytics
  .start(1685527200)
  .end(1685613600)
  .granularity(HALF_HOUR)
  .conversation_categories(["MARKETING","AUTHENTICATION"])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE"])
  &access_token={access-token}"  

Phản hồi:

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685527200,
            "end": 1685529000,
            "conversation": 3,
            "conversation_type": "REGULAR",
            "conversation_category": "MARKETING",
            "cost": 0.0432
          },
          {
            "start": 1685529000,
            "end": 1685530800,
            "conversation": 2,
            "conversation_type": "REGULAR",
            "conversation_category": "AUTHENTICATION",
            "cost": 0.0128
          }
        ]
      }
    ]
  },
  "id": "102290129340398"
}

Dữ liệu phân tích mẫu

Dữ liệu phân tích mẫu mô tả số lần gửi, phân phối và đọc mẫu, cũng như số lượt click vào nút URL hoặc nút Câu trả lời nhanh trong mẫu.

Dữ liệu được trả về với mức độ chi tiết hàng ngày ở múi giờ UTC và khoảng thời gian xem lại lên đến 90 ngày. Bạn cũng có thể tìm thấy dữ liệu phân tích mẫu trong bảng điều khiển Trình quản lý WhatsApp > Mẫu tin nhắn > Chi tiết mẫu > Thông tin chi tiết.

Giới hạn

• Dữ liệu phân tích mẫu chỉ dùng được cho API Tại chỗ nếu tài khoản này chưa chọn sử dụng dữ liệu phân tích mẫu của API Đám mây.
• Dữ liệu phân tích mẫu của API Tại chỗ phải tuân theo các nguyên tắc tổng hợp và ẩn danh. Nguyên tắc này yêu cầu phải có tối thiểu 1.000 sự kiện trước khi hiển thị số lượng cho người dùng.
• Chỉ các mẫu được phân loại là MARKETING hoặc UTILITY mới có dữ liệu phân tích lượt click vào nút.
• Những WABA thuộc sở hữu của/được chia sẻ với các Tài khoản kinh doanh trên Meta ở Liên minh châu Âu, Vương quốc Anh, Nhật Bản hoặc sở hữu số điện thoại của doanh nghiệp có mã vùng quốc gia từ bất kỳ quốc gia/khu vực nào trong số này sẽ không được hỗ trợ.

Báo cáo lỗi

Để báo cáo lỗi dữ liệu phân tích mẫu, hãy gửi phiếu yêu cầu Hỗ trợ trực tiếp với các lựa chọn sau đây:

• Chủ đề câu hỏi: WABiz: API Đám mây
• Loại yêu cầu: Lỗi hoặc sự cố triển khai

Xác nhận dữ liệu phân tích mẫu

Bạn phải xác nhận dữ liệu phân tích mẫu trên Tài khoản WhatsApp Business thì mới có thể lấy dữ liệu phân tích mẫu. Bạn có thể xác nhận dữ liệu phân tích mẫu bằng API hoặc Trình quản lý WhatsApp. Nếu bạn muốn xác nhận qua API, hãy gửi yêu cầu sau đây:

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>?is_enabled_for_insights=true

Sau khi được xác nhận, chúng tôi sẽ bắt đầu thu thập dữ liệu phân tích mẫu cho Tài khoản WhatsApp Business. Bạn không thể vô hiệu hóa dữ liệu phân tích mẫu sau khi được xác nhận.

Khi thành công, API sẽ phản hồi bằng ID Tài khoản WhatsApp Business của bạn. Ví dụ:

{                          
  "id": 102290129340398
}

Thông số cho dữ liệu phân tích mẫu

Ví dụ

Lấy tất cả dữ liệu phân tích mẫu

Tình huống: Trong khoảng thời gian 2 ngày, hãy lấy tất cả dữ liệu phân tích mẫu có sẵn cho một mẫu tin nhắn được liên kết với Tài khoản WhatsApp Business.

Yêu cầu mẫu:

curl -g 'https://graph.facebook.com/v19.0/109259195336416/template_analytics?start=1689379200&end=1689552000&granularity=DAILY&metric_types=[%27SENT%27%2C%27DELIVERED%27%2C%27READ%27%2C%27CLICKED%27]&template_ids=[1924084211297547%2C954638012257287]' \
-H 'Authorization: Bearer EABN8...'

Phản hồi mẫu:

{
  "data": [
    {
      "granularity": "DAILY",
      "data_points": [
        {
          "template_id": "1924084211297547",
          "start": 1689379200,
          "end": 1689465600,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "quick_reply_button",
              "button_content": "Tell me more",
              "count": 3
            },
            {
              "type": "quick_reply_button",
              "button_content": "Get coupon",
              "count": 5
            }
          ]
        },
        {
          "template_id": "1924084211297547",
          "start": 1689465600,
          "end": 1689552000,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "quick_reply_button",
              "button_content": "Tell me more",
              "count": 73
            },
            {
              "type": "quick_reply_button",
              "button_content": "Get coupon",
              "count": 35
            }
          ]
        },
        {
          "template_id": "954638012257287",
          "start": 1689379200,
          "end": 1689465600,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "url_button",
              "button_content": "Visit Website",
              "count": 13
            }
          ]
        },
        {
          "template_id": "954638012257287",
          "start": 1689465600,
          "end": 1689552000,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "url_button",
              "button_content": "Visit Website",
              "count": 12
            }
          ]
        }
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MjQZD"
    }
  }
}

Vô hiệu hóa dữ liệu phân tích lượt click vào nút

Bạn có thể vô hiệu hóa tùy chọn theo dõi lượt click vào nút trên từng mẫu bằng cách đặt trường cta_url_link_tracking_opted_out của mẫu đó thành true. Sau khi bạn vô hiệu hóa, API sẽ không còn trả về tài sản được nhấp trong dữ liệu phân tích mẫu hoặc hiển thị lượt tương tác/lượt click vào nút trong Trình quản lý WhatsApp khi xem thông tin chi tiết của mẫu.

Cú pháp yêu cầu

POST /<TEMPLATE_ID>
  ?cta_url_link_tracking_opted_out=<OPT_OUT>
  &category=<TEMPLATE_CATEGORY>

Thông số yêu cầu

Yêu cầu mẫu

curl -X POST 'https://graph.facebook.com/v19.0/245435364965041?cta_url_link_tracking_opted_out=true&category=marketing' \
-H 'Authorization: Bearer EAAJB...'

Phản hồi mẫu

Sau khi thành công, API này sẽ phản hồi kèm theo:

{
    "success": true
}

Tài liệu tham khảo

Để biết danh sách tất cả các giá trị có thể dùng cho từng trường, hãy xem tài liệu tham khảo về API Đồ thị của trường Dữ liệu phân tích về tài khoản WhatsApp Business.