# 개인화 메시지 작성

## 개요 <a href="#overview" id="overview"></a>

마켓탭 CRM의 핵심 기능인 개인화 메시지 작성 방법을 안내합니다.\
마케터는 사용자 속성과 행동 데이터를 활용해 더욱 효과적인 메시지를 구성할 수 있습니다.

## 1. 적용 위치

개인화 메시지는 다음과 같은 텍스트 영역에서 사용할 수 있습니다.

* SMS 본문
* PUSH 알림 본문
* 알림톡 템플릿 내 개인화 필드
* 브랜드메시지 본문 등

## 2. 작성 방식 선택: 태그 기능 vs Liquid Template

* 두 방식은 동시에 사용할 수 없습니다. 반드시 하나만 선택하여 사용해야 합니다.
* 사용자의 기술 숙련도와 목적에 따라 적합한 방식을 선택하세요.

<table><thead><tr><th width="178.1875">구분</th><th>태그 기능</th><th>Liquid Template</th></tr></thead><tbody><tr><td>사용 대상</td><td>일반 사용자</td><td>고급 사용자</td></tr><tr><td>특징</td><td>버튼 클릭으로 개인화 속성 삽입</td><td>문법 기반 자유로운 템플릿 작성</td></tr><tr><td>데이터 접근</td><td>유저/이벤트 속성 자동 삽입</td><td>코드로 수동 접근</td></tr><tr><td>추천 상황</td><td>빠르게 메세지를 구성할 때</td><td>조건 분기, 외부 API 활용 등</td></tr></tbody></table>

## 3. 태그 기능 안내

* 메시지 작성 시 `< >`버튼을 눌러 유저 및 이벤트 속성을 삽입할 수 있습니다.

<figure><img src="https://3826783036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyROeODSgPulCgZ9LFAYn%2Fuploads%2FUWsibZcRr2XLEOHax3WP%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-09-03%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%209.01.52.png?alt=media&#x26;token=4408541c-d33a-49ab-8cf4-669fa5e9292e" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3826783036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyROeODSgPulCgZ9LFAYn%2Fuploads%2F6ndmh5KdxH8VWKgpd3OX%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-09-03%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%209.02.39.png?alt=media&#x26;token=3a924e38-4634-40d4-89e3-4fe385b54343" alt=""><figcaption></figcaption></figure>

<figure><img src="https://content.gitbook.com/content/yROeODSgPulCgZ9LFAYn/blobs/hjSz3ulVfr4x098TKW0V/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-05-19%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%204.17.17.png" alt=""><figcaption><p>실제 개인화가 적용된 화면</p></figcaption></figure>

* 리스트 값(이벤트 아이템, 유저 위시리스트/카트 등) 하위 속성 선택 시, “속성값 외 N건” 형태로 반복 출력됩니다.
  * 예: 주문제작 운동화 외 3건
* 실시간 미리보기에서는 항상 기본값으로 표기됩니다.

### 3-1. 대체 텍스트

선택한 속성 값이 없을 경우를 대비해, 대체 텍스트를 설정할 수 있습니다. 예를 들어, `이름` 속성을 선택하고 대체 텍스트로 `고객`을 입력하면, 이름 값이 없는 사용자에게는 `"고객"`으로 치환되어 메시지가 발송됩니다.

반대로, 해당 속성을 반드시 포함해야 하는 경우(예: 상품명)에는 **대체 텍스트를 설정하지 않아야 합니다**. 이 경우 값이 없는 유저에게는 메시지 발송이 실패하며, 필수 데이터 누락을 방지할 수 있습니다.

## 4. Liquid Template 가이드

Liquid template은 개인화 문구를 치환할때도 사용이 가능하며 필요한 경우 본문에 바로 Liquid 문법을 사용할 수도 있습니다.

<figure><img src="https://3826783036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyROeODSgPulCgZ9LFAYn%2Fuploads%2F8TolAbxcRiYVzKSov9DZ%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-06-12%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%204.38.55.png?alt=media&#x26;token=6c7dcde6-7692-47c8-9b4e-625921c03e5e" alt=""><figcaption><p>&#x3C;>클릭, 타입에서 Liquid를 선택한 후 화면</p></figcaption></figure>

