분석

이 문서에서는 메시지, 대화, 템플릿 분석(예: 비즈니스 전화번호에서 보낸 메시지 수, 대화 수, WhatsApp Business 계정(WABA)에 발생하는 비용, 특정 템플릿이 읽힌 횟수)을 가져오는 방법을 설명합니다.

요청 시점에 WABA와 연결된 비즈니스 전화번호 및 템플릿에 대한 지표만 응답에 포함됩니다.

데이터 가져오기

WhatsApp Business 계정 엔드포인트를 사용하여 분석을 가져옵니다.

쿼리 구문

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

쿼리 문자열 매개변수

메시지 분석

analytics 필드는 특정 WABA와 연결된 전화번호에서 전송하고 전달한 메시지의 개수와 유형을 제공합니다. 전환 지표의 경우 전환 분석을 참조하세요. /{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters}를 호출하면 다음의 매개변수를 연결할 수 있습니다.

분석 매개변수

예

시나리오: WABA와 연결된 모든 전화번호에서 전송하고 전달한 메시지의 개수를 가져와야 합니다.

추천 솔루션:호출하고자 하는 URL을 결합하고 필터링 매개변수 start, end, granularity를 포함합니다. 그런 다음 해당 URL로 GET 요청을 보냅니다.

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

성공 시 응답은 요청한 데이터와 함께 analytics 개체를 반환합니다.

{
  "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"
}

대화 분석

conversation_analytics 필드는 특정 WABA에 대한 비용 및 대화 정보를 제공합니다. /{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters}를 호출하면 다음의 매개변수를 연결할 수 있습니다.

대화 분석 매개변수

예

특정 시간 범위에 대해 WABA와 관련된 대화 및 비용 정보를 가져올 수 있습니다. 원한다면 결과를 필터링하고 분석할 수 있습니다. 예시는 아래의 코드 샘플을 참조하세요.

모든 분석 데이터를 사용하여 월간 데이터 가져오기

시나리오: 특정 월에 대해 WABA와 연결된 모든 전화번호에 대한 모든 대화 및 비용 정보를 조회하고자 합니다.

추천 솔루션:호출하고자 하는 URL을 결합하고 다음의 필터링 매개변수를 포함합니다.

• start: 시간 범위의 시작입니다. 이 경우 지표를 가져오고자 하는 월의 시작입니다.
• end: 시간 범위의 끝입니다. 이 경우 지표를 가져오고자 하는 월의 끝입니다.
• granularity: 데이터 포인트의 세분화 수준입니다. 아래의 예시에서는 MONTHLY를 사용하므로 각 데이터 포인트는 한 달 분량의 데이터를 나타냅니다.
• phone_numbers: 빈 배열을 보내면 WABA와 연결된 모든 전화번호에 대한 정보가 반환됩니다.
• dimensions: 모든 사용 가능한 분석 데이터("CONVERSATION_CATEGORY", "CONVERSATION_TYPE", "COUNTRY" 및 "PHONE")로 설정합니다.

이 경우에는 country_codes, metric_types, conversation_types 및 conversation_categories를 지정할 필요가 없습니다. 해당 필드에 대해 Meta에 아무것도 전송하지 않으면 모든 사용 가능한 옵션이 반환됩니다. URL을 설정하고 나면 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}"

성공 시 응답은 요청한 데이터와 함께 conversation_analytics 개체를 반환합니다. 다음 예시에서 WABA는 전화번호를 하나만 포함합니다.

{
  "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",
}

모든 분석 데이터와 세분화 수준 30분을 사용하여 특정 전화번호에 대한 데이터 가져오기

시나리오: 특정 시간 범위에 대해 WABA와 연결된 특정 전화번호에 대한 모든 대화 및 비용 정보를 조회하고자 합니다. 결과에서 모든 가능한 분석 데이터를 사용하려고 합니다. 각 데이터 포인트는 30분 분량의 데이터를 나타내야 합니다.

추천 솔루션: 호출하고자 하는 URL을 결합하고 다음의 필터링 매개변수를 포함합니다.

• start: 시간 범위의 시작입니다.
• end: 시간 범위의 끝입니다.
• granularity: 데이터 포인트의 세분화 수준입니다. 아래의 예시에서는 HALF_HOUR를 사용하므로 각 데이터 포인트는 30분 분량의 데이터를 나타냅니다.
• phone_numbers: 관련 정보가 필요한 전화번호입니다.
• dimensions: 모든 사용 가능한 분석 데이터(CONVERSATION_CATEGORY, CONVERSATION_TYPE, COUNTRY 및 PHONE)로 설정합니다.

이 경우 country_codes, metric_types, conversation_types 또는 conversation_categories를 지정할 필요가 없습니다. 해당 필드에 대해 Meta에 아무것도 전송하지 않으면 모든 사용 가능한 옵션이 반환됩니다. URL을 설정하고 나면 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"

성공 시 응답은 요청한 데이터와 함께 conversation_analytics 개체를 반환합니다.

{
  "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"
}

