친구톡 API
- 인쇄
- PDF
친구톡 API
- 인쇄
- PDF
기사 요약
이 요약이 도움이 되었나요?
의견을 보내 주셔서 감사합니다.
기본 정보
API URL
https://sens.apigw.fin-ntruss.com/friendtalk/v2
참고
네이버 클라우드 플랫폼[Financial]에서 제공되는 Simple & Easy Notification Service 의 API는 금융 보안 요건에 따라 인터넷을 통합 접근이 불가능합니다. 인터넷을 통한 접근이 필요할 경우 SSL VPN을 통해서만 접근할 수 있습니다. SSL VPN 접속에 대한 자세한 설명은 네이버 클라우드 플랫폼 포털 이용 안내를 참조해 주십시오.
API Header
항목 | Mandatory | 설명 |
---|---|---|
Content-Type | Mandatory | 요청 Body Content Type을 application/json으로 지정 (POST) |
x-ncp-apigw-timestamp | Mandatory | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타낸 것 API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주 |
x-ncp-iam-access-key | Mandatory | 포탈 또는 Sub Account에서 발급받은 Access Key ID |
x-ncp-apigw-signature-v2 | Mandatory | 위 예제의 Body를 Access Key Id와 맵핑되는 SecretKey로 암호화한 서명 HMAC 암호화 알고리즘은 HmacSHA256 사용 |
NAVER CLOUD PLATFORM 인증키 및 Signature 생성 가이드 바로가기
메시지
메시지 발송
메시지를 발송합니다.
요청 URL
POST https://sens.apigw.fin-ntruss.com/friendtalk/v2/services/{serviceId}/messages
Content-Type: application/json; charset=utf-8
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
Headers
요청 Body
{
"plusFriendId":"string",
"messages":[
{
"isAd":"string",
"countryCode":"string",
"to":"string",
"content":"string",
"buttons":[
{
"type":"string",
"name":"string",
"linkMobile":"string",
"linkPc":"string",
"schemeIos":"string",
"schemeAndroid":"string"
}
],
"image":{
"imageId":"string",
"imageLink":"string"
},
"useSmsFailover": "boolean",
"failoverConfig": {
"type": "string",
"from": "string",
"subject": "string",
"content": "string"
}
}
],
"reserveTime": "yyyy-MM-dd HH:mm",
"reserveTimeZone": "string"
}
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
plusFriendId | Mandatory | String | 카카오톡 채널명 ((구)플러스친구 아이디) | |
messages | Mandatory | Object | 메시지 정보 | 아래 항목들 참조 (messages.XXX) 최대 100개 |
messages.isAd | Optional | Boolean | 광고 메시지 여부 | default: true 광고 메시지로 발송하시는 경우(isAd: true), SMS Failover 동작 시 광고 메시지 전송 표기 의무를 준수해야합니다. |
messages.countryCode | Optional | String | 수신자 국가번호 | default: 82 |
messages.to | Mandatory | String | 수신자번호 | |
messages.content | Mandatory | String | 친구톡 메시지 내용 | |
messages.buttons | Optional | Array of Object | 친구톡 메시지 버튼 | 버튼 정보 참조 |
messages.buttons.type | Mandatory | String | 버튼 Type | 아래 템플릿 버튼 정보 참조 |
messages.buttons.name | Mandatory | String | 버튼명 | 아래 템플릿 버튼 정보 참조 |
messages.image | Optional | Object | 이미지 정보 | 이미지 업로드 참조 |
messages.image.imageId | Mandatory | String | 업로드된 이미지 아이디 | |
messages.image.imageLink | Mandatory | String | 이미지 링크 | |
messages.useSmsFailover | Optional | Boolean | SMS Failover 사용 여부 | Failover가 설정된 카카오톡 채널에서만 사용 가능 기본: 카카오톡 채널의 Failover 설정 여부를 따름 |
messages.failoverConfig | Optional | Object | Failover 설정 | 아래 항목들 참조 |
messages.failoverConfig.type | Optional | String | Failover SMS 메시지 Type | SMS or LMS 기본: content 길이에 따라 자동 적용 (90 bytes 이하 SMS, 초과 LMS) |
messages.failoverConfig.from | Optional | String | Failover SMS 발신번호 | 기본: Failover 설정 시 선택한 발신번호 승인되지 않은 발신번호 사용시, Failover 동작 안함 |
messages.failoverConfig.subject | Optional | String | Failover SMS 제목 | LMS type으로 동작할 때 사용 기본: 카카오톡 채널명 |
messages.failoverConfig.content | Optional | String | Failover SMS 내용 | 기본: 친구톡 메시지 내용 (버튼 제외) |
reserveTime | Optional | String | 예약 일시 | 메시지 발송 예약 일시 (yyyy-MM-dd HH:mm) |
reserveTimeZone | Optional | String | 예약 일시 타임존 | 예약 일시 타임존 (기본: Asia/Seoul) * 지원 타임존 목록 * TZ database name 값 사용 |
- 요청 Body의 Mandatory 필드를 사용하시는 경우, 공백은 허용되지않습니다. (추가하는 경우에만 해당)
- SMS Failover는 비즈메시지 수신 결과 코드 기준, 성공이 아닌 경우 동작하며, prefix로 B가 붙은 코드들에 대해서는 failover 기능을 통한 SMS 대체 발송이 이루어지지 않습니다.
Status | Error text | Desc |
---|---|---|
0000 | - | 정상 발송 |
3022 | NoSendAvailableTimeException | 메시지 발송 가능한 시간이 아님 (친구 톡/마케팅 메시지는 08시~ 20시 50분까지 발송 가능) |
Bxxx | 하단 비즈메시지 수신 결과 코드 참고 | 하단 비즈메시지 수신 결과 코드 참고 |
- 광고 메시지 발송 시 SMS Failover에 설정된 SMS 서비스의 080수신거부 서비스를 사용합니다.
- 설정된 SMS 서비스에 080수신거부 서비스가 사용 가능한 상태가 아니라면, SMS Failover는 실패합니다.
failoverConfig.content
를 별도로 지정하지 않고 사용하시는 경우, SMS Failover시 자동으로 광고 표기 문구를 삽입합니다.[광고]{메시지내용} 무료수신거부번호08012345678
failoverConfig.content
를 별도로 직접 지정하시는 경우, 광고 표기 문구를 삽입하지 않습니다. 광고 메시지 발송 시 직접 추가해 주십시오.- 광고 표기 의무를 준수하지 않은 SMS 메시지 발송 시, 추후 소명이 필요할 수 있습니다.
- 와이드 이미지 발송 시, 텍스트 + 링크 버튼(1개) + 이미지 발송이 가능합니다.
- 2개 이상의 버튼 추가시, 메시지 발송에 실패합니다. (잘못된 파라미터 요청)
- 텍스트 문구는 76자로 제한됩니다.
버튼 정보
Type | Name | Mandatory 항목 |
---|---|---|
WL | 웹 링크 | linkMobile, linkPc (http:// 또는 https://로 시작하는 URL) |
AL | 앱 링크 | schemeIos, schemeAndroid |
BK | 봇 키워드 | |
MD | 메시지 전달 | |
AC | 채널 추가 |
응답 Body
{
"requestId":"string",
"requestTime":"string",
"statusCode":"string",
"statusName":"string",
"messages":[
{
"messageId":"string",
"countryCode":"string",
"to":"string",
"content":"string",
"requestStatusCode":"string",
"requestStatusName":"string",
"requestStatusDesc":"string",
"useSmsFailover":"boolean"
}
]
}
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
requestId | Mandatory | String | 발송 요청 아이디 | |
requestTime | Mandatory | DateTime | 발송 요청 시간 | yyyy-MM-dd'T'HH:mm:ss.SSS |
statusCode | Mandatory | String | 요청 상태 코드 | 202 - 성공 그외 - 실패 * HTTP Status 규격을 따름 |
statusName | Mandatory | String | 요청 상태명 | success - 성공 processing - 처리중 reserved - 예약중 fail - 실패 |
messages.messageId | Mandatory | String | 메시지 아이디 | |
messages.countryCode | Optional | String | 수신자 국가번호 | default: 82 |
messages.to | Mandatory | String | 수신자번호 | |
messages.content | Mandatory | String | 친구톡 메시지 내용 | |
messages.requestStatusCode | Mandatory | String | 발송요청 상태 코드 | A000 - 성공 그외 코드 - 실패(Desc 항목에 실패 사유가 명시) |
messages.requestStatusName | Mandatory | String | 발송요청 상태명 | success - 성공 fail - 실패 |
messages.requestStatusDesc | Mandatory | String | 발송요청 상태 내용 | |
messages.useSmsFailover | Mandatory | Boolean | SMS Failover 사용 여부 |
응답 Status
HTTP Status | Desc |
---|---|
202 | Accepted (발송 요청 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
메시지 발송 요청 조회
메시지 발송 요청을 조회합니다.
요청 URL
GET https://sens.apigw.fin-ntruss.com/friendtalk/v2/services/{serviceId}/messages?requestId=
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
Parameters
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
requestId | Mandatory | String | 요청 아이디 | 발송 요청 아이디 |
plusFriendId | Mandatory | String | 카카오 채널 | 등록된 채널 명 |
requestStartTime | Mandatory | String | 조회 시간 시작 시각 | yyyy-MM-dd'T'HH:mm:ss |
requestEndTime | Mandatory | String | 조회 시간 종료 시각 | yyyy-MM-dd'T'HH:mm:ss |
completeStartTime | Mandatory | String | 발송 완료 시작 시간 | yyyy-MM-dd'T'HH:mm:ss |
completeEndTime | Mandatory | String | 발송 완료 종료 시간 | yyyy-MM-dd'T'HH:mm:ss |
messageId | Optional | String | 메시지 아이디 | |
requestStatusName | Optional | String | 요청 상태 | success, fail |
messageStatusName | Optional | String | 요청 상태 | success, processing, fail |
to | Optional | String | 메세지 수신 번호 | 붙임표 (-)를 제외한 번호 |
pageIndex | Optional | Integer | 페이지 번호 | default: 0 |
pageSize | Optional | Integer | 페이지 크기 | default: 20, max: 100 requestId를 포함한 조회시, default: 100 |
참고
- 메시지 발송 이력은 최근 30일 이내의 이력만 조회할 수 있습니다.
- requestId 또는 requestStartTime + requestEndTime 또는 completeStartTime + completeEndTime 중에 하나는 필수입니다.
- requestStartTime + requestEndTime과 completeStartTime + completeEndTime은 동시에 사용할 수 없습니다.
- requestStartTime ~ requestEndTime의 조회 범위는 최대 31일로 제한됩니다.
- completeStartTime ~ completeEndTime의 조회 범위는 최대 24시간으로 제한됩니다.
- 조회 조건에 requestId가 포함되어있지않은 경우, plusFriendId는 필수입니다.
Headers
요청 Body
없음
응답 Body
{
"requestId": "string",
"statusCode": "string",
"statusName": "string",
"messages": [
{
"requestTime": "string",
"messageId": "string",
"countryCode": "string",
"to": "string",
"content": "string",
"plusFriendId": "string",
"completeTime": "string",
"requestStatusCode": "string",
"requestStatusName": "string",
"requestStatusDesc": "string",
"messageStatusCode": "string",
"messageStatusName": "string",
"messageStatusDesc": "string",
"isWide": "boolean",
"isAd": "boolean",
"useSmsFailover": "boolean",
"failover": {
"smsServiceId": "string",
"requestId": "string",
"messageId": "string",
"requestStatusCode": "string",
"requestStatusName": "string",
"requestStatusDesc": "string",
"messageStatus": "string",
"messageStatusCode": "string",
"messageStatusName": "string",
"messageStatusDesc": "string"
}
}
],
"pageSize": "integer",
"pageIndex": "integer",
"itemCount": "integer",
"hasMore": "boolean"
}
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
requestId | Optional | String | 발송 요청 아이디 | requestId로 조회하는 경우에만 노출됨 |
statusCode | Mandatory | String | 요청 상태 코드 | 202 - 성공 그외 - 실패 * HTTP Status 규격을 따름 |
statusName | Mandatory | String | 요청 상태명 | success - 성공 processing - 발송중 reserved - 예약중 fail - 실패 |
messages.requestTime | Mandatory | DateTime | 발송 요청 시간 | yyyy-MM-dd'T'HH:mm:ss.SSS |
messages.messageId | Mandatory | String | 메시지 아이디 | |
messages.countryCode | Optional | String | 수신자 국가번호 | default: 82 |
messages.to | Mandatory | String | 수신자번호 | |
messages.content | Mandatory | String | 친구톡 메시지 내용 | |
messages.plusFriendId | Mandatory | String | 카카오톡 채널명 ((구)플러스친구 아이디) | |
messages.completeTime | Optional | DateTime | 발송 리포트(처리 완료) 시간 | yyyy-MM-dd'T'HH:mm:ss |
messages.requestStatusCode | Mandatory | String | 발송요청 상태 코드 | A000 - 성공 그외 코드 - 실패(Desc 항목에 실패 사유가 명시) |
messages.requestStatusName | Mandatory | String | 발송요청 상태명 | success - 성공 fail - 실패 |
messages.requestStatusDesc | Mandatory | String | 발송요청 상태 내용 | |
messages.messageStatusCode | Mandatory | String | 발송결과 상태 코드 | 0000 - 성공 그외 코드 - 실패(Desc 항목에 실패 사유가 명시) |
messages.messageStatusName | Mandatory | String | 발송결과 상태명 | success - 성공 processing - 처리중 * 발송요청 성공 후, 메시지 발송서버에서 처리중인 상태 * messageCode, messageDesc가 조회되지 않음 fail - 실패 |
messages.messageStatusDesc | Mandatory | String | 발송결과 상태 내용 | |
messages.isWide | Mandatory | Boolean | 와이드 여부 | |
messages.isAd | Mandatory | Boolean | 광고메시지 여부 | |
messages.useSmsFailover | Mandatory | Boolean | SMS Failover 사용 여부 | |
messages.failover | Optional | Object | SMS Failover | |
messages.failover.smsServiceId | Optional | String | SMS Failover 서비스 아이디 | |
messages.failover.requestId | Optional | String | SMS Failover 발송 요청 아이디 | |
messages.failover.messageId | Optional | String | SMS Failover 발송 메시지 아이디 | |
messages.failover.requestStatusCode | Optional | String | SMS Failover 발송 요청 상태 코드 | 오류 코드 표 참고 |
messages.failover.requestStatusName | Optional | String | SMS Failover 발송 요청 상태명 | success - 성공 fail - 실패 |
messages.failover.requestStatusDesc | Optional | String | SMS Failover 발송 요청 상태 내용 | |
messages.failover.messageStatus | Optional | String | SMS Failover 발송 처리 상태 | READY: 대기 PROCESSING: 처리 중 COMPLETED: 처리 완료 |
messages.failover.messageStatusCode | Optional | String | SMS Failover 발송 단말 수신 상태 결과 코드 | 오류 코드 표 참고 |
messages.failover.messageStatusName | Optional | String | SMS Failover 발송 단말 수신 결과명 | |
messages.failover.messageStatusDesc | Optional | String | SMS Failover 발송 단말 수신 내용 | |
pageSize | Mandatory | Integer | 페이지 사이즈 | |
pageIndex | Mandatory | Integer | 페이지 인덱스 (0부터 시작) | |
itemCount | Mandatory | Integer | 조회한 페이지 내의 메시지 수 | |
hasMore | Mandatory | Boolean | 다음 페이지 존재 여부 |
응답 Status
HTTP Status | Desc |
---|---|
200 | OK (조회 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
메시지 발송 결과 조회
메시지 발송 결과를 조회합니다.
요청 URL
GET https://sens.apigw.fin-ntruss.com/friendtalk/v2/services/{serviceId}/messages/{messageId}
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
messageId | Mandatory | String | 메시지 아이디 | 메시지 발송시 반환되는 메시지 식별자 |
Headers
요청 Body
없음
응답 Body
{
"messageId":"string",
"requestId":"string",
"requestTime":"string",
"completeTime":"string",
"plusFriendId":"string",
"countryCode":"string",
"to":"string",
"content":"string",
"requestStatusCode":"string",
"requestStatusName":"string",
"requestStatusDesc":"string",
"messageStatusCode":"string",
"messageStatusName":"string",
"messageStatusDesc":"string",
"isWide":"boolean",
"isAd":"boolean",
"imageId":"string",
"imageName":"string",
"imageUrl":"string",
"imageLink":"string",
"useSmsFailover":"boolean",
"failover": {
"smsServiceId":"string",
"requestId":"string",
"requestStatusCode":"string",
"requestStatusName":"string",
"requestStatusDesc":"string",
"messageId":"string",
"messageStatus":"string",
"messageStatusCode":"string",
"messageStatusName":"string",
"messageStatusDesc":"string"
}
}
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
messageId | Mandatory | String | 메시지 아이디 | |
requestId | Mandatory | String | 발송 요청 아이디 | |
requestTime | Mandatory | DateTime | 발송 요청 시간 | yyyy-MM-dd'T'HH:mm:ss.SSS |
completeTime | Optional | DateTime | 발송 리포트(처리 완료) 시간 | yyyy-MM-dd'T'HH:mm:ss |
plusFriendId | Mandatory | String | 카카오톡 채널명 ((구)플러스친구 아이디) | |
templateCode | Mandatory | String | 템플릿 코드 | |
countryCode | Optional | String | 수신자 국가번호 | default: 82 |
to | Mandatory | String | 수신자번호 | |
content | Mandatory | String | 친구톡 메시지 내용 | |
requestStatusCode | Mandatory | String | 발송요청 상태 코드 | A000 - 성공 그외 코드 - 실패(Desc 항목에 실패 사유가 명시) |
requestStatusName | Mandatory | String | 발송요청 상태명 | success - 성공 fail - 실패 |
requestStatusDesc | Mandatory | String | 발송요청 상태 내용 | |
messageStatusCode | Mandatory | String | 발송결과 상태 코드 | 0000 - 성공 그외 코드 - 실패(Desc 항목에 실패 사유가 명시) |
messageStatusName | Mandatory | String | 발송결과 상태명 | success - 성공 processing - 처리중 * 발송요청 성공 후, 메시지 발송서버에서 처리중인 상태 * messageCode, messageDesc가 조회되지 않음 fail - 실패 |
messageStatusDesc | Mandatory | String | 발송결과 상태 내용 | |
isWide | Mandatory | Boolean | 와이드 여부 | |
isAd | Mandatory | Boolean | 광고메시지 여부 | |
imageId | Optional | String | 이미지 아이디 | |
imageName | Optional | String | 이미지 이름 | |
imageUrl | Optional | String | 이미지 URL | |
imageLink | Optional | String | 이미지 링크 | |
useSmsFailover | Mandatory | Boolean | SMS Failover 사용 여부 | |
failover | Optional | Object | SMS Failover 사용 여부 | |
failover.smsServiceId | Optional | String | SMS Failover 서비스 아이디 | |
failover.requestId | Optional | String | SMS Failover 발송 요청 아이디 | |
failover.requestStatusCode | Optional | String | SMS Failover 발송 요청 상태 코드 | 오류 코드 표 참고 |
failover.requestStatusName | Optional | String | SMS Failover 발송 요청 상태명 | success - 성공 fail - 실패 |
failover.requestStatusDesc | Optional | String | SMS Failover 발송 요청 상태 내용 | |
failover.messageId | Optional | String | SMS Failover 발송 메시지 아이디 | |
failover.messageStatus | Optional | String | SMS Failover 발송 처리 상태 | READY: 대기 PROCESSING: 처리 중 COMPLETED: 처리 완료 |
failover.messageStatusCode | Optional | String | SMS Failover 발송 단말 수신 상태 결과 코드 | 오류 코드 표 참고 |
failover.messageStatusName | Optional | String | SMS Failover 발송 단말 수신 결과명 | |
failover.messageStatusDesc | Optional | String | SMS Failover 발송 단말 수신 내용 |
Failover 요청 상태 코드
requestStatusCode | Desc |
---|---|
0 | 성공 |
E4000 | failover 설정이 유효하지 않음 |
E4001 | failover 설정 정보가 누락됨 |
E4002 | failover SMS 서비스가 설정되지 않음 |
E4003 | failover SMS type(SMS, LMS)이 설정되지 않음 |
E4004 | failover SMS 발신번호가 설정되지 않음 |
E4005 | failover SMS 제목이 설정되지 않음 |
E4006 | failover SMS 내용이 설정되지 않음 |
E4007 | failover SMS 수신번호가 설정되지 않음 |
E4008 | failover SMS 서비스가 사용 가능한 상태가 아님 |
E4009 | failover SMS 발신번호가 인증되지 않음 |
E4010 | failover SMS 080무료수신거부 서비스가 사용 가능한 상태가 아님 |
E4999 | failover 설정 파싱 오류 (고객 지원으로 문의 필요) |
E5000 | 내부 오류 (고객 지원으로 문의 필요) |
응답 Status
HTTP Status | Desc |
---|---|
200 | OK (조회 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
예약 메시지
예약 메시지 상태 조회
메시지 발송 예약 상태를 조회합니다.
GET https://sens.apigw.fin-ntruss.com/friendtalk/v2/services/{serviceId}/reservations/{reserveId}/reserve-status
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
reserveId | Mandatory | String | 예약 메시지 아이디 | 예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId) |
Headers
요청 Body
없음
응답 Body
{
"reserveId": "string",
"reserveTimeZone": "string",
"reserveTime": "string",
"reserveStatus": "string"
}
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
reserveId | Mandatory | String | 예약 메시지 아이디 | 예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId) |
reserveTime | Mandatory | String | 예약 일시 | 메시지 발송 예약 일시 (yyyy-MM-dd HH:mm) |
reserveTimeZone | Mandatory | String | 예약 일시 타임존 | 예약 일시 타임존 (기본: Asia/Seoul) * 지원 타임존 목록 * TZ database name 값 사용 |
reserveStatus | Mandatory | String | 예약 상태 | READY - 발송 대기 PROCESSING - 발송 요청중 CANCELED - 발송 취소 FAIL - 발송 요청 실패 DONE - 발송 요청 성공 STALE - 발송 요청 실패 (시간 초과) |
응답 Status
HTTP Status | Desc |
---|---|
200 | OK (조회 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
예약 메시지 취소
메시지 발송 예약을 취소합니다.
DELETE https://sens.apigw.fin-ntruss.com/friendtalk/v2/services/{serviceId}/reservations/{reserveId}
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
reserveId | Mandatory | String | 예약 메시지 아이디 | 예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId) |
Headers
요청 Body
없음
응답 Body
없음
응답 Status
HTTP Status | Desc |
---|---|
204 | No Content (삭제 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
카카오톡 채널
채널 조회
카카오톡 채널을 조회합니다.
GET https://sens.apigw.fin-ntruss.com/friendtalk/v2/services/{serviceId}/channels
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
Parameters
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
pageSize | Optional | Integer | 페이지 사이즈 | default: 100 (1 ~ 100 사이의 숫자만 입력 가능) |
pageIndex | Optional | Integer | 페이지 인덱스 | default: 0 |
Headers
요청 Body
없음
응답 Body
[
{
"createTime": "string",
"updateTime": "string",
"serviceId": "string",
"channelId": "string",
"channelName": "string",
"channelStatus": "string",
"useSmsFailover": "boolean",
"failoverServiceId": "string",
"failoverTelNo": "string",
"isBlock": "boolean",
"isDormant": "boolean"
}
]
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
createTime | Mandatory | String | 생성 시간 | format: LocalDateTime |
updateTime | Optional | String | 수정 시간 | format: LocalDateTime |
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
channelId | Mandatory | String | 카카오톡 채널 아이디 | |
channelName | Mandatory | String | 카카오톡 채널 이름 | |
channelStatus | Mandatory | String | 카카오톡 채널 상태 | - 정상: ACTIVE - 삭제: DELETED - 영구 삭제 중: DELETING_PERMANENTLY - 영구 삭제: PERMANENTLY_DELETED - 차단: BLOCKED - 삭제 지연 중: PENDING_DELETE |
useSmsFailover | Mandatory | Boolean | SMS 대체 발송 사용 여부 | |
failoverServiceId | Optional | String | Failover SMS 서비스ID | |
failoverTelNo | Optional | String | Failover 발신번호 | |
isBlock | Mandatory | Boolean | 채널 차단 여부 | |
isDormant | Mandatory | Boolean | 채널 휴면 전환 여부 |
응답 Status
HTTP Status | Desc |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |
이미지
이미지 업로드
친구톡 발송에 사용할 이미지를 업로드합니다.
이미지는 1년간 보관하며, 그 이후에는 자동 삭제되어 사용하실 수 없습니다.
요청 URL
POST https://sens.apigw.fin-ntruss.com/friendtalk/v2/services/{serviceId}/images
Content-Type: multipart/form-data; boundary=a29b1180-70f5-42f7-afbe-0d68a15f2370
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
Headers
요청 Parameter
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
plusFriendId | Mandatory | String | 카카오톡 채널명 ((구)플러스친구 아이디) | |
imageFile | Mandatory | File | 이미지 파일 | - 공통 * jpg, png 만 가능 * 500KB 이하 - 일반 * 권장 사이즈 : 720px x 720px * 가로 500px 이상, 가로 * 세로 비율 2:1 이상 3:4 이하 만 업로드 가능 - 와이드 * 제한 사이즈 : 800px x 600px * 가로 * 세로 비율 4:3 만 업로드 가능 |
isWide | Optional | Boolean | 와이드 이미지 여부 | 와이드 이미지 업로드시, 와이드 친구톡 메시지로 발송됨 * defealt: false |
응답 Body
{
"imageId":"string",
"imageName":"string",
"imageUrl":"string",
"isWide":"boolean",
"createTime":"string"
}
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
imageId | Mandatory | Strng | 이미지 아이디 | |
imageName | Mandatory | String | 이미지 파일 이름 | |
imageUrl | Mandatory | String | 이미지 URL | |
isWide | Mandatory | Boolean | 와이드 여부 | |
createTime | Mandatory | DateTime | 이미지 업로드 시간 |
응답 Status
HTTP Status | Desc |
---|---|
200 | Ok (업로드 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
이미지 목록 조회
업로드된 이미지 목록을 조회합니다.
요청 URL
GET https://sens.apigw.fin-ntruss.com/friendtalk/v2/services/{serviceId}/images
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
Headers
Parameters
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
pageIndex | Optional | Integer | 페이지 인덱스 | default: 0 |
pageSize | Optional | Integer | 페이지 사이즈 | default: 20 (1 ~ 100 사이의 숫자만 입력 가능) |
요청 Body
없음
응답 Body
{
"items": [
{
"imageId": "string",
"imageName": "string",
"imageUrl": "string",
"isWide": "boolean",
"createTime": "string"
}
],
"pageIndex": "integer",
"pageSize": "integer",
"itemCount": "integer",
"totalCount": "integer"
}
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
items | Mandatory | Array of Object | 이미지 데이터 목록 | 이미지 데이터 참조 |
pageIndex | Mandatory | Integer | 페이지 인덱스 | |
pageSize | Mandatory | Integer | 페이지 사이즈 | |
itemCount | Mandatory | Integer | 조회된 아이템 개수 | |
totalCount | Mandatory | Integer | 전체 개수 |
응답 Status
HTTP Status | Desc |
---|---|
200 | Ok (조회 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
이미지 단건 조회
업로드된 이미지를 단건 조회합니다.
요청 URL
GET https://sens.apigw.fin-ntruss.com/friendtalk/v2/services/{serviceId}/images/{imageId}
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
imageId | Mandatory | String | 이미지 아이디 | 업로드된 이미지 아이디 |
Headers
요청 Body
없음
응답 Body
{
"imageId":"string",
"imageName":"string",
"imageUrl":"string",
"isWide":"boolean",
"createTime":"string"
}
이미지 데이터
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
imageId | Mandatory | Strng | 이미지 아이디 | |
imageName | Mandatory | String | 이미지 파일 이름 | |
imageUrl | Mandatory | String | 이미지 URL | |
isWide | Mandatory | Boolean | 와이드 여부 | |
createTime | Mandatory | DateTime | 이미지 업로드 시간 |
응답 Status
HTTP Status | Desc |
---|---|
200 | Ok (조회 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
이미지 삭제
업로드된 이미지를 삭제합니다.
요청 URL
DELETE https://sens.apigw.fin-ntruss.com/friendtalk/v2/services/{serviceId}/images/{imageId}
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
imageId | Mandatory | String | 이미지 아이디 | 업로드된 이미지 아이디 |
Headers
요청 Body
없음
응답 Body
없음
응답 Status
HTTP Status | Desc |
---|---|
204 | No Content (삭제 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
오류 코드
비즈메시지 수신 결과 코드
Status | Error text | Desc |
---|---|---|
0000 | - | 정상 발송 |
1001 | NoJsonBody | Request Body가 Json형식이 아님 |
1002 | InvalidHubPartnerKey | 파트너 키가 유효하지 않음 |
1003 | InvalidSenderKey | 발신 프로필 키가 유효하지 않음 |
1004 | NoValueJsonElement | Request BODY(Json)에서 name을 찾을 수 없음 |
1005 | SenderNotFound | 발신프로필을 찾을 수 없음 |
1006 | DeletedSender | 삭제된 발신 프로필 |
1007 | StoppedSender | 차단 상태의 발신 프로필 |
1011 | ContractNotFound | 계약 정보를 찾을 수 없음 |
1012 | InvalidUserKeyException | 잘못된 형식의 유저 키 요청 |
1013 | InvalidAppLink | 유효하지 않은 app연결 |
1014 | InvalidBizNum | 유효하지 않은 사업자번호 |
1015 | TalkUserIdNotFonud | 유효하지 않은 app user id 요청 |
1016 | BizNumNotEqual | 사업자등록번호 불일치 |
1020 | InvalidReceiveUserException | 올바른 유저 식별자 값이 하나도 없는 경우 |
1021 | BlockedProfile | 차단 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인) |
1022 | DeactivatedProfile | 닫힘 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인) |
1023 | DeletedProfile | 삭제된 카카오톡 채널 (카카오톡 채널 운영툴에서 확인) |
1024 | DeletingProfile | 삭제대기 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인) |
1025 | SpammedProfile | 메시지차단 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인) |
1030 | InvalidParameterException | 잘못된 파라메터 요청 |
1033 | - | 템플릿 타입과 메시지타입 불일치 |
2003 | FailedToSendMessageByNoFriendshipException | 메시지 전송 실패 (테스트 서버에서 카카오톡 채널을 추가하지 않은 경우) |
2004 | FailedToMatchTemplateException | 템플릿 일치 확인 시 오류 발생 (카카오 내부 오류) |
2006 | FailedToMatchSerialNumberPrefixPattern | 시리얼넘버 형식 불일치 |
3000 | UnexceptedExcetpion | 예기치 않은 오류 발생 |
3005 | AckTimeoutException | 메시지를 발송 했으나, 수신확인 안됨 (성공 불 확실) |
3006 | FailedToSendMessageException | 카카오 내부 시스템 오류로 메시지 전송 실패 |
3008 | InvalidPhoneNumberException | 전화번호 오류 |
3010 | JsonParsseExcetpion | Json 파싱 오류 |
3011 | MessageNotFoundException | 메시지가 존재하지 않음 |
3012 | SerialNumberDuplicatedException | 메시지 일련번호가 중복됨 (메시지 일련 번호는 고유의 값이 부여되어야 함) |
3013 | MessageEmptyException | 빈 메시지 |
3014 | MessageLengthOverLimitException | 메시지 길이 제한 오류 (텍스트 타입 1000자 초과, 이미지 타입 400자 초과) |
3015 | TemplateNotFoundException | 템플릿을 찾을 수 없음 |
3016 | NoMatchedTemplateException | 메시지 내용이 템플릿과 일치하지 않음 |
3018 | NoSendAvailableException | 메시지를 전송할 수 없음 |
3020 | SeenInfoNotFoundException | 메시지 확인 정보를 찾을 수 없음 |
3022 | NoSendAvailableTimeException | 메시지 발송 가능한 시간이 아님 (친구 톡/마케팅 메시지는 08시~ 20시 50분까지 발송 가능) |
3024 | MessageInvaildImageException | 메시지에 포함된 이미지를 전송할 수 없음 |
3025 | ExceedMaxVariableLengthException | 변수 글자수 제한 초과 |
3026 | Button chat_extra(event)-InvalidExtra(EventName)Exception '([A-Za-z0-9_]{1,50})' | 상담/봇 전환 버튼 extra, event 글자수 제한 초과 |
3027 | NoMatchedTemplateButtonException | 버튼 내용이 템플릿과 일치 하지 않음 |
3028 | NoMatchedTemplateTitleException | 메시지 강조 표기 타이틀이 템플릿과 일치하지 않음 |
3029 | ExceedMaxTitleLengthException | 메시지 강조 표기 타이틀 길이 제한 초과 (50자) |
3031 | - | 텍스트 유형 불일치 |
4000 | ResponseHistoryNotFoundException | 메시지 전송 결과를 찾을 수 없음 |
4001 | UnKnownMessageStatusError | 알수 없는 메시지 상태 |
7011 | - | 시리얼 넘버 패턴 에러 |
7014 | - | 메시지 유효 시간 초과 에러 |
8512 | - | 수신자 타입 찾을 수 없음 |
8514 | - | request_id 찾을 수 없음 |
8520 | - | 지원하지 않는상품 타입 오류 |
8521 | - | 지원하지 않는 메시지 타입 오류 |
8522 | - | 지원하지 않는 텍스트 유형 오류 |
8523 | - | 지원하지 않는 response method 오류 |
8530 | - | 수신자 목록 사이즈 오류 |
8999 | - | 내부 서버 오류 |
9998 | 현재 서비스를 제공하고 있지 않습니다. | 시스템에 문제가 발생하여 담당자가 확인하고 있는 경우 |
9999 | 시스템에 알수 없는 문제 발생, 담당자 확인중 | 시스템에 문제가 발생하여. 담당자 확인중 |
B000 | Prepare to relay failed | 중계사 발송을 위한 사전 작업 실패 |
B001 | Request to relay failed | 중계사 발송 실패 |
B002 | Filtering for request to relay failed | 잘못된 요청으로 인해 필터링됨 |
B003 | Invalid phone number format | 올바르지 않은 발신번호 포멧 |
B004 | Quota Exceed | 쿼터 초과 |
B005 | Message processing timeout exceed | 메시지 요청 시간과 처리 시간의 차이가 허용 범위를 벗어남 |
B400 | Invalid Request | 메시지 형식 오류 |
B999 | Unexpected server error | 예기치 못한 에러 |
이 문서가 도움이 되었습니까?