<figure><img src="https://3826783036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyROeODSgPulCgZ9LFAYn%2Fuploads%2F7UQMzUKFU7IYBe6BZ50r%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-06-12%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%204.41.07.png?alt=media&#x26;token=d796016c-18e6-42e4-873c-b6e5f5cc907b" alt=""><figcaption><p>본문에서 직접 Liquid 문법을 사용한 화면</p></figcaption></figure>

{% hint style="success" %}
기본 문법은 [Shopify Liquid 공식 문서](https://shopify.github.io/liquid/)를 참고하세요.

이 절에서는 마켓탭에서만 사용할 수 있는 전용 문법을 소개합니다.
{% endhint %}

### **4-1. 유저 및 이벤트 데이터 접근**

* user.속성명, event.속성명 으로 데이터에 접근합니다.
* 속성명은 \[고객데이터 연동 > 유저/이벤트 속성] 페이지에서 확인할 수 있습니다.

```liquid
{{ user.mkt_name }} 님의 최근 구매는 
{{ event.mkt_items[0].mkt_product_name | default: '없음' }}입니다.
```

### **4-2. 외부 API를 통한 개인화**

고객별 쿠폰, 포인트, 배송정보 등을 실시간으로 조회해 메시지에 반영하고 싶을 때 사용할 수 있는 기능입니다.

**예를 들어 아래와 같은 상황에서 유용합니다:**

* 예시 ①: 쿠폰 발급 시스템과 연동하여, 실제 발급된 쿠폰 코드를 포함한 메시지를 보낼 때
* 예시 ②: 특정 고객의 잔여 포인트를 외부 시스템에서 조회해 안내할 때
* 예시 ③: 구매 고객에게 실시간 배송조회 URL을 만들어서 발송할 때

**문법은 아래와 같습니다:**

```liquid
{% api_content
  :name 응답결과를 담을 변수명
  :url '요청을 보낼 URL'
  :method HTTP_METHOD (get, post, put)
  :headers '유효한 JSON 문자열'
  :body '유효한 JSON 문자열'
%}
```

<table><thead><tr><th width="167.0625">속성명</th><th>설명</th></tr></thead><tbody><tr><td>:name</td><td><p>응답 결과를 담을 <strong>고유 변수명</strong> (예: coupon_response) </p><p>메시지 내에서 {{ 변수명.필드명 }} 으로 접근합니다.</p></td></tr><tr><td>:url</td><td><p>API 요청을 보낼 <strong>URL</strong> (반드시 작은 따옴표 '로 감쌈) </p><p>메시지 내 개인화 변수({{ user.user_id }} 등)를 포함할 수 있습니다.</p></td></tr><tr><td>:method</td><td>HTTP 요청 방식 (지원 값: get, post, put)</td></tr><tr><td>:headers</td><td><p>요청 헤더. 반드시 <strong>유효한 JSON 형식</strong>의 문자열로 작성하고, 작은 따옴표로 감쌉니다. </p><p>개인화 변수도 사용 가능합니다. (예: "X-User-Id": "{{ user.user_id }}")</p></td></tr><tr><td>:body</td><td>요청 본문. <strong>유효한 문자열</strong>이어야 하며, 작은 따옴표로 감쌉니다.<br>메시지 내 개인화 변수({{ user.user_id }} 등)를 포함할 수 있습니다.</td></tr></tbody></table>

**예시는 아래와 같습니다:**

```
{% api_content
  :name my_api_response
  :url 'https://my-domain.site/path'
  :method post
  :headers '{
    "X-App-Id": "SAMPLE-APP-ID",
    "X-App-Token": "SAMPLE-APP-TOKEN",
    "X-User-Id": "{{ user.user_id }}",
    "Content-Type": "application/json"
  }'
  :body '{
    "key1": "value1"
  }'
%}
```

* HTTP 200 응답일 경우에만 메시지가 정상 발송됩니다.

**메세지에서의 사용 방법은 아래와 같습니다:**

위 예시 요청의 API 응답이 다음과 같을 경우:

```json
{
  "coupon_code": "ABC123",
  "discount_percent": 5,
  "expired_at": "2025-06-30"
}
```

메시지에서는 다음처럼 사용할 수 있습니다:

```liquid
{{ user.mkt_name }}님, 발급된 쿠폰은 {{ my_api_response.coupon_code }}입니다.
해당 쿠폰은 전품목 {{ my_api_response.discount_percent }}% 할인 쿠폰이며,
사용 기한은 {{ my_api_response.expired_at }}까지입니다.
```

## 5. 쿠폰 속성 가이드

쿠폰 속성은 메시지에 **쿠폰 발급 코드**를 포함하고자 할 때 사용할 수 있습니다.\
[쿠폰 설정 화면](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/settings/channel/coupon)에서 생성한 쿠폰을 선택한 뒤, **쿠폰 발급 코드 속성**을 선택해주세요.

<figure><img src="https://3826783036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyROeODSgPulCgZ9LFAYn%2Fuploads%2Ffoc5VvM3mNPo3eDGeLnn%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-09-03%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%209.05.15.png?alt=media&#x26;token=d98d009b-0682-4635-aa24-a1a63902b297" alt=""><figcaption></figcaption></figure>

&#x20;

## 6. 카탈로그 <a href="#catalog" id="catalog"></a>

메시지에 카탈로그 속성은 두 가지 방식으로 설정할 수 있습니다.

1. 상품을 직접 지정한 뒤, 원하는 속성을 선택하는 방식
2. 이벤트 속성 또는 유저 속성이 상품 ID와 매칭되는 경우,
   * 매칭 기준이 될 이벤트/유저 속성 지정
   * 개인화에 사용할 상품 속성 선택

{% hint style="info" %}

* 카탈로그를 개인화 속성으로 사용하는 경우, 이벤트 기반이라면 상품 ID와 매칭 가능한 이벤트 속성이 존재해야 합니다.
* 이미지 사용 시에는 메시지 유형에 따라 자동으로 크기나 비율이 조정될 수 있으므로, 발송 전 미리 검토하는 것이 필요합니다.
  {% endhint %}

### 6-1. 고정 상품 선택

고정 상품을 선택할 경우, 개인화 문구에 사용할 상품을 직접 지정하게 됩니다. 이 경우 6-2의 캠페인 설정 카탈로그와 관계 없이 설정한 고정 상품의 속성 문구가 노출됩니다.

<figure><img src="https://3826783036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyROeODSgPulCgZ9LFAYn%2Fuploads%2FF6wkGOxCIl0Do2f3ZpJU%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-12-12%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%204.29.58.png?alt=media&#x26;token=45d7caef-6bb8-46f1-a5bb-0c06b5bc399e" alt=""><figcaption></figcaption></figure>

### 6-2. 캠페인 상품 카탈로그

캠페인에서 설정한 상품 카탈로그를 공통으로 사용합니다.&#x20;

상품 카탈로그는 `캠페인 설정 > 고급 설정`에서 지정하거나 툴팁의 영역을 선택해서 지정할 수 있습니다. 두 경우 모두 캠페인에서 공용으로 사용되는 상품 카탈로그 설정을 지정합니다. 따라서 수정할 경우 `캠페인 상품 카탈로그` 옵션을 사용하는 다른 개인화 문구에도 반영됩니다.

<figure><img src="https://3826783036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyROeODSgPulCgZ9LFAYn%2Fuploads%2FUgF3YcWUbkquCNQCQ0P4%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-12-12%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%204.32.09.png?alt=media&#x26;token=44781c6e-7485-42f3-a83f-0df0d011f8bb" alt=""><figcaption></figcaption></figure>

## 7. 주의사항

* SMS 및 알림톡 등 일부 채널은 글자 수 제한이 있으므로, 개인화 이후 총 글자 수를 반드시 직접 확인해야 합니다.
* Liquid 문법 오류가 있을 경우, 메시지가 전송되지 않으며 payload conversion failed로 처리됩니다.
* mkt\_items와 같이 반복 가능한 데이터는 아이템 수에 따라 메시지 길이가 달라질 수 있습니다.