> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the Kakao Message data source in Adriel.

## Introduction

Kakao Message is the message-campaign variant of Kakao's Kakao Moment platform. It covers broadcast ad campaigns delivered as KakaoTalk channel messages sent to a channel's followers. The connector retrieves per-message-ad performance from a distinct versioned Kakao Moment Message Ad endpoint, separate from the standard Kakao Moment display-ad API, so the metrics it exposes are message-specific: sends, opens, and per-element click placements rather than the impressions and reach of display ads.

As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration.

To connect this data source, see [How to connect Kakao Message to Adriel](/data-sources/g-n/kakao-message/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers the ad account, KakaoTalk channels (serving as both campaigns and ad sets), and individual message ads. Architecture data refreshes at **4:00 PM UTC and 5:00 AM UTC**.

### Reports data

Reports include daily performance for the ad account, channels, and message ads.

**Real-time.** Report data is fetched from Kakao Moment on demand when a dashboard loads, so the latest values are always visible. On top of that, scheduled cache refreshes keep historical data consistent across multiple time windows.

**Refresh schedule.** Reports refresh on three overlapping schedules, each covering the ad account, campaign, ad set, and ad levels:

* **5:00 PM UTC daily** — syncs the last **9 days**
* **11:40 PM and 6:40 AM UTC daily** — syncs the last **3 days**
* **7:30 AM UTC on the 1st and 15th of each month** — syncs the last **30 days**

## Architecture levels

Kakao Message maps the KakaoTalk channel hierarchy onto the canonical four-level model:

* **Ad account** — Kakao Moment ad account, suffixed `_message` to keep the message-ad account distinct from the display-ad account under the same Kakao Moment account.
* **Campaign** — KakaoTalk channel profile.
* **Ad set** — KakaoTalk channel profile (structurally identical to the campaign level; the same channel object serves both).
* **Ad** — Individual broadcast message ad sent to channel followers.

## Attribution windows

Conversion metrics are reported across two attribution windows: **1-day** and **7-day**. Each conversion event produces a separate 1-day and 7-day variant. For example, purchase conversions appear as both `conv_purchase_1d` and `conv_purchase_7d`. Non-conversion metrics (sends, opens, clicks) are not windowed.

## Metrics

<Note>
  **How to read the columns**

  **Data type** uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.

  **API Key** in code style like `cost` is the literal Kakao Moment Message Ad API field name. *Italic text* describes how a value is produced when it does not map cleanly to a single API field (for example, derived metrics).
</Note>

### Cost & spend

<Note>
  Currency values are reported in Korean won (KRW).
</Note>

| Metric               | Description                                    | Data type | API Key               |
| -------------------- | ---------------------------------------------- | --------- | --------------------- |
| Ad spend             | Reported spend.                                | Currency  | `cost`                |
| Ad spend (incl. VAT) | Spend grossed up by 10% VAT.                   | Currency  | *derived from `cost`* |
| CPC                  | Cost per click (spend divided by clicks).      | Currency  | *derived*             |
| CPM                  | Cost per mille (spend divided by impressions). | Currency  | *derived*             |

### Message delivery

| Metric               | Description                   | Data type | API Key         |
| -------------------- | ----------------------------- | --------- | --------------- |
| Messages sent        | Broadcast messages sent.      | Number    | `msg_send`      |
| Messages send-failed | Messages that failed to send. | Number    | `msg_send_fail` |

### Opens & clicks

<Note>
  Message opens are mapped to impressions and link clicks are mapped to clicks, so these values populate the standard impressions and clicks columns used across connectors.
</Note>

| Metric              | Description                                           | Data type  | API Key     |
| ------------------- | ----------------------------------------------------- | ---------- | ----------- |
| Impressions (opens) | Messages opened, mapped to impressions.               | Number     | `msg_open`  |
| Link clicks         | Clicks on links inside the message, mapped to clicks. | Number     | `msg_click` |
| CTR                 | Click-through rate (clicks divided by impressions).   | Percentage | *derived*   |

### Click placements

Each metric counts clicks on a specific element of the message layout.

| Metric                      | Description                             | Data type | API Key                                                     |
| --------------------------- | --------------------------------------- | --------- | ----------------------------------------------------------- |
| Click — Share               | Clicks on the share affordance.         | Number    | `msg_click_share`                                           |
| Click — Media               | Clicks on a media region.               | Number    | `msg_click_media`                                           |
| Click — Title               | Clicks on the title.                    | Number    | `msg_click_title`                                           |
| Click — Text                | Clicks on body text.                    | Number    | `msg_click_text`                                            |
| Click — List 1–5            | Clicks on list items 1 through 5.       | Number    | `msg_click_list1` … `msg_click_list5`                       |
| Click — Button 1–2          | Clicks on action buttons 1 and 2.       | Number    | `msg_click_button1`, `msg_click_button2`                    |
| Click — Carousel button 1–6 | Clicks on each carousel slide's button. | Number    | `msg_click_carousel_button1` … `msg_click_carousel_button6` |
| Click — Carousel share 1–6  | Share clicks on each carousel slide.    | Number    | `msg_click_carousel_share1` … `msg_click_carousel_share6`   |
| Click — Carousel coupon 1–6 | Coupon clicks on each carousel slide.   | Number    | `msg_click_carousel1_coupon` … `msg_click_carousel6_coupon` |
| Click — Carousel more       | "Show more" clicks in a carousel.       | Number    | `msg_click_carousel_more`                                   |
| Click — Coupon              | Coupon clicks.                          | Number    | `msg_click_coupon`                                          |
| Click — Catalog item        | Dynamic catalog item clicks.            | Number    | `msg_click_catalog_item{n}`                                 |
| Click — Others              | Clicks on other placements.             | Number    | `msg_click_others`                                          |

### Conversions

Conversions are attributed from pixel and SDK events. Each event is reported in both a 1-day and a 7-day attribution window (see [Attribution windows](#attribution-windows)). Purchase additionally carries a conversion-value variant.

| Metric                | Description                                                           | Data type  | API Key                                              |
| --------------------- | --------------------------------------------------------------------- | ---------- | ---------------------------------------------------- |
| Registration complete | Attributed registration events.                                       | Number     | `conv_cmpt_reg_1d`, `conv_cmpt_reg_7d`               |
| View cart             | Attributed view-cart events.                                          | Number     | `conv_view_cart_1d`, `conv_view_cart_7d`             |
| Purchase              | Attributed purchase events.                                           | Number     | `conv_purchase_1d`, `conv_purchase_7d`               |
| Purchase value        | Conversion value attributed to purchase events.                       | Currency   | `conv_purchase_p_1d`, `conv_purchase_p_7d`           |
| Participation         | Attributed participation events.                                      | Number     | `conv_participation_1d`, `conv_participation_7d`     |
| Sign-up               | Attributed sign-up events.                                            | Number     | `conv_signup_1d`, `conv_signup_7d`                   |
| App install           | Attributed app-install events.                                        | Number     | `conv_app_install_1d`, `conv_app_install_7d`         |
| Add to wishlist       | Attributed add-to-wishlist events.                                    | Number     | `conv_add_to_wishlist_1d`, `conv_add_to_wishlist_7d` |
| Add to cart           | Attributed add-to-cart events.                                        | Number     | `conv_add_to_cart_1d`, `conv_add_to_cart_7d`         |
| CPA                   | Cost per action, per conversion type (spend divided by conversions).  | Currency   | *derived*                                            |
| Conversion rate       | Conversion rate, per conversion type (conversions divided by clicks). | Percentage | *derived*                                            |

## Breakdowns

### Standard hierarchy

<Note>
  The KakaoTalk channel profile serves as both the campaign and the ad-set level, so grouping by campaign and grouping by ad set return the same set of channel rows.
</Note>

| Breakdown  | Description                                  | API Key     |
| ---------- | -------------------------------------------- | ----------- |
| Ad account | Group by ad account.                         | `adAccount` |
| Campaign   | Group by KakaoTalk channel (campaign level). | `campaign`  |
| Ad set     | Group by KakaoTalk channel (ad-set level).   | `adSet`     |
| Ad         | Group by individual message ad.              | `ad`        |

### Message ad attributes

| Breakdown       | Description                                                        | API Key         |
| --------------- | ------------------------------------------------------------------ | --------------- |
| Message ad type | Group by message ad type (for example, `BROADCAST`).               | `messageAdType` |
| Status          | Group by message ad status (for example, `FINISHED`, `IN_REVIEW`). | `status`        |

### UTM tracking

<Note>
  Kakao does not return UTM values; Adriel parses them from each ad's landing URL and exposes them as breakdowns for grouping.
</Note>

| Breakdown    | Description                     |
| ------------ | ------------------------------- |
| UTM Source   | Group by parsed `utm_source`.   |
| UTM Medium   | Group by parsed `utm_medium`.   |
| UTM Campaign | Group by parsed `utm_campaign`. |
| UTM Content  | Group by parsed `utm_content`.  |
| UTM Term     | Group by parsed `utm_term`.     |

## Limitations

* **Message-ad metric set only** — message ads expose a different metric catalogue than Kakao Moment display ads: opens, sends, and per-element click placements rather than impressions and reach. Display-ad metrics are not available on this connector.
* **Campaign and ad set are the same object** — the KakaoTalk channel profile is both the campaign and the ad-set level, so filtering by campaign or by ad set returns identical channel rows.
* **Separate ad account identifier** — the ad account is suffixed `_message` to keep message-ad and display-ad accounts distinct under the same Kakao Moment account.
* **Reconciliation window** — scheduled refreshes reconcile the last 30 days. Live queries can request older periods, but only the windows covered by the refresh schedule above are guaranteed to be reconciled.

## API references

* [Kakao Moment](https://moment.kakao.com/) — Kakao's ad management platform for advertisers.
* [Kakao Developers](https://developers.kakao.com/) — Kakao API and OAuth documentation.

## See also

* [How to connect Kakao Message to Adriel](/data-sources/g-n/kakao-message/how-to-connect) (paired how-to)
* [Kakao Moment data reference](/data-sources/g-n/kakao-moment/data-reference) — for Kakao Moment display ads
* [Kakao Keyword Ads data reference](/data-sources/g-n/kakao-keyword-ads/data-reference) — for Kakao search keyword ads
* [KakaoTalk Channel data reference](/data-sources/g-n/kakaotalk-channel/data-reference) — for organic KakaoTalk channel metrics