> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/guide/marketing/smart-message.md).

# 푸시알림

### 푸시알림이란 <a href="#what-is-push-notification" id="what-is-push-notification"></a>

푸시알림은 미니앱이 사용자에게 보내는 푸시·알림 메시지예요. 주문·결제·배송처럼 서비스 이용에 꼭 필요한 정보를 사용자에게 전달할 수 있어요.

푸시알림은 기능성 메시지로만 보낼 수 있어요. 수신자가 요청한 정보이거나, 서비스 이행에 필요한 필수 메시지여야 해요. 구매 유도, 서비스 이용 유도, 혜택 안내, 리텐션 같은 광고·마케팅 목적의 내용은 넣을 수 없어요. 메시지 문구가 고민된다면 UX 라이팅 문서와 아래 메시지 작성 가이드를 참고해 주세요.

#### 푸시와 알림의 개념 <a href="#push-and-notification-concepts" id="push-and-notification-concepts"></a>

* 푸시: 앱을 열지 않은 상태에서도 받는 운영체제(OS) 알림이에요. 앱 이름과 로고가 함께 노출돼요.
* 알림: 토스 앱 오른쪽 위의 종 아이콘을 눌렀을 때 확인할 수 있는 앱 안의 메시지예요.

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FyL7gYaNc3oBWxYwBlK80%2Fimage.png?alt=media&#x26;token=cdc5c74c-6bf1-43be-af7a-819c360f57d1" alt=""><figcaption></figcaption></figure>

#### 푸시알림의 좋은 점 <a href="#push-notification-benefits" id="push-notification-benefits"></a>

* 사용자에게 꼭 필요한 정보를 자동으로 전달할 수 있어요.
* 사용자가 미니앱을 열지 않아도 중요한 정보를 놓치지 않게 할 수 있어요.
* 적절한 타이밍의 메시지로 서비스 이용 흐름을 자연스럽게 이어갈 수 있어요.
* 발송 결과를 바탕으로 메시지 내용을 계속 개선할 수 있어요.

#### 꼭 참고해 주세요 <a href="#important-notes" id="important-notes"></a>

* 푸시·알림을 보내려면 메시지 템플릿 문구 검수가 필요해요.
* 푸시 내용을 작성하면 알림 메시지에 자동으로 반영돼요.
* 워크스페이스(사업자)당 10만 건까지 발송할 수 있어요.
* 서비스 유도, 혜택 안내, 리텐션 같은 광고 목적의 내용을 넣을 수 없어요.
* 사용자에게 미리 그 목적으로 발송하겠다는 알림 동의를 받아야 해요.
* 사용자가 알림 수신을 해제할 수 있는 기능을 제공하고, 해제 방법을 명확하게 안내하는 걸 권장해요.

<details>

<summary>토스 앱 → 전체 탭 → 설정 버튼 → 알림 → 서비스별 알림에서 알림 수신 여부를 직접 제어할 수 있어요.</summary>

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FeR5t52wqNrftZBu4DHj7%2Fimage.png?alt=media&#x26;token=d8668c28-2385-4e27-a0b0-cc9d845c935c" alt=""><figcaption></figcaption></figure>

</details>

***

### 콘솔에서 설정하기 <a href="#configure-in-console" id="configure-in-console"></a>

접속 방법: 앱인토스 콘솔 → 워크스페이스 선택 → 미니앱 선택 → 왼쪽 메뉴 '푸시알림' 선택

푸시알림은 서비스 이용에 직접 필요한 정보를 전달하는 메시지예요. 수신자가 요청한 정보이거나, 서비스 이행을 위한 필수 메시지여야 해요. 서비스 사용 유도, 혜택 안내, 리텐션 등 광고 목적의 내용이 들어가면 광고성 캠페인으로 발송해야 해요.

<details>

<summary>허용되는 예시</summary>

* 결제 완료, 환불, 포인트 적립 등 거래 관련 메시지
* 배송 시작, 배송 완료, 예약 확정 등 서비스 진행 상황 메시지
* 정기 결제 예정, 서비스 만료 예정 등 이용 기간·상태 알림

</details>

<details>

<summary><mark style="color:$danger;">허용되지 않는 예시</mark></summary>

