Appearance

기능성 푸시, 알림 발송하기 ​

서비스에서 사용자에게 기능성 푸시 및 알림을 발송할 수 있는 기능이에요.

🚨 잠시만요

기능성 PUSH 메시지 발송을 위해서는 필수적으로 간편 로그인(토스 로그인)을 연동하셔야 해요.

기능성 푸시, 알림은 「정보통신망법」 에 따라 별도의 마케팅 수신 동의 없이도 발송할 수 있어요.
서비스 이용약관 또는 개인정보 처리방침에 관련 내용을 고지하는 것으로 충분합니다.

다만, 사용자가 알림 수신을 해제할 수 있는 기능을 제공하고, 해제 경로를 명확히 안내하는 것을 권장합니다.

토스는 기능성 알림에 대해 별도의 동의 절차를 마련하고 있으며, 사용자가 언제든 동의를 철회할 수 있도록 구성되어 있어요.

Checklist 0

설정하기 ​

푸시, 알림을 발송을 위해서는 콘솔에서 메시지 템플릿 등록이 필요해요. 등록하신 앱 선택 후 메시지 탭에서 설정을 할 수 있어요.

토스앱 사용자에게 적절한 목적으로 라이팅 원칙에 준하는 문구로 발송하는지를 확인하기 위하여 검수 프로세스를 거치고 있어요.
메시지 템플릿 승인까지는 최대 2~3 영업일이 소요됩니다.
따라서, 모든 템플릿들은 승인을 고려하여 필요일 2~3영업일 이전에 템플릿 저장 및 검수 요청을 완료해주세요.

가이드라인을 제공해요

푸시/알림 가이드라인를 확인하세요.

개발하기 ​

메시지를 사용자에게 발송합니다.

  • Content-type : application/json
  • Method : POST
  • URL : /api-partner/v1/apps-in-toss/messenger/send-message

요청 헤더

이름타입필수값 여부설명
x-toss-user-keystringY토스 로그인을 통해 획득한 userKey 값

요청 파라미터

이름타입필수설명
templateSetCodeStringY발송할 메시지 템플릿 코드값
contextobjectY등록된 템플릿의 내용 중 변수 전달
json
{
	"templateSetCode":"test_01", //발송할 메시지 템플릿 코드값
	"context": { // 등록된 템플릿의 내용 중 변수 전달
		"storeName": "토스증권",
		"date": "2025-01-20 15:30"
		// userName 은 발송 시 유저의 이름으로 적용되는 기본 변수이기 때문에 전달할 필요 없음
	}
}

응답

json
{
	"resultType": "SUCCESS" // HTTP_TIMEOUT, NETWORK_ERROR, EXECUTION_FAIL, INTERRUPTED, INTERNAL_ERROR, FAIL
	"result":{
		"msgCount": 1, // 발송 성공 카운트
		"sentPushCount": 1, // 발송 성공 푸시 카운트
		"sentInboxCount: 0, // 발송 성공 Inbox(알림) 카운트
		"sentSmsCount": 0, // 발송 성공 문자 카운트
		"sentAlimtalkCount": 0, // 발송 성공 알림톡 카운트
		"sentFriendtalkCount": 0, // 발송 성공 친구톡 카운트
		"detail": {
			"sentPush":[
				{
					"contentId":"toss:PUSH~~~~", // 발송 성공한 푸시의 메시지 키
				}
			],
			"sentInbox":[], // sentPush 와 동일 포맷
			"sentInbox":[], // sentPush 와 동일 포맷
			"sentSms":[], // sentPush 와 동일 포맷
			"sentAlimtalk":[], // sentPush 와 동일 포맷
			"sentFriendtalk":[], // sentPush 와 동일 포맷
		}
		"fail": {
				"sentPush":[
					{
						"contentId":"toss:PUSH~~~~", // 발송 성공한 푸시의 메시지 키
						"reachFailReason: "실패사유", // 실패 사유
					}
				],
				"sentInbox":[], // sentPush 와 동일 포맷
				"sentInbox":[], // sentPush 와 동일 포맷
				"sentSms":[], // sentPush 와 동일 포맷
				"sentAlimtalk":[], // sentPush 와 동일 포맷
				"sentFriendtalk":[], // sentPush 와 동일 포맷
		}
	},
	"error": {
    "errorType": 0,
    "errorCode": "string",
    "reason": "string",
    "data": {
      "additionalProp1": {},
      "additionalProp2": {},
      "additionalProp3": {}
    },
    "title": "string"
  }
}

json
curl --location 'https://{{domain}}/api-partner/v1/apps-in-toss/messenger/send-message' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{유저 정보 조회에서 나온 userKey}}'
--data '{
	"templateSetCode":"test_01", //발송할 메시지 템플릿 코드값
	"context": { // 등록된 템플릿의 내용 중 변수 전달
		"storeName": "토스증권",
		"date": "2025-01-20 15:30"
		// userName 은 발송 시 유저의 이름으로 적용되는 기본 변수이기 때문에 전달할 필요 없음
	}
}'