> 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/documentation/api/push.md).

# 푸시, 알림

## 메시지 발송하기

> 이 API는 파트너 앱이 토스 사용자에게 알림 또는 메시지를 전송할 수 있게 해줘요. 사용자 인증 토큰이 필요하며, 사용자에게 메시지를 전송할 수 있는 scope 권한이 포함돼야 해요. 테스트 발송을 포함해 모든 메시지는 문구 검수를 통해 승인 받은 이후 발송 가능해요.\
> \
> \### 비즈니스 오류 코드\
> \
> 아래 오류는 HTTP 200과 \`resultType: FAIL\`로 응답해요.\
> \
> \| errorCode | 설명 |\
> \| --- | --- |\
> \| \`5004\` | 승인되지 않은 메시지 템플릿이에요. 메시지 발송을 하기 위해서는 템플릿 검토 승인이 필요해요. |\
> \| \`4034\` | 워크스페이스가 없거나 워크스페이스에 접근할 수 있는 권한이 없어요 |\
> \| \`4010\` | 인증 정보를 찾을 수 없어요. |\
> \| \`4095\` | 요청 한도를 초과했어요. 잠시 후 다시 시도해주세요. |\
> \
> \*\*요청 한도\*\*: 앱당 분당 15,000회, 사용자당 분당 10회

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 파트너 API","version":"1.0.0"},"tags":[{"description":"파트너 앱에서 토스 사용자와 메시지를 처리할 때 사용하는 API예요.","name":"push"}],"servers":[{"description":"운영 (간편 로그인·메시지 발송·토스 포인트 지급 등)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 [서버 API 이용하기](https://appsintoss.gitbook.io/appsintoss-docs/gS3ttrb5Le6IDbEbyixR/documentation/integration/server-api) 문서를 참고하세요.","type":"mutualTLS"}},"schemas":{"SendMessageRequest":{"description":"사용자에게 보낼 메시지를 정의해요. 어떤 메시지 템플릿을 사용할지와 템플릿에 들어갈 데이터를 함께 담아요.","properties":{"context":{"additionalProperties":{"type":"object"},"description":"템플릿에서 사용할 변수값들이에요. 예를 들어 사용자 이름이나 인증번호 같은 값을 넣어요.","type":"object"},"templateSetCode":{"description":"사용할 메시지 템플릿 코드예요. 사전에 등록한 템플릿 코드 중 하나를 넣어요.","type":"string"}},"required":["context","templateSetCode"],"type":"object"},"TossApiSuccessSendMessageResponse":{"description":"성공 응답 봉투예요.","properties":{"resultType":{"description":"처리 결과예요. 성공이면 `SUCCESS`예요.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/SendMessageResponse"}},"required":["resultType","success"],"type":"object"},"SendMessageResponse":{"description":"채널별로 몇 건의 메시지가 전송됐는지와 성공/실패한 메시지의 상세 정보가 담겨 있어요.","properties":{"detail":{"$ref":"#/components/schemas/AppendContextResultDetailResponse","description":"성공적으로 전송된 메시지들의 상세 정보예요."},"fail":{"$ref":"#/components/schemas/AppendContextResultDetailResponse","description":"전송에 실패한 메시지들의 상세 정보예요."},"msgCount":{"description":"총 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentAlimtalkCount":{"description":"알림톡으로 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentFriendtalkCount":{"description":"친구톡으로 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentInboxCount":{"description":"인박스(Inbox)로 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentPushCount":{"description":"푸시(Push)로 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentSmsCount":{"description":"SMS로 발송된 메시지 수예요.","format":"int32","type":"integer"}},"required":["detail","fail","msgCount","sentAlimtalkCount","sentFriendtalkCount","sentInboxCount","sentPushCount","sentSmsCount"]},"AppendContextResultDetailResponse":{"description":"각 채널별로 전송된 메시지들의 상세 리스트예요. 어떤 메시지가 어떤 채널에서 성공 또는 실패했는지 알 수 있어요.","properties":{"sentAlimtalk":{"description":"알림톡으로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"},"sentFriendtalk":{"description":"친구톡으로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"},"sentInbox":{"description":"인박스(Inbox)로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"},"sentPush":{"description":"푸시(Push)로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"},"sentSms":{"description":"SMS로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"}},"required":["sentAlimtalk","sentFriendtalk","sentInbox","sentPush","sentSms"]},"SentContentResponse":{"description":"발송된 메시지 한 건에 대한 정보예요.","properties":{"contentId":{"description":"발송된 메시지의 고유 ID예요.","type":"string"},"reachedFailReason":{"description":"메시지 도달에 실패한 경우 실패 사유가 담겨 있어요.","type":"string"}},"required":["contentId"]},"TossApiFail":{"description":"실패 응답 봉투예요. 비즈니스 오류는 HTTP 200으로 응답하니 `resultType`을 반드시 확인하세요.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"처리 결과예요. `SUCCESS`가 아닌 값은 모두 실패로 처리하세요. 일반적으로 `FAIL`이에요.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"실패 시 항상 null이에요."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"오류 상세 정보예요.","properties":{"data":{"description":"오류 부가 정보예요. 요청 한도 초과 시 `retryAfterSeconds`가 담겨요.","type":"object"},"errorCode":{"description":"오류 코드예요. 각 API의 비즈니스 오류 코드 표를 참고하세요.","type":"string"},"errorType":{"description":"내부 오류 분류 값이에요. 오류 구분에는 `errorCode`를 사용하세요.","format":"int32","type":"integer"},"reason":{"description":"사람이 읽을 수 있는 오류 설명이에요.","type":"string"},"title":{"description":"오류 제목이에요. 대부분 null이에요.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"요청 필드 검증에 실패했을 때의 응답이에요.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"처리 결과예요. `SUCCESS`가 아닌 값은 모두 실패로 처리하세요. 일반적으로 `FAIL`이에요.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"실패 시 항상 null이에요."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"오류 상세 정보예요.","properties":{"data":{"description":"오류 부가 정보예요. 요청 한도 초과 시 `retryAfterSeconds`가 담겨요.","properties":{"errorDetails":{"description":"필드별 검증 실패 상세 목록이에요.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"오류 코드예요. 각 API의 비즈니스 오류 코드 표를 참고하세요.","type":"string"},"errorType":{"description":"내부 오류 분류 값이에요. 오류 구분에는 `errorCode`를 사용하세요.","format":"int32","type":"integer"},"reason":{"description":"사람이 읽을 수 있는 오류 설명이에요.","type":"string"},"title":{"description":"오류 제목이에요. 대부분 null이에요.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"필드별 검증 실패 상세 목록이에요.","properties":{"field":{"description":"검증에 실패한 필드 이름이에요.","type":"string"},"message":{"description":"검증 실패 사유예요.","type":"string"},"rejectedValue":{"description":"거부된 입력 값이에요."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/messenger/send-message":{"post":{"description":"이 API는 파트너 앱이 토스 사용자에게 알림 또는 메시지를 전송할 수 있게 해줘요. 사용자 인증 토큰이 필요하며, 사용자에게 메시지를 전송할 수 있는 scope 권한이 포함돼야 해요. 테스트 발송을 포함해 모든 메시지는 문구 검수를 통해 승인 받은 이후 발송 가능해요.\n\n### 비즈니스 오류 코드\n\n아래 오류는 HTTP 200과 `resultType: FAIL`로 응답해요.\n\n| errorCode | 설명 |\n| --- | --- |\n| `5004` | 승인되지 않은 메시지 템플릿이에요. 메시지 발송을 하기 위해서는 템플릿 검토 승인이 필요해요. |\n| `4034` | 워크스페이스가 없거나 워크스페이스에 접근할 수 있는 권한이 없어요 |\n| `4010` | 인증 정보를 찾을 수 없어요. |\n| `4095` | 요청 한도를 초과했어요. 잠시 후 다시 시도해주세요. |\n\n**요청 한도**: 앱당 분당 15,000회, 사용자당 분당 10회","operationId":"sendMessage","parameters":[{"description":"사용자를 인증하기 위한 키예요. [사용자 정보 받기](https://appsintoss.gitbook.io/appsintoss-docs/gS3ttrb5Le6IDbEbyixR/documentation/api/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API를 통해 획득할 수 있어요","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"사용자를 인증하기 위한 키예요. 미니앱 SDK의 [User.getAnonymousKey](https://appsintoss.gitbook.io/appsintoss-docs/gS3ttrb5Le6IDbEbyixR/documentation/sdk/domains-api/user/user.getanonymouskey) 함수로 발급받을 수 있어요","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}},"description":"전송할 메시지의 정보예요","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessSendMessageResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessSendMessageResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"메시지 전송에 성공했어요"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"요청 본문이 형식에 맞지 않아요. `error.data.errorDetails`에서 필드별 상세를 확인하세요."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요."}},"summary":"메시지 발송하기","tags":["push"]}}}}
```