* "이런 상품은 어떠세요?", "오늘만 할인 중이에요." — 판촉·광고 목적
* "이전 구매 고객을 위한 추천 상품" — 부가적 마케팅 정보
* "이벤트 참여하고 혜택 받아가세요." — 이벤트 홍보성 메시지

</details>

#### 1) 직접 API로 발송하기

파트너사 서버에서 원하는 시점에 발송할 수 있어요.

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2Fk7om6S42RmDrgXYPQD4M%2Fimage.png?alt=media&#x26;token=0cda12d0-d35e-4ebb-94bb-c2f09af72cd2" alt=""><figcaption></figcaption></figure>

파트너사 서버에서 원하는 시점에 발송할 수 있어요. 발송 API 상세 스펙은 '기능성 메시지 발송하기' 문서에서 확인할 수 있어요.

* 캠페인 제목: 어떤 목적으로 발송하는 캠페인인지 알기 쉽게 지어 주세요.
* 제목: 7자 이내(띄어쓰기 포함), 명사형으로 작성해 주세요. '\~하기' 형태로 쓰면 사용자 행동을 유도하는 목적으로 오해받을 수 있어요.
* 내용: 25자 이내(띄어쓰기 포함), '\~요.' 체로 작성해 주세요. 변수는 2글자로 계산돼요. API로 발송할 때 변수는 직접 개발해야 해요.
* 이동 URL: 푸시나 알림을 눌렀을 때 이동할 페이지를 설정해 주세요. 접속되는지 꼭 확인해 주세요.
* 발송 코드 : 파트너사 서버에서 이 메시지를 불러올 수 있도록 발송 코드를 입력해 주세요. 반드시 `{appName}-` 로 시작해야 해요.
* 알림 동의문: 문구 검토에서 알림 동의문이 필요하다고 판단되어 반려되면, 반드시 알림 동의문을 구성한 뒤 재검토를 요청해 주세요.

#### 2) 토스에게 발송 요청하기

일회성 발송과 정기 발송을 골라서 발송할 수 있어요.

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FPeKBN4f5ZWaW1WjVxkqG%2Fimage.png?alt=media&#x26;token=6c2fbb20-8879-42ba-8a42-533443d39684" alt=""><figcaption></figcaption></figure>

서버 없이 일회성 발송과 정기 발송을 골라서 발송할 수 있어요.

* 캠페인 제목: 어떤 목적으로 발송하는 캠페인인지 알기 쉽게 지어 주세요.
* 제목: 7자 이내(띄어쓰기 포함), 명사형으로 작성해 주세요.
* 내용: 25자 이내(띄어쓰기 포함), '\~요.' 체로 작성해 주세요. 토스에게 발송을 요청할 때는 이름 변수만 쓸 수 있어요. 변수는 2글자로 계산돼요.
* 이동 URL: 푸시나 알림을 눌렀을 때 이동할 페이지를 설정해 주세요. 접속되는지 꼭 확인해 주세요.
* 알림 동의문: 토스에게 발송을 요청해 발송하는 경우 알림 동의문이 반드시 필요해요.
* 발송 유형: 일회성 발송과 정기 발송 중 선택할 수 있어요.
  * 일회성 발송: 특정 날짜와 시간을 지정해 한 번만 발송해요.
  * 정기 발송: 반복 발송 주기를 설정할 수 있어요. (매일: 매일 지정한 시간에 발송 / 매주: 원하는 요일과 시간을 선택해 발송) 시작일과 종료일을 설정하고, '종료일 없음'을 선택하면 직접 중단할 때까지 계속 발송해요.

#### 알림 동의문 <a href="#notification-consent-message" id="notification-consent-message"></a>

기능성 메시지를 보내려면 알림 동의문이 필요할 수 있어요. 알림 동의문은 사용자가 서비스 이용 과정에서 알림 수신에 동의할 수 있도록 제공하는 안내 문구예요. 특정 시점에 알림을 받겠다고 사용자에게 동의를 받는 경우에는 반드시 알림 동의문을 써야 해요.

<details>

<summary>알림동의문이 필요한 경우</summary>

재입고 알림 신청, 이벤트 시작 알림 신청, 가격 변동 알림 신청, 예약 오픈 알림 신청

</details>

<details>

<summary>알림동의문이 필요하지 않은 경우</summary>

결제 완료, 배송 시작, 배송 완료, 환불 완료, 정보 변경 안내, 약관 변경 안내

