앱인토스 소개 – 스마트 메시지(Smart Message, 푸시알림) 규칙, 보내기 전에 알아둘 것
앱인토스 미니앱에서 사용자에게 알림을 보내고 싶다면 가장 먼저 알아야 할 것은 스마트 메시지(Smart Message)라고도 부를 수 있는 푸시알림이 기능성 메시지만 보낼 수 있는 기능이라는 점입니다. 코드를 짜기 전에 문구와 목적부터 통과해야 해요.
공식 문서 주소에는 smart-message라고 적혀 있고 콘솔에는 스마트 발송이라는 이름도 보이는데, 이 글에서는 편의상 스마트 메시지라고 부르겠습니다. 토스 공식 개발자 문서를 읽고 정리했고, 마지막에는 제가 만든 물마시기 미니앱이 알림 동의를 어떻게 요청하는지도 코드에서 옮겨 두었습니다.
다만 이 글에는 제가 알림을 실제로 보내 본 결과나 문구 검수 결과는 없습니다. 문서에 적힌 규칙과 앱 코드에 있는 동의 요청 부분만 다룹니다.
스마트 메시지는 기능성 메시지만 보낼 수 있다
공식 문서는 푸시알림을 미니앱이 사용자에게 보내는 푸시·알림 메시지라고 설명합니다. 주문, 결제, 배송처럼 서비스 이용에 꼭 필요한 정보를 전달하는 용도예요.
푸시와 알림은 문서에서 서로 다른 것으로 구분됩니다. 푸시는 앱을 열지 않은 상태에서도 받는 운영체제 알림이고 앱 이름과 로고가 함께 보입니다. 알림은 토스 앱 오른쪽 위 종 아이콘을 눌렀을 때 보이는 앱 안의 메시지고요. 푸시 내용을 작성하면 알림 메시지에도 자동으로 반영된다고 합니다.
문서가 꼽는 좋은 점은 사용자에게 꼭 필요한 정보를 자동으로 전달할 수 있다는 것, 미니앱을 열지 않아도 중요한 정보를 놓치지 않게 할 수 있다는 것, 발송 결과를 보면서 메시지 내용을 계속 고쳐 갈 수 있다는 것 등입니다.
핵심 제한은 이렇습니다. 수신자가 요청한 정보이거나 서비스 이행에 필요한 필수 메시지여야 하고, 구매 유도, 서비스 이용 유도, 혜택 안내, 리텐션 같은 광고·마케팅 목적의 내용은 넣을 수 없습니다. 그런 내용이 들어가면 광고성 캠페인으로 발송해야 한다고 문서가 안내하고 있어요.
푸시알림으로 보낼 수 있는 문구와 없는 문구
문서에는 허용되는 예시와 허용되지 않는 예시가 따로 있습니다. 허용되는 쪽은 거래, 진행 상황, 이용 기간·상태에 관한 메시지고, 허용되지 않는 쪽은 판촉·광고, 부가적 마케팅 정보, 이벤트 홍보입니다.
예시를 가르는 기준은 “사용자가 이미 한 일이나 신청한 일의 결과를 알려 주는가”로 읽힙니다. 이 구분은 문서 예시를 읽고 제가 묶은 것이고, 문서가 이 문장으로 정의하지는 않아요. 애매한 문구가 검수에서 어떻게 판정되는지는 문서에 없어서 적지 않습니다.
앱인토스 소개 – 어떤 플랫폼이고 왜 해볼 만한가스마트 메시지를 보내기 전에 거치는 순서
푸시알림을 API로 보내려면 호출 전에 콘솔 설정부터 끝내야 합니다. API 문서가 안내하는 사전 준비는 3단계까지이고, 4단계는 그다음 발송입니다.
- 기능성 캠페인 만들기. 콘솔에서 캠페인을 만들면 템플릿 코드(templateSetCode)가 발급됩니다.
- 알림 동의문 연결. 동의문이 필요한 메시지라면 캠페인을 만들기 전에 동의문을 먼저 만들어 캠페인에 연결합니다.
- 문구 검수 승인. 승인 전에는 테스트 메시지도 보낼 수 없습니다.
- 발송. 승인된 템플릿으로 서버에서 API를 호출하거나, 토스에게 발송을 요청합니다.
콘솔 접속 경로는 앱인토스 콘솔의 워크스페이스, 미니앱을 고른 뒤 왼쪽 메뉴의 푸시알림입니다.
발송 방식은 둘로 나뉩니다.
| 방식 | 보내는 시점 | 동의문 |
|---|---|---|
| 직접 API로 발송 | 파트너사 서버에서 원하는 때 | 반려되면 구성 후 재검토 |
| 토스에게 발송 요청 | 일회성 또는 정기(매일, 매주) | 반드시 필요 |
직접 API로 보낼 때 발송 코드는 {appName}-으로 시작해야 하고, 문구 검토에서 알림 동의문이 필요하다고 판단해 반려하면 동의문을 만들어 다시 검토를 요청해야 합니다. 토스에게 요청하는 쪽은 서버가 없어도 되지만 본문에 쓸 수 있는 변수가 이름 변수뿐이에요. API로 보낼 때의 변수는 직접 개발해야 합니다.
알림 동의문이 필요한 경우와 필요 없는 경우
알림 동의문은 사용자가 서비스를 이용하다가 알림 수신에 동의하도록 보여 주는 안내 문구입니다. 문서는 사용자에게서 특정 시점에 알림을 받겠다는 동의를 받는 경우에는 반드시 동의문을 써야 한다고 적었어요.
재입고 알림 신청
이벤트 시작 알림 신청 가격 변동 알림 신청 예약 오픈 알림 신청
결제 완료
배송 시작과 배송 완료 환불 완료 정보 변경, 약관 변경 안내
동의문이 필요한 메시지인데 등록하지 않으면 템플릿을 저장할 수 없습니다. 동의문에는 서비스명과 설명, 알림 발송 시점, 동의 철회 경로, 고객센터 연락처가 들어가는데 서비스명과 연락처는 미니앱 정보에서 자동으로 채워져요.
알림을 받는 사용자 쪽에서는 토스 앱의 전체 탭, 설정, 알림, 서비스별 알림에서 수신 여부를 직접 바꿀 수 있습니다. 문서는 수신을 해제하는 기능을 제공하고 방법을 분명히 안내하길 권장해요.
앱인토스 소개 – AI로 만들고 수익화하는 방법문구는 이렇게 써야 한다
문구 작성 가이드의 기본 규칙은 해요체입니다. 문서는 토스를 쓰는 모든 사용자에게 내 앱을 처음 소개한다는 마음으로 쓰라고 하고, 사용자가 이 푸시를 토스라는 금융 앱의 맥락 안에서 받아들이니 토스답게 자연스럽게 읽히도록 쓰라고 당부합니다. 본문은 문장형으로 쓰고 끝에 마침표를 찍으며, 제목에는 마침표를 쓰지 않아요. 기능성 메시지의 제목은 명사형으로 써야 하는데, 문서는 ‘~하기’로 쓰면 사용자 행동을 유도하는 목적으로 오해받을 수 있다고 설명합니다.
글자 수는 제목 7자, 본문 25자까지고 공백도 센다고 합니다. 글씨를 크게 키워도 잘리지 않는 기준이라고 문서에 적혀 있고, 안드로이드에서 큰 글씨 1.3배 이상이 전체의 24%라는 설명이 붙어 있습니다.
쓸 수 없는 표현도 정해져 있습니다.
- 글자 수를 맞추려고 띄어쓰기를 생략하는 것. “찜한상품이다시입고됐어요”가 나쁜 예시고 “찜한 상품이 다시 입고됐어요”가 좋은 예시입니다.
- 어색한 표현. “상품이 도착이 됐어요” 대신 “상품이 도착했어요”로 쓰라고 합니다.
- ‘토스 + 서비스명’ 형태로 쓰는 것.
- 게임 서비스에서 게임이라고 밝히지 않는 것. 문서는 “[경쟁 퍼즐]” 대신 “[퍼즐 게임]”처럼 쓰라고 하고, 특정 게임에서 파생된 장르명이나 게임 전문 용어도 쓰지 못하게 합니다.
API로 보낼 때 알아둘 한도
서버에서 직접 호출하는 방식에는 몇 가지 숫자가 따라옵니다. 모두 API 문서에 있는 값이에요.
- 서버 간 통신에 mTLS 인증서가 필요합니다.
- 1명에게 보내는 메시지는 사용자 식별키별로 분당 최대 10회까지 호출할 수 있고, 넘으면 오류가 돌아옵니다.
- 대량 메시지는 50건 이상 보낼 때 쓰고, 요청 한 번에 최대 2,500건입니다.
- 받는 사람은 토스 로그인으로 받은
userKey나 사용자 식별키 발급으로 받은anonKey중 하나로 지정하며, 두 값을 동시에 보내면 안 됩니다. - 테스트 메시지는 문구 검수 승인 뒤에 보낼 수 있습니다.
콘솔 안내에는 워크스페이스(사업자)당 10만 건까지 발송할 수 있다는 문장이 있습니다. 어떤 기간 기준인지는 문서에 적혀 있지 않아서, 그 이상은 확인하지 못했습니다.
알림 한도는 바뀔 수 있습니다
위 숫자는 이 글을 쓴 시점의 공식 문서 기준입니다. 보내기 전에 원문에서 다시 확인하세요.
물마시기 앱은 동의 요청을 이렇게 했다
제가 만든 물마시기 미니앱에는 스마트 메시지 알림 동의를 요청하는 코드가 있습니다. 앱 설정 파일에는 알림 일정이 “매일 오후 3시”, 문구가 “지금까지의 물 기록을 확인해보세요.”로 적혀 있어요. 이 문구는 19자입니다.
동의를 받는 흐름은 첫 물 기록 뒤에 인라인 카드를 보여 주고, 눌렀을 때 동의 요청 함수를 부르는 구조입니다. 헤더의 벨 아이콘으로 설정 시트를 열어 다시 신청할 수도 있어요.
동의를 요청하는 부분의 코드입니다. 일부를 줄이지 않고 그대로 옮겼어요.
setNotificationState('working');
notificationCleanup.current?.();
notificationCleanup.current = Notification.requestAgreement({
options: { templateCode: appSpec.notifications.templateCode },
onEvent: ({ type }) => {
const nextState = type === 'agreementRejected' ? 'rejected' : 'agreed';
setNotificationState(nextState);
commit({
...markNotificationPromptSeen(state),
notificationAgreementState: nextState,
});
showToast(nextState === 'agreed' ? '매일 오후 3시에 알려드릴게요' : '알림 없이도 기록할 수 있어요');
},
onError: () => {
setNotificationState('idle');
showToast('알림 신청을 완료하지 못했어요');
},
});코드에서 확인되는 것
- 공식 문서가 동의 결과를 받은 뒤 cleanup 함수를 호출하고, 다시 호출하기 전에 이전 cleanup을 먼저 실행하라고 안내합니다. 위 코드의
notificationCleanup.current?.()가 이전 요청을 먼저 정리하는 줄입니다. - 동의를 거부한 경우(
agreementRejected)와 그 밖의 결과를 갈라서, 거부해도 기록 기능은 그대로 쓰게 두고 안내 문구만 바꿉니다. - 요청 직전에는 토스 앱 버전과
isSupported()를 확인하고, 미지원이면 앱 업데이트를 안내하는 문구를 보여 줍니다. 공식 문서도 미지원 버전에서는 호출 즉시 오류가 나므로isSupported()로 먼저 확인하라고 안내합니다.
이 앱 코드는 동의를 받는 쪽입니다. 알림을 실제로 몇 번 보냈는지, 검수가 어떻게 진행됐는지는 제가 가진 기록에 없어서 이 글에서 다루지 않습니다.
앞 글에서 광고와 정산을 다뤘으니, 알림을 붙이기 전에 수익화 흐름과 같이 읽으면 순서를 잡기 좋습니다.
스마트 메시지 자주 묻는 질문
앱인토스 스마트 메시지로 이벤트나 할인 소식을 보낼 수 있나요?
보낼 수 없습니다. 푸시알림은 기능성 메시지로만 보낼 수 있고, 구매 유도나 혜택 안내, 이벤트 홍보 같은 광고·마케팅 목적의 내용은 넣을 수 없다고 공식 문서에 적혀 있습니다. 그런 내용은 광고성 캠페인으로 발송해야 합니다.
알림 동의문은 항상 받아야 하나요?
메시지 성격에 따라 다릅니다. 결제 완료나 배송 시작처럼 서비스 이용에 꼭 필요한 정보는 동의문 없이 보낼 수 있고, 재입고나 가격 변동처럼 사용자가 특정 알림을 받겠다고 신청하는 경우에는 동의문이 필요합니다. 토스에게 발송을 요청하는 방식은 동의문이 반드시 필요합니다.
푸시알림 제목과 본문은 몇 자까지 쓸 수 있나요?
공식 문서 기준으로 제목은 띄어쓰기를 포함해 7자, 본문은 25자까지입니다. 변수는 2글자로 계산됩니다.
앱인토스는 토스 앱 안에서 미니앱을 서비스하는 플랫폼이고, 공식 안내는 앱인토스 개발자센터에 있습니다.
이 글은 직접 만들고 운영하며 남긴 기록입니다. 적힌 수치는 작성 시점의 제 계정 기준이며, 같은 결과나 수익을 보장하지 않습니다.