## 대량 메시지 발송하기

> 여러 사용자에게 동일한 템플릿으로 메시지를 대량 발송해요. 최소 50건 이상 대량 발송할때 사용해주세요. 한번 요청 시 최대 2,500건까지 발송 가능해요.\
> \
> \### 비즈니스 오류 코드\
> \
> 아래 오류는 HTTP 200과 \`resultType: FAIL\`로 응답해요.\
> \
> \| errorCode | 설명 |\
> \| --- | --- |\
> \| \`5004\` | 승인되지 않은 메시지 템플릿이에요. 메시지 발송을 하기 위해서는 템플릿 검토 승인이 필요해요. |\
> \| \`4034\` | 워크스페이스가 없거나 워크스페이스에 접근할 수 있는 권한이 없어요 |\
> \| \`4095\` | 요청 한도를 초과했어요. 잠시 후 다시 시도해주세요. |\
> \
> \*\*요청 한도\*\*: 앱당 분당 3,000회

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 파트너 API","version":"1.0.0"},"tags":[{"description":"파트너 앱에서 토스 사용자와 메시지를 처리할 때 사용하는 API예요.","name":"push"}],"servers":[{"description":"운영 (간편 로그인·메시지 발송·토스 포인트 지급 등)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 [서버 API 이용하기](https://appsintoss.gitbook.io/appsintoss-docs/gS3ttrb5Le6IDbEbyixR/documentation/integration/server-api) 문서를 참고하세요.","type":"mutualTLS"}},"schemas":{"BulkSendMessageRequest":{"description":"대량으로 사용자에게 보낼 메시지를 정의해요. 어떤 메시지 템플릿을 사용할지와 템플릿에 들어갈 데이터 목록을 함께 담아요.","properties":{"contextList":{"description":"메시지를 받을 사용자의 userKey 또는 anonKey와 변수값 목록이에요.","items":{"$ref":"#/components/schemas/BulkSendMessageContext"},"type":"array"},"templateSetCode":{"description":"사용할 메시지 템플릿 코드예요. 사전에 등록한 템플릿 코드 중 하나를 넣어요.","type":"string"}},"required":["contextList","templateSetCode"]},"BulkSendMessageContext":{"description":"대량 메시지 발송 시 수신자 한 명에 대한 정보와 템플릿 변수값을 담은 항목이에요.","properties":{"anonKey":{"description":"앱에서 발급받은 익명 사용자 식별자에요.","type":"string"},"context":{"additionalProperties":{"type":"object"},"description":"템플릿에서 사용할 변수값들이에요. 예를 들어 사용자 이름이나 인증번호 같은 값을 넣어요.","type":"object"},"userKey":{"description":"사용자의 고유 식별자에요.","format":"int64","type":"integer"}},"required":["context"]},"TossApiSuccessBulkSendMessageResponse":{"description":"성공 응답 봉투예요.","properties":{"resultType":{"description":"처리 결과예요. 성공이면 `SUCCESS`예요.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/BulkSendMessageResponse"}},"required":["resultType","success"],"type":"object"},"BulkSendMessageResponse":{"description":"채널별로 몇 건의 메시지가 전송됐는지와 성공/실패한 메시지의 상세 정보가 담겨 있어요.","properties":{"detail":{"$ref":"#/components/schemas/AppendContextResultDetailResponse","description":"성공적으로 전송된 메시지들의 상세 정보예요."},"fail":{"$ref":"#/components/schemas/AppendContextResultDetailResponse","description":"전송에 실패한 메시지들의 상세 정보예요."},"msgCount":{"description":"총 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentAlimtalkCount":{"description":"알림톡으로 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentFriendtalkCount":{"description":"친구톡으로 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentInboxCount":{"description":"인박스(Inbox)로 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentPushCount":{"description":"푸시(Push)로 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentSmsCount":{"description":"SMS로 발송된 메시지 수예요.","format":"int32","type":"integer"}},"required":["detail","fail","msgCount","sentAlimtalkCount","sentFriendtalkCount","sentInboxCount","sentPushCount","sentSmsCount"]},"AppendContextResultDetailResponse":{"description":"각 채널별로 전송된 메시지들의 상세 리스트예요. 어떤 메시지가 어떤 채널에서 성공 또는 실패했는지 알 수 있어요.","properties":{"sentAlimtalk":{"description":"알림톡으로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"},"sentFriendtalk":{"description":"친구톡으로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"},"sentInbox":{"description":"인박스(Inbox)로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"},"sentPush":{"description":"푸시(Push)로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"},"sentSms":{"description":"SMS로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"}},"required":["sentAlimtalk","sentFriendtalk","sentInbox","sentPush","sentSms"]},"SentContentResponse":{"description":"발송된 메시지 한 건에 대한 정보예요.","properties":{"contentId":{"description":"발송된 메시지의 고유 ID예요.","type":"string"},"reachedFailReason":{"description":"메시지 도달에 실패한 경우 실패 사유가 담겨 있어요.","type":"string"}},"required":["contentId"]},"TossApiFail":{"description":"실패 응답 봉투예요. 비즈니스 오류는 HTTP 200으로 응답하니 `resultType`을 반드시 확인하세요.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"처리 결과예요. `SUCCESS`가 아닌 값은 모두 실패로 처리하세요. 일반적으로 `FAIL`이에요.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"실패 시 항상 null이에요."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"오류 상세 정보예요.","properties":{"data":{"description":"오류 부가 정보예요. 요청 한도 초과 시 `retryAfterSeconds`가 담겨요.","type":"object"},"errorCode":{"description":"오류 코드예요. 각 API의 비즈니스 오류 코드 표를 참고하세요.","type":"string"},"errorType":{"description":"내부 오류 분류 값이에요. 오류 구분에는 `errorCode`를 사용하세요.","format":"int32","type":"integer"},"reason":{"description":"사람이 읽을 수 있는 오류 설명이에요.","type":"string"},"title":{"description":"오류 제목이에요. 대부분 null이에요.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"요청 필드 검증에 실패했을 때의 응답이에요.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"처리 결과예요. `SUCCESS`가 아닌 값은 모두 실패로 처리하세요. 일반적으로 `FAIL`이에요.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"실패 시 항상 null이에요."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"오류 상세 정보예요.","properties":{"data":{"description":"오류 부가 정보예요. 요청 한도 초과 시 `retryAfterSeconds`가 담겨요.","properties":{"errorDetails":{"description":"필드별 검증 실패 상세 목록이에요.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"오류 코드예요. 각 API의 비즈니스 오류 코드 표를 참고하세요.","type":"string"},"errorType":{"description":"내부 오류 분류 값이에요. 오류 구분에는 `errorCode`를 사용하세요.","format":"int32","type":"integer"},"reason":{"description":"사람이 읽을 수 있는 오류 설명이에요.","type":"string"},"title":{"description":"오류 제목이에요. 대부분 null이에요.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"필드별 검증 실패 상세 목록이에요.","properties":{"field":{"description":"검증에 실패한 필드 이름이에요.","type":"string"},"message":{"description":"검증 실패 사유예요.","type":"string"},"rejectedValue":{"description":"거부된 입력 값이에요."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/messenger/send-bulk-message":{"post":{"description":"여러 사용자에게 동일한 템플릿으로 메시지를 대량 발송해요. 최소 50건 이상 대량 발송할때 사용해주세요. 한번 요청 시 최대 2,500건까지 발송 가능해요.\n\n### 비즈니스 오류 코드\n\n아래 오류는 HTTP 200과 `resultType: FAIL`로 응답해요.\n\n| errorCode | 설명 |\n| --- | --- |\n| `5004` | 승인되지 않은 메시지 템플릿이에요. 메시지 발송을 하기 위해서는 템플릿 검토 승인이 필요해요. |\n| `4034` | 워크스페이스가 없거나 워크스페이스에 접근할 수 있는 권한이 없어요 |\n| `4095` | 요청 한도를 초과했어요. 잠시 후 다시 시도해주세요. |\n\n**요청 한도**: 앱당 분당 3,000회","operationId":"sendBulkMessage","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSendMessageRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessBulkSendMessageResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessBulkSendMessageResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"요청 처리 결과예요. `resultType` 값으로 성공/실패를 구분하세요."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"요청 본문이 형식에 맞지 않아요. `error.data.errorDetails`에서 필드별 상세를 확인하세요."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요."}},"summary":"대량 메시지 발송하기","tags":["push"]}}}}
```

