Appearance

기능성 PUSH 메시지 발송하기 ​

토스앱을 통해 PUSH/알림을 발송할 수 있는 기능이에요.

🚨 잠시만요

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

시작하기 ​

메시지 템플릿 등록하기 ​

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

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

통신 방화벽 확인하기 ​

In/Out Bound 방화벽 관리를 하신다면 아래 IP를 방화벽에 등록해주세요.

가맹점이 허용해야하는 outbound IP 목록(가맹점 -> 앱인토스)

도메인IPport
apps-in-toss-api-toss.im117.52.3.192, 211.115.96.192, 106.249.5.192443

API 공통규격 확인하기 ​

도메인 정보 ​

https://apps-in-toss-api.toss.im

API 공통 응답 ​

성공

json
// 성공일 경우 resultType이 SUCCESS로 설정되며 해당 API의 응답이 success 하위에 적재됩니다.
{
   "resultType":"SUCCESS",
   "success":{
      "sample":"data"
   }
}

실패

json
// 실패일 경우 resultType 이 FAIL로 설정되며 해당 실패 사유가 error 하위에 적재됩니다.
{
   "resultType":"FAIL",
   "error":{
      "errorCode":"INVALID_PARAMETER",
      "reason":"요청에 실패했습니다."
   }
}

개발하기 ​

메시지 발송하기 ​

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

  • 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 은 발송 시 유저의 이름으로 적용되는 기본 변수이기 때문에 전달할 필요 없음
	}
}'