</details>

알림 동의문이 필요한 메시지인데 동의문을 등록하지 않으면, 기능성 메시지 템플릿을 저장할 수 없어요.

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FZiL8M4U1TrIslpw4RTU2%2Fimage.png?alt=media&#x26;token=8210c1a0-cccb-4b03-9880-895ab0992ba9" alt=""><figcaption></figcaption></figure>

**알림 동의문 설정하기**

* 알림 동의문 이름: 미니앱 서비스에서 어떤 상황에 이 동의문을 쓰는지 알 수 있게 지어 주세요.
* 알림 발송 시점: 동의하면 언제 발송하는지 작성해 주세요.
  * API로 발송하는 경우: 언제 발송하는지 작성해 주세요. (예: 찜한 상품 가격이 내렸을 때, 매일 날씨 안내를 받기로 했을 때, 서비스 내 정지된 기능이 다시 활성화됐을 때 등)
  * 토스에게 발송을 요청하는 경우: 언제 발송되는지와 함께 발송 시점을 명확하게 작성해 주세요. (예: 매주 화요일 오후 5시에 다음 날 날씨를 알려줄 때 등)

<details>

<summary>알림동의문에 포함되는 내용</summary>

* 서비스명과 서비스 설명 (미니앱 정보에서 자동 반영)
* 알림 발송 시점 (템플릿을 만들 때 입력한 트리거 조건)
* 알림 동의 철회 경로
* 고객센터 연락처 (미니앱 정보에서 자동 반영)

</details>

**알림 발송 방법**

* 특정 조건 충족: 어떤 조건이 충족되면 알림을 발송하는지 입력해 주세요. (예: 찜한 상품 가격 인하, 정지된 기능 재활성화 등)
* 정해진 요일과 시간: 발송 주기와 유형을 입력해 주세요. (예: 매일 날씨 안내, 출석 알림 등)