## 테스트 메시지 발송하기

> 이 API는 파트너 앱이 메시지를 수신하고 심사 전 번들이 정상동작하는지 확인할 수 있게 해줘요. 사용자 인증 토큰이 필요하며, 사용자에게 메시지를 전송할 수 있는 scope 권한이 포함돼야 해요. 테스트 발송을 포함해 모든 메시지는 문구 검수를 통해 승인 받은 이후 발송 가능해요.\
> \
> \### 비즈니스 오류 코드\
> \
> 아래 오류는 HTTP 200과 \`resultType: FAIL\`로 응답해요.\
> \
> \| errorCode | 설명 |\
> \| --- | --- |\
> \| \`4010\` | 인증 정보를 찾을 수 없어요. |\
> \| \`4095\` | 요청 한도를 초과했어요. 잠시 후 다시 시도해주세요. |\
> \
> \*\*요청 한도\*\*: 앱당 분당 3,000회

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 파트너 API","version":"1.0.0"},"tags":[{"description":"파트너 앱에서 토스 사용자와 메시지를 처리할 때 사용하는 API예요.","name":"push"}],"servers":[{"description":"운영 (간편 로그인·메시지 발송·토스 포인트 지급 등)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 [서버 API 이용하기](https://appsintoss.gitbook.io/appsintoss-docs/gS3ttrb5Le6IDbEbyixR/documentation/integration/server-api) 문서를 참고하세요.","type":"mutualTLS"}},"schemas":{"TestSendMessageRequest":{"description":"사용자에게 보낼 메시지를 정의해요. 어떤 메시지 템플릿을 사용할지와 템플릿에 들어갈 데이터를 함께 담아요.","properties":{"context":{"additionalProperties":{"type":"object"},"description":"템플릿에서 사용할 변수값들이에요. 예를 들어 사용자 이름이나 인증번호 같은 값을 넣어요.","type":"object"},"deploymentId":{"description":"메시지 발송 테스트 시 사용할 번들의 식별값이에요. UUID 형식으로 앱인토스 콘솔의 앱 출시 메뉴에 업로드한 번들에서 확인할 수 있어요.","type":"string"},"templateSetCode":{"description":"사용할 메시지 템플릿 코드예요. 사전에 등록한 템플릿 코드 중 하나를 넣어요.","type":"string"}},"required":["context","deploymentId","templateSetCode"],"type":"object"},"TossApiSuccessTestSendMessageResponse":{"description":"성공 응답 봉투예요.","properties":{"resultType":{"description":"처리 결과예요. 성공이면 `SUCCESS`예요.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/TestSendMessageResponse"}},"required":["resultType","success"],"type":"object"},"TestSendMessageResponse":{"description":"채널별로 몇 건의 메시지가 전송됐는지와 성공/실패한 메시지의 상세 정보가 담겨 있어요.","properties":{"detail":{"$ref":"#/components/schemas/AppendContextResultDetailResponse","description":"성공적으로 전송된 메시지들의 상세 정보예요."},"fail":{"$ref":"#/components/schemas/AppendContextResultDetailResponse","description":"전송에 실패한 메시지들의 상세 정보예요."},"msgCount":{"description":"총 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentAlimtalkCount":{"description":"알림톡으로 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentFriendtalkCount":{"description":"친구톡으로 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentInboxCount":{"description":"인박스(Inbox)로 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentPushCount":{"description":"푸시(Push)로 발송된 메시지 수예요.","format":"int32","type":"integer"},"sentSmsCount":{"description":"SMS로 발송된 메시지 수예요.","format":"int32","type":"integer"}},"required":["detail","fail","msgCount","sentAlimtalkCount","sentFriendtalkCount","sentInboxCount","sentPushCount","sentSmsCount"]},"AppendContextResultDetailResponse":{"description":"각 채널별로 전송된 메시지들의 상세 리스트예요. 어떤 메시지가 어떤 채널에서 성공 또는 실패했는지 알 수 있어요.","properties":{"sentAlimtalk":{"description":"알림톡으로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"},"sentFriendtalk":{"description":"친구톡으로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"},"sentInbox":{"description":"인박스(Inbox)로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"},"sentPush":{"description":"푸시(Push)로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"},"sentSms":{"description":"SMS로 발송된 메시지 목록이에요.","items":{"$ref":"#/components/schemas/SentContentResponse"},"type":"array"}},"required":["sentAlimtalk","sentFriendtalk","sentInbox","sentPush","sentSms"]},"SentContentResponse":{"description":"발송된 메시지 한 건에 대한 정보예요.","properties":{"contentId":{"description":"발송된 메시지의 고유 ID예요.","type":"string"},"reachedFailReason":{"description":"메시지 도달에 실패한 경우 실패 사유가 담겨 있어요.","type":"string"}},"required":["contentId"]},"TossApiFail":{"description":"실패 응답 봉투예요. 비즈니스 오류는 HTTP 200으로 응답하니 `resultType`을 반드시 확인하세요.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"처리 결과예요. `SUCCESS`가 아닌 값은 모두 실패로 처리하세요. 일반적으로 `FAIL`이에요.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"실패 시 항상 null이에요."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"오류 상세 정보예요.","properties":{"data":{"description":"오류 부가 정보예요. 요청 한도 초과 시 `retryAfterSeconds`가 담겨요.","type":"object"},"errorCode":{"description":"오류 코드예요. 각 API의 비즈니스 오류 코드 표를 참고하세요.","type":"string"},"errorType":{"description":"내부 오류 분류 값이에요. 오류 구분에는 `errorCode`를 사용하세요.","format":"int32","type":"integer"},"reason":{"description":"사람이 읽을 수 있는 오류 설명이에요.","type":"string"},"title":{"description":"오류 제목이에요. 대부분 null이에요.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"요청 필드 검증에 실패했을 때의 응답이에요.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"처리 결과예요. `SUCCESS`가 아닌 값은 모두 실패로 처리하세요. 일반적으로 `FAIL`이에요.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"실패 시 항상 null이에요."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"오류 상세 정보예요.","properties":{"data":{"description":"오류 부가 정보예요. 요청 한도 초과 시 `retryAfterSeconds`가 담겨요.","properties":{"errorDetails":{"description":"필드별 검증 실패 상세 목록이에요.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"오류 코드예요. 각 API의 비즈니스 오류 코드 표를 참고하세요.","type":"string"},"errorType":{"description":"내부 오류 분류 값이에요. 오류 구분에는 `errorCode`를 사용하세요.","format":"int32","type":"integer"},"reason":{"description":"사람이 읽을 수 있는 오류 설명이에요.","type":"string"},"title":{"description":"오류 제목이에요. 대부분 null이에요.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"필드별 검증 실패 상세 목록이에요.","properties":{"field":{"description":"검증에 실패한 필드 이름이에요.","type":"string"},"message":{"description":"검증 실패 사유예요.","type":"string"},"rejectedValue":{"description":"거부된 입력 값이에요."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/messenger/send-test-message":{"post":{"description":"이 API는 파트너 앱이 메시지를 수신하고 심사 전 번들이 정상동작하는지 확인할 수 있게 해줘요. 사용자 인증 토큰이 필요하며, 사용자에게 메시지를 전송할 수 있는 scope 권한이 포함돼야 해요. 테스트 발송을 포함해 모든 메시지는 문구 검수를 통해 승인 받은 이후 발송 가능해요.\n\n### 비즈니스 오류 코드\n\n아래 오류는 HTTP 200과 `resultType: FAIL`로 응답해요.\n\n| errorCode | 설명 |\n| --- | --- |\n| `4010` | 인증 정보를 찾을 수 없어요. |\n| `4095` | 요청 한도를 초과했어요. 잠시 후 다시 시도해주세요. |\n\n**요청 한도**: 앱당 분당 3,000회","operationId":"sendTestMessage","parameters":[{"description":"사용자를 인증하기 위한 키예요. [사용자 정보 받기](https://appsintoss.gitbook.io/appsintoss-docs/gS3ttrb5Le6IDbEbyixR/documentation/api/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API를 통해 획득할 수 있어요","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"사용자를 인증하기 위한 키예요. 미니앱 SDK의 [User.getAnonymousKey](https://appsintoss.gitbook.io/appsintoss-docs/gS3ttrb5Le6IDbEbyixR/documentation/sdk/domains-api/user/user.getanonymouskey) 함수로 발급받을 수 있어요","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestSendMessageRequest"}}},"description":"전송할 메시지의 정보예요","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessTestSendMessageResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessTestSendMessageResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"메시지 전송에 성공했어요"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"요청 본문이 형식에 맞지 않아요. `error.data.errorDetails`에서 필드별 상세를 확인하세요."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요."}},"summary":"테스트 메시지 발송하기","tags":["push"]}}}}
```


---

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api/push.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.