> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/crm-marketing/message-personalization/catalog.md).
# 카탈로그 사용하기
미리 설정 해 둔 카탈로그를 발송 시점에 메시지 본문으로 불러오는 기능입니다. 상품 정보, 매장 목록, 콘텐츠 메타데이터처럼 **여러 사용자가 공유하는 데이터**를 사용자 속성과 별개로 관리할 수 있습니다.
{% hint style="info" %}
**시작 전 준비물**
메시지에서 사용하려면 먼저 카탈로그와 데이터가 준비되어 있어야 합니다.
카탈로그 설정법은 다음 페이지를 참고하세요 {카탈로그 Link}
{% endhint %}
### 기본 문법
{% code overflow="wrap" %}
```liquid
{% catalog_items <카탈로그명> <아이템ID> [아이템ID] [아이템ID] %}
```
{% endcode %}
조회 결과는 **`items` 변수**에 담기며, 이후 본문에서 `items[번호].필드명` 으로 사용합니다.
{% code overflow="wrap" %}
```liquid
{% catalog_items Games 1234 %}{{ items[0].title }} 지금 {{ items[0].price }}원
→ 슈퍼마리오 지금 49000원
```
{% endcode %}
#### 파라미터 상세
파라미터
설명
필수
<카탈로그명>
조회할 카탈로그 이름
✅
<아이템ID>
조회할 아이템의 ID. 공백으로 구분해 최대 3개
최소 1개 필수
***
### 지원 기능
**아이템 여러 개 조회** — 한 태그에서 최대 3개까지
{% code overflow="wrap" %}
```liquid
{% catalog_items Games 1234 1235 1236 %}{{ items[0].title }}, {{ items[1].title }}, {{ items[2].title }}
```
{% endcode %}
**아이템 ID에 개인화 변수 사용**
{% code overflow="wrap" %}
```liquid
{% catalog_items Games {{ user_properties["last_viewed_item"] }} %}{{ items[0].title }}
```
{% endcode %}
**필터 적용**
{% code overflow="wrap" %}
```liquid
{{ items[0].price | default: "가격 문의" }}
```
{% endcode %}
**필드 타입에 맞는 값 사용** — 카탈로그 필드 타입에 따라 값이 그대로 전달됩니다
| 필드 타입 | 메시지에서의 값 |
| ------- | ---------------------------------------- |
| STRING | 문자열 |
| NUMBER | 숫자 (계산·필터 적용 가능) |
| BOOLEAN | `true` / `false` (조건문에 사용 가능) |
| TIME | ISO-8601 문자열 (예: `2026-08-20T00:00:00Z`) |
**아이템 ID 자체 참조** — `{{ items[0].id }}`
***
### 응답 처리 규칙
| 상황 | 처리 방식 |
| ------------------ | ---------------------------- |
| 정상 조회 | `items` 에 아이템이 담김 |
| 요청한 아이템이 카탈로그에 없음 | **그 자리만 빈 값**, 나머지 아이템은 그대로 |
| 조회 실패 (일시적 오류 등) | 전체가 빈 값 |
| 아이템 ID 자리의 변수가 빈 값 | **그 자리만 빈 값** |
| 카탈로그명이 빈 값 | 태그 전체를 건너뜀 (`items` 가 비어 있음) |
| 아이템 ID를 4개 이상 지정 | 태그 전체를 건너뜀 |
{% hint style="warning" %}
응답 여부에 따라 메시지 발송이 실패하지 않습니다. 값을 가져오지 못하면 그 자리가 비워진 채로 발송됩니다.
결과에 따라 메시지 발송을 취소하고싶다면? -> {Abort Link}
{% endhint %}
#### 아이템이 없어도 순서가 밀리지 않습니다
요청한 아이템 ID의 순서와 위치가 그대로 유지됩니다. 가운데 아이템이 삭제되어도 뒤 아이템의 번호가 당겨지지 않습니다.
{% code overflow="wrap" %}
```liquid
{% catalog_items Games 1234 없는ID 1236 %}[{{ items[0].title }}] [{{ items[1].title }}] [{{ items[2].title }}]
→ [슈퍼마리오] [] [젤다의전설]
```
{% endcode %}
`items[2]` 는 언제나 세 번째로 지정한 아이템입니다. 아이템 하나가 삭제되었을 때 다른 상품 정보가 그 자리에 표시되는 일이 없습니다.
***
### 에러 처리 및 방어 패턴
값이 비어 있을 수 있으므로 아래 두 가지 방법을 권장합니다.
**1. 기본값 지정 — `default` 필터**
{% code overflow="wrap" %}
```liquid
{% catalog_items Games 1234 %}{{ items[0].title | default: "인기 상품" }} 을 확인해 보세요
```
{% endcode %}
**2. 조건 분기 — `if` 문**
{% code overflow="wrap" %}
```liquid
{% catalog_items Games 1234 %}{% if items[0] %} {{ items[0].title }} 이 {{ items[0].price }}원!{% else %} 이번 주 신작을 확인해 보세요{% endif %}
```
{% endcode %}
여러 아이템을 쓸 때는 각 자리를 따로 확인할 수 있습니다.
{% code overflow="wrap" %}
```liquid
{% catalog_items Games 1234 1235 %}{% if items[1] %}{{ items[1].title }}도 함께 만나보세요{% endif %}
```
{% endcode %}
전체 개수가 필요하면 `size` 필터를 사용합니다. 비어 있는 자리도 개수에 포함됩니다.
{% code overflow="wrap" %}
```liquid
{{ items | size }}
```
{% endcode %}
***
### 실 사용 예시
**1. 단일 상품 소개**
{% code overflow="wrap" %}
```liquid
{% catalog_items Products SKU-1001 %}{{ items[0].name }} 이 {{ items[0].discount_price }}원으로 준비되어 있어요
```
{% endcode %}
**2. 사용자가 마지막으로 본 상품**
{% code overflow="wrap" %}
```liquid
{% catalog_items Products {{ user_properties["last_viewed_sku"] }} %}{% if items[0] %} 아직 고민 중이신가요? {{ items[0].name }} 이 기다리고 있어요{% else %} 이번 주 추천 상품을 확인해 보세요{% endif %}
```
{% endcode %}
**3. 이벤트 속성으로 주문 상품 안내**
{% code overflow="wrap" %}
```liquid
{% catalog_items Products {{ event_properties["sku"] }} %}{{ items[0].name }} 주문이 완료되었습니다
```
{% endcode %}
**4. 세 가지 상품 한 번에**
{% code overflow="wrap" %}
```liquid
{% catalog_items Products SKU-1001 SKU-1002 SKU-1003 %}이번 주 베스트 31위 {{ items[0].name }}2위 {{ items[1].name }}3위 {{ items[2].name }}
```
{% endcode %}
**5. BOOLEAN 필드로 조건 분기**
{% code overflow="wrap" %}
```liquid
{% catalog_items Products SKU-1001 %}{% if items[0].on_sale %} 🔥 {{ items[0].name }} 특가 진행 중{% else %} {{ items[0].name }} 을 만나보세요{% endif %}
```
{% endcode %}
**6. 이미지 URL 사용**
이미지 URL 필드도 문자열로 저장해 사용할 수 있습니다. 이미지 영역에 입력할 때는 태그와 URL 출력 사이에 공백이나 줄바꿈을 넣지 마세요.
{% code overflow="wrap" %}
```liquid
{% catalog_items Products SKU-1001 %}{{ items[0].image_url }}
```
{% endcode %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.hackle.io/crm-marketing/message-personalization/catalog.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.