푸시, 알림
이 API는 파트너 앱이 토스 사용자에게 알림 또는 메시지를 전송할 수 있게 해줘요. 사용자 인증 토큰이 필요하며, 사용자에게 메시지를 전송할 수 있는 scope 권한이 포함돼야 해요. 테스트 발송을 포함해 모든 메시지는 문구 검수를 통해 승인 받은 이후 발송 가능해요.
비즈니스 오류 코드
아래 오류는 HTTP 200과 resultType: FAIL로 응답해요.
5004
승인되지 않은 메시지 템플릿이에요. 메시지 발송을 하기 위해서는 템플릿 검토 승인이 필요해요.
4034
워크스페이스가 없거나 워크스페이스에 접근할 수 있는 권한이 없어요
4010
인증 정보를 찾을 수 없어요.
4095
요청 한도를 초과했습니다. 잠시 후 다시 시도해주세요.
이 API는 연동된 내부 시스템의 오류 코드를 그대로 전달할 수 있어요. 문서화되지 않은 errorCode는 실패로 처리하고 reason 메시지를 참고하세요.
요청 한도: 앱당 분당 15,000회, 사용자당 분당 10회
파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.
사용자를 인증하기 위한 키예요. 미니앱 SDK의 User.getAnonymousKey 함수로 발급받을 수 있어요
kQ7pL2mZxN9wRt5vB8yD3jF6cA1사용자에게 보낼 메시지를 정의해요. 어떤 메시지 템플릿을 사용할지와 템플릿에 들어갈 데이터를 함께 담아요.
사용할 메시지 템플릿 코드예요. 사전에 등록한 템플릿 코드 중 하나를 넣어요.
ALERT_OTP_TEMPLATE메시지 전송에 성공했어요
요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.
분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.
POST /api-partner/v1/apps-in-toss/messenger/send-message HTTP/1.1
Host: apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json
{
"templateSetCode": "ALERT_OTP_TEMPLATE",
"context": {
"userName": "홍길동",
"otp": "123456"
}
}{
"resultType": "SUCCESS",
"success": {
"detail": {
"sentAlimtalk": [],
"sentFriendtalk": [
{
"contentId": "MSG_FRIENDTALK_0001"
}
],
"sentInbox": [
{
"contentId": "MSG_INBOX_0001"
}
],
"sentPush": [
{
"contentId": "MSG_PUSH_0001"
},
{
"contentId": "MSG_PUSH_0002"
}
],
"sentSms": [
{
"contentId": "MSG_SMS_0001"
}
]
},
"fail": {
"sentAlimtalk": [],
"sentFriendtalk": [
{
"contentId": "MSG_FRIENDTALK_0001"
}
],
"sentInbox": [
{
"contentId": "MSG_INBOX_0001"
}
],
"sentPush": [
{
"contentId": "MSG_PUSH_0001"
},
{
"contentId": "MSG_PUSH_0002"
}
],
"sentSms": [
{
"contentId": "MSG_SMS_0001"
}
]
},
"msgCount": 5,
"sentAlimtalkCount": 0,
"sentFriendtalkCount": 1,
"sentInboxCount": 1,
"sentPushCount": 2,
"sentSmsCount": 1
}
}여러 사용자에게 동일한 템플릿으로 메시지를 대량 발송해요. 최소 50건 이상 대량 발송할때 사용해주세요. 한번 요청 시 최대 2,500건까지 발송 가능해요.
비즈니스 오류 코드
아래 오류는 HTTP 200과 resultType: FAIL로 응답해요.
5004
승인되지 않은 메시지 템플릿이에요. 메시지 발송을 하기 위해서는 템플릿 검토 승인이 필요해요.
4034
워크스페이스가 없거나 워크스페이스에 접근할 수 있는 권한이 없어요
4095
요청 한도를 초과했습니다. 잠시 후 다시 시도해주세요.
이 API는 연동된 내부 시스템의 오류 코드를 그대로 전달할 수 있어요. 문서화되지 않은 errorCode는 실패로 처리하고 reason 메시지를 참고하세요.
요청 한도: 앱당 분당 3,000회
파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.
대량으로 사용자에게 보낼 메시지를 정의해요. 어떤 메시지 템플릿을 사용할지와 템플릿에 들어갈 데이터 목록을 함께 담아요.
사용할 메시지 템플릿 코드예요. 사전에 등록한 템플릿 코드 중 하나를 넣어요.
ALERT_OTP_TEMPLATE요청 처리 결과예요. resultType 값으로 성공/실패를 구분하세요.
요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.
분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.
POST /api-partner/v1/apps-in-toss/messenger/send-bulk-message HTTP/1.1
Host: apps-in-toss-api.toss.im
Content-Type: application/json
{
"templateSetCode": "ALERT_OTP_TEMPLATE",
"contextList": [
{
"userKey": 12345678,
"context": {
"userName": "홍길동",
"otp": "123456"
}
}
]
}{
"resultType": "SUCCESS",
"success": {
"detail": {
"sentAlimtalk": [],
"sentFriendtalk": [
{
"contentId": "MSG_FRIENDTALK_0001"
}
],
"sentInbox": [
{
"contentId": "MSG_INBOX_0001"
}
],
"sentPush": [
{
"contentId": "MSG_PUSH_0001"
},
{
"contentId": "MSG_PUSH_0002"
}
],
"sentSms": [
{
"contentId": "MSG_SMS_0001"
}
]
},
"fail": {
"sentAlimtalk": [],
"sentFriendtalk": [
{
"contentId": "MSG_FRIENDTALK_0001"
}
],
"sentInbox": [
{
"contentId": "MSG_INBOX_0001"
}
],
"sentPush": [
{
"contentId": "MSG_PUSH_0001"
},
{
"contentId": "MSG_PUSH_0002"
}
],
"sentSms": [
{
"contentId": "MSG_SMS_0001"
}
]
},
"msgCount": 5,
"sentAlimtalkCount": 0,
"sentFriendtalkCount": 1,
"sentInboxCount": 1,
"sentPushCount": 2,
"sentSmsCount": 1
}
}이 API는 파트너 앱이 메시지를 수신하고 심사 전 번들이 정상동작하는지 확인할 수 있게 해줘요. 사용자 인증 토큰이 필요하며, 사용자에게 메시지를 전송할 수 있는 scope 권한이 포함돼야 해요. 테스트 발송을 포함해 모든 메시지는 문구 검수를 통해 승인 받은 이후 발송 가능해요.
비즈니스 오류 코드
아래 오류는 HTTP 200과 resultType: FAIL로 응답해요.
4010
인증 정보를 찾을 수 없어요.
4095
요청 한도를 초과했습니다. 잠시 후 다시 시도해주세요.
이 API는 연동된 내부 시스템의 오류 코드를 그대로 전달할 수 있어요. 문서화되지 않은 errorCode는 실패로 처리하고 reason 메시지를 참고하세요.
요청 한도: 앱당 분당 3,000회
파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.
사용자를 인증하기 위한 키예요. 미니앱 SDK의 User.getAnonymousKey 함수로 발급받을 수 있어요
kQ7pL2mZxN9wRt5vB8yD3jF6cA1사용자에게 보낼 메시지를 정의해요. 어떤 메시지 템플릿을 사용할지와 템플릿에 들어갈 데이터를 함께 담아요.
메시지 발송 테스트 시 사용할 번들의 식별값이에요. UUID 형식으로 앱인토스 콘솔의 앱 출시 메뉴에 업로드한 번들에서 확인할 수 있어요.
019abfe8-fd68-7021-9cdc-30d6053cc009사용할 메시지 템플릿 코드예요. 사전에 등록한 템플릿 코드 중 하나를 넣어요.
ALERT_OTP_TEMPLATE메시지 전송에 성공했어요
요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.
분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.
POST /api-partner/v1/apps-in-toss/messenger/send-test-message HTTP/1.1
Host: apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json
{
"templateSetCode": "ALERT_OTP_TEMPLATE",
"deploymentId": "019abfe8-fd68-7021-9cdc-30d6053cc009",
"context": {
"userName": "홍길동",
"otp": "123456"
}
}{
"resultType": "SUCCESS",
"success": {
"detail": {
"sentAlimtalk": [],
"sentFriendtalk": [
{
"contentId": "MSG_FRIENDTALK_0001"
}
],
"sentInbox": [
{
"contentId": "MSG_INBOX_0001"
}
],
"sentPush": [
{
"contentId": "MSG_PUSH_0001"
},
{
"contentId": "MSG_PUSH_0002"
}
],
"sentSms": [
{
"contentId": "MSG_SMS_0001"
}
]
},
"fail": {
"sentAlimtalk": [],
"sentFriendtalk": [
{
"contentId": "MSG_FRIENDTALK_0001"
}
],
"sentInbox": [
{
"contentId": "MSG_INBOX_0001"
}
],
"sentPush": [
{
"contentId": "MSG_PUSH_0001"
},
{
"contentId": "MSG_PUSH_0002"
}
],
"sentSms": [
{
"contentId": "MSG_SMS_0001"
}
]
},
"msgCount": 5,
"sentAlimtalkCount": 0,
"sentFriendtalkCount": 1,
"sentInboxCount": 1,
"sentPushCount": 2,
"sentSmsCount": 1
}
}도움이 되었나요?