대화 유형 분석 데이터를 사용하여 월별 데이터 가져오기

시나리오: 특정 시간 범위에 대해 WABA와 연결된 모든 전화번호에 대한 대화 및 비용 정보를 조회하고자 합니다. 결과에서 대화 유형별로 분석하려고 합니다.

추천 솔루션: 호출하고자 하는 URL을 결합하고 다음 필터링 매개변수를 포함합니다.

• start: 시간 범위의 시작입니다.
• end: 시간 범위의 끝입니다.
• granularity: 데이터 포인트의 세분화 수준입니다. 아래의 예시에서는 MONTHLY를 사용하므로 각 데이터 포인트는 반 개월 분량의 데이터를 나타냅니다.
• phone_numbers: 빈 배열을 보내면 WABA와 연결된 모든 전화번호에 대한 정보가 반환됩니다.
• dimensions: CONVERSATION_TYPE으로 설정합니다.

이 경우에는 country_codes, metric_types, conversation_types, conversation_directions 또는 conversation_categories를 지정할 필요가 없습니다. 해당 필드에 대해 Meta에 아무것도 전송하지 않으면 모든 사용 가능한 옵션이 반환됩니다. URL을 설정하고 나면 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}"

성공 시 응답은 요청한 데이터와 함께 conversation_analytics 개체를 반환합니다.

{
  "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
        }
      ]
    }
  ]
}

대화 카테고리별로 분석한 30분 간격 데이터 가져오기

요청:

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

응답:

{
  "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"
}

#### 대화 유형 및 대화 카테고리별로 분석한 30분 간격 데이터 가져오기

요청:

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

응답:

{
  "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"
}

템플릿 분석

템플릿 분석은 템플릿이 전송된 횟수, 전달된 횟수, 읽힌 횟수 그리고 템플릿에서 URL 버튼 또는 빠른 답장 버튼이 클릭된 횟수를 설명합니다.

데이터는 최대 90일까지 소급하여 UTC 시간대 기준 하루 단위로 반환됩니다. 템플릿 분석은 WhatsApp 관리자 > 메시지 템플릿 > 템플릿 상세 정보 > 인사이트 패널에서도 확인할 수 있습니다.

제한 사항

• 계정이 클라우드 API 템플릿 분석을 옵트 인하지 않은 경우 템플릿 분석은 온프레미스 API에만 제공됩니다.
• 온프레미스 API 템플릿 분석은 집계 및 익명화 가이드라인이 적용되며, 사용자에게 카운트가 표시되려면 이벤트가 1,000개 이상 있어야 합니다.
• 버튼 클릭 분석은 MARKETING 또는 UTILITY로 분류된 템플릿에만 제공됩니다.
• 유럽 연합, 영국 또는 일본에서 Meta Business 계정이 소유하거나 이에 공유된 WABA 또는 이러한 국가나 지역의 국가 통화 번호를 가진 비즈니스 전화번호가 있는 WABA는 지원되지 않습니다.

버그 신고

템플릿 분석 버그를 신고하려면 다음과 같이 선택하여 기술 지원 티켓을 제출하세요.

• 질문 주제: WABiz: 클라우드 API
• 요청 유형: 버그 또는 구현 문제

템플릿 분석 확인

템플릿 분석을 가져오려면 WhatsApp Business 계정에서 템플릿 분석을 확인해야 합니다. WhatsApp 관리자 또는 API를 사용하여 템플릿 분석을 확인할 수 있습니다. API를 통해 확인하려면 다음의 요청을 보내세요.

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>?is_enabled_for_insights=true

템플릿 분석이 확인되면 WhatsApp Business 계정에 대한 템플릿 분석 수집이 시작됩니다. 확인이 끝난 템플릿 분석은 비활성화할 수 없습니다.

요청이 성공하면 API가 WhatsApp Business 계정 ID로 응답합니다. 예를 들면 다음과 같습니다.

{                          
  "id": 102290129340398
}

템플릿 분석 매개변수

예

모든 템플릿 분석 가져오기

시나리오: 주어진 2일의 기간에 WhatsApp Business 계정과 연결된 단일 메시지 템플릿에 대해 사용 가능한 모든 템플릿 분석을 가져옵니다.

요청 예시:

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

응답 예시:

{
  "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"
    }
  }
}

버튼 클릭 분석 비활성화

cta_url_link_tracking_opted_out 필드를 true로 설정하여 각 템플릿에서 버튼 클릭 추적을 비활성화할 수 있습니다. 이 기능을 비활성화하면 템플릿 인사이트를 확인할 때 API가 더 이상 템플릿 분석에서 클릭된 속성을 반환하거나 WhatsApp 관리자에서 버튼 참여/클릭 수를 표시하지 않습니다.

요청 구문

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

요청 매개변수

요청 예시

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

응답 예시

요청에 성공하면 API가 다음과 같이 응답합니다.

{
    "success": true
}

참고 자료

각 필드에 사용할 수 있는 모든 값의 리스트는 WhatsApp Business 계정 분석 필드의 그래프 API 참고 자료를 참조하세요.