미니앱에서 사용자에게 알림 수신 동의 UI를 표시하려면 [알림 동의문 요청하기 문서](https://developers-apps-in-toss.toss.im/documentation/common/growth/smart-message#id-4.-requestnotificationagreement)를 참고해 주세요.

{% hint style="info" %}
알림 동의문 호출 시 templateCode

미니앱에서 알림 동의문을 호출할 때 쓰는 `templateCode`는, 그 알림 동의문이 연결된 기능성 메시지의 발송 코드예요. 콘솔 → 스마트 발송 → '기능성' 탭에서 확인할 수 있어요.
{% endhint %}

***

### 메시지 작성 가이드 <a href="#message-writing-guide" id="message-writing-guide"></a>

토스를 쓰는 모든 사용자에게 내 앱을 처음 소개한다는 마음으로 작성해 주세요. 사용자는 이 푸시를 '토스'라는 금융 앱의 맥락 안에서 받아들여요. 메시지가 토스답게 보이고 자연스럽게 이해되도록 써 주세요.

#### 기본 규칙 <a href="#basic-rules" id="basic-rules"></a>

* 모든 푸시·알림은 해요체로 써요. 본문은 문장형('\~요.')으로 쓰고 문장 끝에 마침표를 찍어요. 일관된 보이스톤을 지키기 위한 규칙이에요.
* 마침표는 본문에만 써요. 제목에는 마침표를 쓰지 않아요.
* 제목은 '\~하기'나 명사형으로 써요. (기능성은 명사형으로 써요.)
* '토스 + 서비스명'으로 작성하는 방식은 쓸 수 없어요.
* 글자 수는 제목 7자, 본문 25자까지예요(공백 포함). 글씨를 크게 키워도 잘리지 않는 기준이에요. (안드로이드에서 큰 글씨 1.3배 이상이 전체의 24%예요.)
* 맞춤법과 띄어쓰기를 꼭 확인해 주세요.

#### 1) 아래 표현은 쓸 수 없어요.

**띄어쓰기 생략**

글자 수를 맞추려고 띄어쓰기를 생략하지 않아요.

* <mark style="color:$danger;">안 좋은</mark> 예시: \[재입고알림] 찜한상품이다시입고됐어요.
* 좋은 예시: \[재입고 알림] 찜한 상품이 다시 입고됐어요.

**어색한 표현**

문법적으로 틀리진 않지만 자연스럽지 않은 표현이에요. 소리 내어 읽어보면 금방 알 수 있어요.

* <mark style="color:$danger;">안 좋은</mark> 예시: \[배송 안내] 상품이 도착이 됐어요. → 조사가 어색해요. 소리 내어 읽으면 금방 알 수 있어요.
* 좋은 예시: \[배송 완료] 상품이 도착했어요.

#### 2) 게임 서비스는 '게임'이라고 밝혀요.

사용자가 클릭하기 전에 게임인지 알아야 해요. 서비스명이나 게임 내 용어만 쓰면 모를 수 있어요.

* <mark style="color:$danger;">안 좋은</mark> 예시: \[경쟁 퍼즐] 새 시즌 보상이 도착했어요.
* 좋은 예시: \[퍼즐 게임] 새 시즌 보상이 도착했어요.

#### 3) 게임 장르를 활용할 경우 참고해 주세요.

* 특정 게임 이름에서 파생된 장르는 쓸 수 없어요. (예: 로그라이크, 메트로배니아, 소울라이크, 뱀서라이크 등)
* 사용자가 직관적으로 이해할 수 있는 장르명을 써요.

| 장르             | Do                   |
| -------------- | -------------------- |
| **방치형 RPG**    | **방치형 게임 또는 RPG 게임** |
| **캐주얼 MMORPG** | **캐주얼 게임**           |
| **오픈월드 액션**    | **액션 게임**            |
| **쓰리매치 퍼즐**    | **퍼즐 게임**            |
| **턴제 전략 RPG**  | **전략 게임 또는 RPG 게임**  |
| **2D 횡스크롤 액션** | **액션 게임**            |

<details>

<summary>장르를 조합하거나 세분화하지 않아요.</summary>

<table data-search="false"><thead><tr><th>장르</th><th>뜻</th><th>대체 방향</th></tr></thead><tbody><tr><td><strong>MMORPG</strong></td><td>Massively Multiplayer Online RPG</td><td><strong>RPG 게임</strong></td></tr><tr><td><strong>ARPG</strong></td><td>Action RPG</td><td><strong>RPG 게임 또는 액션 게임</strong></td></tr><tr><td><strong>SRPG</strong></td><td>Simulation/Strategy RPG</td><td><strong>RPG 게임 또는 전략 게임</strong></td></tr><tr><td><strong>JRPG</strong></td><td>Japanese RPG</td><td><strong>일본 RPG 게임</strong></td></tr><tr><td><strong>FPS</strong></td><td>First-Person Shooter</td><td><strong>슈팅 게임</strong></td></tr><tr><td><strong>TPS</strong></td><td>Third-Person Shooter</td><td><strong>슈팅 게임</strong></td></tr><tr><td><strong>MOBA</strong></td><td>Multiplayer Online Battle Arena</td><td><strong>전략 게임</strong></td></tr><tr><td><strong>RTS</strong></td><td>Real-Time Strategy</td><td><strong>전략 게임</strong></td></tr></tbody></table>

</details>

<details>

<summary>게임 관련 전문 용어는 사용할 수 없어요.</summary>

<table data-search="false"><thead><tr><th>장르</th><th>뜻</th><th>대체 방향</th></tr></thead><tbody><tr><td><strong>핵앤슬래시</strong></td><td>Hack and Slash</td><td><strong>액션 게임</strong></td></tr><tr><td><strong>덱빌딩</strong></td><td>Deck Building</td><td><strong>카드 게임</strong></td></tr><tr><td><strong>오토배틀러</strong></td><td>Auto Battler</td><td><strong>전략 게임</strong></td></tr><tr><td><strong>불렛헬</strong></td><td>Bullet Hell</td><td><strong>슈팅 게임</strong></td></tr><tr><td><strong>런앤건</strong></td><td>Run and Gun</td><td><strong>액션 게임 &#x26; 스포츠 게임</strong></td></tr><tr><td><strong>하이퍼캐주얼</strong></td><td>Hyper Casual</td><td><strong>캐주얼 게임</strong></td></tr><tr><td><strong>샌드박스</strong></td><td>Sandbox (게임 맥락)</td><td><strong>시뮬레이션 게임</strong></td></tr></tbody></table>

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers-apps-in-toss.toss.im/guide/marketing/smart-message.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.