MENU
      친구톡 API

        친구톡 API


        기사 요약

        기본 정보

        API URL

        https://sens.apigw.ntruss.com/friendtalk/v2
        HTTP

        SENS 친구톡 API Swagger 바로가기

        API Header

        항목Mandatory설명
        Content-TypeMandatory요청 Body Content Type을 application/json으로 지정 (POST)
        x-ncp-apigw-timestampMandatory1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타낸 것
        API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주
        x-ncp-iam-access-keyMandatory포탈 또는 Sub Account에서 발급받은 Access Key ID
        x-ncp-apigw-signature-v2Mandatory위 예제의 Body를 Access Key Id와 맵핑되는 SecretKey로 암호화한 서명
        HMAC 암호화 알고리즘은 HmacSHA256 사용

        NAVER CLOUD PLATFORM 인증키 및 Signature 생성 가이드 바로가기


        메시지

        메시지 발송

        메시지를 발송합니다.

        요청 URL

        POST https://sens.apigw.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}
        HTTP

        Path Variables

        항목MandatoryType설명비고
        serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디

        Headers

        API Header 바로가기

        요청 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"
        }
        JSON
        항목MandatoryType설명비고
        plusFriendIdMandatoryString카카오톡 채널명 ((구)플러스친구 아이디)
        messagesMandatoryObject메시지 정보아래 항목들 참조 (messages.XXX)
        최대 100개
        messages.isAdOptionalBoolean광고 메시지 여부default: true
        광고 메시지로 발송하시는 경우(isAd: true),
        SMS Failover 동작 시 광고 메시지 전송 표기 의무를 준수해야합니다.
        messages.countryCodeOptionalString수신자 국가번호default: 82
        messages.toMandatoryString수신자번호
        messages.contentMandatoryString친구톡 메시지 내용
        messages.buttonsOptionalArray of Object친구톡 메시지 버튼버튼 정보 참조
        messages.buttons.typeMandatoryString버튼 Type아래 템플릿 버튼 정보 참조
        messages.buttons.nameMandatoryString버튼명아래 템플릿 버튼 정보 참조
        messages.imageOptionalObject이미지 정보이미지 업로드 참조
        messages.image.imageIdMandatoryString업로드된 이미지 아이디
        messages.image.imageLinkMandatoryString이미지 링크
        messages.useSmsFailoverOptionalBooleanSMS Failover 사용 여부Failover가 설정된 카카오톡 채널에서만 사용 가능
        기본: 카카오톡 채널의 Failover 설정 여부를 따름
        messages.failoverConfigOptionalObjectFailover 설정아래 항목들 참조
        messages.failoverConfig.typeOptionalStringFailover SMS 메시지 TypeSMS or LMS
        기본: content 길이에 따라 자동 적용 (90 bytes 이하 SMS, 초과 LMS)
        messages.failoverConfig.fromOptionalStringFailover SMS 발신번호기본: Failover 설정 시 선택한 발신번호
        승인되지 않은 발신번호 사용시, Failover 동작 안함
        messages.failoverConfig.subjectOptionalStringFailover SMS 제목LMS type으로 동작할 때 사용
        기본: 카카오톡 채널명
        messages.failoverConfig.contentOptionalStringFailover SMS 내용기본: 친구톡 메시지 내용 (버튼 제외)
        reserveTimeOptionalString예약 일시메시지 발송 예약 일시 (yyyy-MM-dd HH:mm)
        reserveTimeZoneOptionalString예약 일시 타임존예약 일시 타임존 (기본: Asia/Seoul)
        * 지원 타임존 목록
        * TZ database name 값 사용
        • 요청 Body의 Mandatory 필드를 사용하시는 경우, 공백은 허용되지않습니다. (추가하는 경우에만 해당)
        • SMS Failover는 비즈메시지 수신 결과 코드 기준, 성공이 아닌 경우 동작하며, prefix로 B가 붙은 코드들에 대해서는 failover 기능을 통한 SMS 대체 발송이 이루어지지 않습니다.
        StatusError textDesc
        0000-정상 발송
        3022NoSendAvailableTimeException메시지 발송 가능한 시간이 아님 (친구 톡/마케팅 메시지는 08시~ 20시 50분까지 발송 가능)
        Bxxx하단 비즈메시지 수신 결과 코드 참고하단 비즈메시지 수신 결과 코드 참고
        • 광고 메시지 발송 시 SMS Failover에 설정된 SMS 서비스의 080수신거부 서비스를 사용합니다.
          • 설정된 SMS 서비스에 080수신거부 서비스가 사용 가능한 상태가 아니라면, SMS Failover는 실패합니다.
          • failoverConfig.content를 별도로 지정하지 않고 사용하시는 경우, SMS Failover시 자동으로 광고 표기 문구를 삽입합니다.
            [광고]{메시지내용}
            무료수신거부번호08012345678
            Plain text
          • failoverConfig.content를 별도로 직접 지정하시는 경우, 광고 표기 문구를 삽입하지 않습니다. 광고 메시지 발송 시 직접 추가해 주십시오.
          • 광고 표기 의무를 준수하지 않은 SMS 메시지 발송 시, 추후 소명이 필요할 수 있습니다.
        • 와이드 이미지 발송 시, 텍스트 + 링크 버튼(1개) + 이미지 발송이 가능합니다.
          • 2개 이상의 버튼 추가시, 메시지 발송에 실패합니다. (잘못된 파라미터 요청)
          • 텍스트 문구는 76자로 제한됩니다.

        버튼 정보

        TypeNameMandatory 항목
        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"
                }
            ]
        }
        JSON
        항목MandatoryType설명비고
        requestIdMandatoryString발송 요청 아이디
        requestTimeMandatoryDateTime발송 요청 시간yyyy-MM-dd'T'HH:mm:ss.SSS
        statusCodeMandatoryString요청 상태 코드202 - 성공
        그외 - 실패
        * HTTP Status 규격을 따름
        statusNameMandatoryString요청 상태명success - 성공
        processing - 처리중
        reserved - 예약중
        fail - 실패
        messages.messageIdMandatoryString메시지 아이디
        messages.countryCodeOptionalString수신자 국가번호default: 82
        messages.toMandatoryString수신자번호
        messages.contentMandatoryString친구톡 메시지 내용
        messages.requestStatusCodeMandatoryString발송요청 상태 코드A000 - 성공
        그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
        messages.requestStatusNameMandatoryString발송요청 상태명success - 성공
        fail - 실패
        messages.requestStatusDescMandatoryString발송요청 상태 내용
        messages.useSmsFailoverMandatoryBooleanSMS Failover 사용 여부

        응답 Status

        HTTP StatusDesc
        202Accepted (발송 요청 완료)
        400Bad Request
        401Unauthorized
        403Forbidden
        404Not Found
        500Internal Server Error

        메시지 발송 요청 조회

        메시지 발송 요청을 조회합니다.

        요청 URL

        GET https://sens.apigw.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}
        HTTP

        Path Variables

        항목MandatoryType설명비고
        serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디

        Parameters

        항목MandatoryType설명비고
        requestIdMandatoryString요청 아이디발송 요청 아이디
        plusFriendIdMandatoryString카카오 채널등록된 채널 명
        requestStartTimeMandatoryString조회 시간 시작 시각yyyy-MM-dd'T'HH:mm:ss
        requestEndTimeMandatoryString조회 시간 종료 시각yyyy-MM-dd'T'HH:mm:ss
        completeStartTimeMandatoryString발송 완료 시작 시간yyyy-MM-dd'T'HH:mm:ss
        completeEndTimeMandatoryString발송 완료 종료 시간yyyy-MM-dd'T'HH:mm:ss
        messageIdOptionalString메시지 아이디
        requestStatusNameOptionalString요청 상태success, fail
        messageStatusNameOptionalString요청 상태success, processing, fail
        toOptionalString메세지 수신 번호붙임표 (-)를 제외한 번호
        pageIndexOptionalInteger페이지 번호default: 0
        pageSizeOptionalInteger페이지 크기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

        API Header 바로가기

        요청 Body

        없음
        JSON

        응답 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"
        }
        JSON
        항목MandatoryType설명비고
        requestIdOptionalString발송 요청 아이디requestId로 조회하는 경우에만 노출됨
        statusCodeMandatoryString요청 상태 코드202 - 성공
        그외 - 실패
        * HTTP Status 규격을 따름
        statusNameMandatoryString요청 상태명success - 성공
        processing - 발송중
        reserved - 예약중
        fail - 실패
        messages.requestTimeMandatoryDateTime발송 요청 시간yyyy-MM-dd'T'HH:mm:ss.SSS
        messages.messageIdMandatoryString메시지 아이디
        messages.countryCodeOptionalString수신자 국가번호default: 82
        messages.toMandatoryString수신자번호
        messages.contentMandatoryString친구톡 메시지 내용
        messages.plusFriendIdMandatoryString카카오톡 채널명 ((구)플러스친구 아이디)
        messages.completeTimeOptionalDateTime발송 리포트(처리 완료) 시간yyyy-MM-dd'T'HH:mm:ss
        messages.requestStatusCodeMandatoryString발송요청 상태 코드A000 - 성공
        그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
        messages.requestStatusNameMandatoryString발송요청 상태명success - 성공
        fail - 실패
        messages.requestStatusDescMandatoryString발송요청 상태 내용
        messages.messageStatusCodeMandatoryString발송결과 상태 코드0000 - 성공
        그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
        messages.messageStatusNameMandatoryString발송결과 상태명success - 성공
        processing - 처리중
            * 발송요청 성공 후, 메시지 발송서버에서 처리중인 상태
            * messageCode, messageDesc가 조회되지 않음
        fail - 실패
        messages.messageStatusDescMandatoryString발송결과 상태 내용
        messages.isWideMandatoryBoolean와이드 여부
        messages.isAdMandatoryBoolean광고메시지 여부
        messages.useSmsFailoverMandatoryBooleanSMS Failover 사용 여부
        messages.failoverOptionalObjectSMS Failover
        messages.failover.smsServiceIdOptionalStringSMS Failover 서비스 아이디
        messages.failover.requestIdOptionalStringSMS Failover 발송 요청 아이디
        messages.failover.messageIdOptionalStringSMS Failover 발송 메시지 아이디
        messages.failover.requestStatusCodeOptionalStringSMS Failover 발송 요청 상태 코드오류 코드 표 참고
        messages.failover.requestStatusNameOptionalStringSMS Failover 발송 요청 상태명success - 성공
        fail - 실패
        messages.failover.requestStatusDescOptionalStringSMS Failover 발송 요청 상태 내용
        messages.failover.messageStatusOptionalStringSMS Failover 발송 처리 상태READY: 대기
        PROCESSING: 처리 중
        COMPLETED: 처리 완료
        messages.failover.messageStatusCodeOptionalStringSMS Failover 발송 단말 수신 상태 결과 코드오류 코드 표 참고
        messages.failover.messageStatusNameOptionalStringSMS Failover 발송 단말 수신 결과명
        messages.failover.messageStatusDescOptionalStringSMS Failover 발송 단말 수신 내용
        pageSizeMandatoryInteger페이지 사이즈
        pageIndexMandatoryInteger페이지 인덱스 (0부터 시작)
        itemCountMandatoryInteger조회한 페이지 내의 메시지 수
        hasMoreMandatoryBoolean다음 페이지 존재 여부

        응답 Status

        HTTP StatusDesc
        200OK (조회 완료)
        400Bad Request
        401Unauthorized
        403Forbidden
        404Not Found
        500Internal Server Error

        메시지 발송 결과 조회

        메시지 발송 결과를 조회합니다.

        요청 URL

        GET https://sens.apigw.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}
        HTTP

        Path Variables

        항목MandatoryType설명비고
        serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디
        messageIdMandatoryString메시지 아이디메시지 발송시 반환되는 메시지 식별자

        Headers

        API Header 바로가기

        요청 Body

        없음
        JSON

        응답 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"
            }
        }
        JSON
        항목MandatoryType설명비고
        messageIdMandatoryString메시지 아이디
        requestIdMandatoryString발송 요청 아이디
        requestTimeMandatoryDateTime발송 요청 시간yyyy-MM-dd'T'HH:mm:ss.SSS
        completeTimeOptionalDateTime발송 리포트(처리 완료) 시간yyyy-MM-dd'T'HH:mm:ss
        plusFriendIdMandatoryString카카오톡 채널명 ((구)플러스친구 아이디)
        templateCodeMandatoryString템플릿 코드
        countryCodeOptionalString수신자 국가번호default: 82
        toMandatoryString수신자번호
        contentMandatoryString친구톡 메시지 내용
        requestStatusCodeMandatoryString발송요청 상태 코드A000 - 성공
        그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
        requestStatusNameMandatoryString발송요청 상태명success - 성공
        fail - 실패
        requestStatusDescMandatoryString발송요청 상태 내용
        messageStatusCodeMandatoryString발송결과 상태 코드0000 - 성공
        그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
        messageStatusNameMandatoryString발송결과 상태명success - 성공
        processing - 처리중
            * 발송요청 성공 후, 메시지 발송서버에서 처리중인 상태
            * messageCode, messageDesc가 조회되지 않음
        fail - 실패
        messageStatusDescMandatoryString발송결과 상태 내용
        isWideMandatoryBoolean와이드 여부
        isAdMandatoryBoolean광고메시지 여부
        imageIdOptionalString이미지 아이디
        imageNameOptionalString이미지 이름
        imageUrlOptionalString이미지 URL
        imageLinkOptionalString이미지 링크
        useSmsFailoverMandatoryBooleanSMS Failover 사용 여부
        failoverOptionalObjectSMS Failover 사용 여부
        failover.smsServiceIdOptionalStringSMS Failover 서비스 아이디
        failover.requestIdOptionalStringSMS Failover 발송 요청 아이디
        failover.requestStatusCodeOptionalStringSMS Failover 발송 요청 상태 코드오류 코드 표 참고
        failover.requestStatusNameOptionalStringSMS Failover 발송 요청 상태명success - 성공
        fail - 실패
        failover.requestStatusDescOptionalStringSMS Failover 발송 요청 상태 내용
        failover.messageIdOptionalStringSMS Failover 발송 메시지 아이디
        failover.messageStatusOptionalStringSMS Failover 발송 처리 상태READY: 대기
        PROCESSING: 처리 중
        COMPLETED: 처리 완료
        failover.messageStatusCodeOptionalStringSMS Failover 발송 단말 수신 상태 결과 코드오류 코드 표 참고
        failover.messageStatusNameOptionalStringSMS Failover 발송 단말 수신 결과명
        failover.messageStatusDescOptionalStringSMS Failover 발송 단말 수신 내용

        Failover 요청 상태 코드

        requestStatusCodeDesc
        0성공
        E4000failover 설정이 유효하지 않음
        E4001failover 설정 정보가 누락됨
        E4002failover SMS 서비스가 설정되지 않음
        E4003failover SMS type(SMS, LMS)이 설정되지 않음
        E4004failover SMS 발신번호가 설정되지 않음
        E4005failover SMS 제목이 설정되지 않음
        E4006failover SMS 내용이 설정되지 않음
        E4007failover SMS 수신번호가 설정되지 않음
        E4008failover SMS 서비스가 사용 가능한 상태가 아님
        E4009failover SMS 발신번호가 인증되지 않음
        E4010failover SMS 080무료수신거부 서비스가 사용 가능한 상태가 아님
        E4999failover 설정 파싱 오류 (고객 지원으로 문의 필요)
        E5000내부 오류 (고객 지원으로 문의 필요)

        응답 Status

        HTTP StatusDesc
        200OK (조회 완료)
        400Bad Request
        401Unauthorized
        403Forbidden
        404Not Found
        500Internal Server Error

        예약 메시지

        예약 메시지 상태 조회

        메시지 발송 예약 상태를 조회합니다.

        GET https://sens.apigw.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}
        HTTP

        Path Variables

        항목MandatoryType설명비고
        serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디
        reserveIdMandatoryString예약 메시지 아이디예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId)

        Headers

        API Header 바로가기

        요청 Body

        없음
        JSON

        응답 Body

        {
          "reserveId": "string",
          "reserveTimeZone": "string",
          "reserveTime": "string",
          "reserveStatus": "string"
        }
        JSON
        항목MandatoryType설명비고
        reserveIdMandatoryString예약 메시지 아이디예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId)
        reserveTimeMandatoryString예약 일시메시지 발송 예약 일시 (yyyy-MM-dd HH:mm)
        reserveTimeZoneMandatoryString예약 일시 타임존예약 일시 타임존 (기본: Asia/Seoul)
        * 지원 타임존 목록
        * TZ database name 값 사용
        reserveStatusMandatoryString예약 상태READY - 발송 대기
        PROCESSING - 발송 요청중
        CANCELED - 발송 취소
        FAIL - 발송 요청 실패
        DONE - 발송 요청 성공
        STALE - 발송 요청 실패 (시간 초과)

        응답 Status

        HTTP StatusDesc
        200OK (조회 완료)
        400Bad Request
        401Unauthorized
        403Forbidden
        404Not Found
        500Internal Server Error

        예약 메시지 취소

        메시지 발송 예약을 취소합니다.

        DELETE https://sens.apigw.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}
        HTTP

        Path Variables

        항목MandatoryType설명비고
        serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디
        reserveIdMandatoryString예약 메시지 아이디예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId)

        Headers

        API Header 바로가기

        요청 Body

        없음
        JSON

        응답 Body

        없음
        JSON

        응답 Status

        HTTP StatusDesc
        204No Content (삭제 완료)
        400Bad Request
        401Unauthorized
        403Forbidden
        404Not Found
        500Internal Server Error

        카카오톡 채널

        채널 조회

        카카오톡 채널을 조회합니다.

        GET https://sens.apigw.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}
        HTTP

        Path Variables

        항목MandatoryType설명비고
        serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디

        Parameters

        항목MandatoryType설명비고
        pageSizeOptionalInteger페이지 사이즈default: 100 (1 ~ 100 사이의 숫자만 입력 가능)
        pageIndexOptionalInteger페이지 인덱스default: 0

        Headers

        API Header 바로가기

        요청 Body

        없음
        JSON

        응답 Body

        [
            {
                "createTime": "string",
                "updateTime": "string",
                "serviceId": "string",
                "channelId": "string",
                "channelName": "string",
                "channelStatus": "string",
                "useSmsFailover": "boolean"
            }
        ]
        JSON
        항목MandatoryType설명비고
        createTimeMandatoryString생성 시간format: LocalDateTime
        updateTimeOptionalString수정 시간format: LocalDateTime
        serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디
        channelIdMandatoryString카카오톡 채널 아이디
        channelNameMandatoryString카카오톡 채널 이름
        channelStatusMandatoryString카카오톡 채널 상태- 정상: ACTIVE
        - 삭제: DELETED
        - 영구 삭제 중: DELETING_PERMANENTLY
        - 영구 삭제: PERMANENTLY_DELETED
        - 차단: BLOCKED
        - 삭제 지연 중: PENDING_DELETE
        useSmsFailoverMandatoryBooleanSMS 대체 발송 사용 여부

        응답 Status

        HTTP StatusDesc
        200OK
        400Bad Request
        401Unauthorized
        403Forbidden
        404Not Found
        429Too Many Requests
        500Internal Server Error

        이미지

        이미지 업로드

        친구톡 발송에 사용할 이미지를 업로드합니다.
        이미지는 1년간 보관하며, 그 이후에는 자동 삭제되어 사용하실 수 없습니다.

        요청 URL

        POST https://sens.apigw.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}
        HTTP

        Path Variables

        항목MandatoryType설명비고
        serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디

        Headers

        API Header 바로가기

        요청 Parameter

        항목MandatoryType설명비고
        plusFriendIdMandatoryString카카오톡 채널명 ((구)플러스친구 아이디)
        imageFileMandatoryFile이미지 파일- 공통
        * jpg, png 만 가능
        * 500KB 이하
        - 일반
        * 권장 사이즈 : 720px x 720px
        * 가로 500px 이상, 가로 * 세로 비율 2:1 이상 3:4 이하 만 업로드 가능
        - 와이드
        * 제한 사이즈 : 800px x 600px
        * 가로 * 세로 비율 4:3 만 업로드 가능
        isWideOptionalBoolean와이드 이미지 여부와이드 이미지 업로드시, 와이드 친구톡 메시지로 발송됨
        * defealt: false

        응답 Body

        {
            "imageId":"string",
            "imageName":"string",
            "imageUrl":"string",
            "isWide":"boolean",
            "createTime":"string"
        }
        JSON
        항목MandatoryType설명비고
        imageIdMandatoryStrng이미지 아이디
        imageNameMandatoryString이미지 파일 이름
        imageUrlMandatoryString이미지 URL
        isWideMandatoryBoolean와이드 여부
        createTimeMandatoryDateTime이미지 업로드 시간

        응답 Status

        HTTP StatusDesc
        200Ok (업로드 완료)
        400Bad Request
        401Unauthorized
        403Forbidden
        404Not Found
        500Internal Server Error

        이미지 목록 조회

        업로드된 이미지 목록을 조회합니다.

        요청 URL

        GET https://sens.apigw.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}
        HTTP

        Path Variables

        항목MandatoryType설명비고
        serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디

        Headers

        API Header 바로가기

        Parameters

        항목MandatoryType설명비고
        pageIndexOptionalInteger페이지 인덱스default: 0
        pageSizeOptionalInteger페이지 사이즈default: 20 (1 ~ 100 사이의 숫자만 입력 가능)

        요청 Body

        없음
        JSON

        응답 Body

        {
          "items": [
            {
              "imageId": "string",
              "imageName": "string",
              "imageUrl": "string",
              "isWide": "boolean",
              "createTime": "string"
            }
          ],
          "pageIndex": "integer",
          "pageSize": "integer",
          "itemCount": "integer",
          "totalCount": "integer"
        }
        JSON
        항목MandatoryType설명비고
        itemsMandatoryArray of Object이미지 데이터 목록이미지 데이터 참조
        pageIndexMandatoryInteger페이지 인덱스
        pageSizeMandatoryInteger페이지 사이즈
        itemCountMandatoryInteger조회된 아이템 개수
        totalCountMandatoryInteger전체 개수

        응답 Status

        HTTP StatusDesc
        200Ok (조회 완료)
        400Bad Request
        401Unauthorized
        403Forbidden
        404Not Found
        500Internal Server Error

        이미지 단건 조회

        업로드된 이미지를 단건 조회합니다.

        요청 URL

        GET https://sens.apigw.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}
        HTTP

        Path Variables

        항목MandatoryType설명비고
        serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디
        imageIdMandatoryString이미지 아이디업로드된 이미지 아이디

        Headers

        API Header 바로가기

        요청 Body

        없음
        JSON

        응답 Body

        {
            "imageId":"string",
            "imageName":"string",
            "imageUrl":"string",
            "isWide":"boolean",
            "createTime":"string"
        }
        JSON

        이미지 데이터

        항목MandatoryType설명비고
        imageIdMandatoryStrng이미지 아이디
        imageNameMandatoryString이미지 파일 이름
        imageUrlMandatoryString이미지 URL
        isWideMandatoryBoolean와이드 여부
        createTimeMandatoryDateTime이미지 업로드 시간

        응답 Status

        HTTP StatusDesc
        200Ok (조회 완료)
        400Bad Request
        401Unauthorized
        403Forbidden
        404Not Found
        500Internal Server Error

        이미지 삭제

        업로드된 이미지를 삭제합니다.

        요청 URL

        DELETE https://sens.apigw.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}
        HTTP

        Path Variables

        항목MandatoryType설명비고
        serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디
        imageIdMandatoryString이미지 아이디업로드된 이미지 아이디

        Headers

        API Header 바로가기

        요청 Body

        없음
        JSON

        응답 Body

        없음
        JSON

        응답 Status

        HTTP StatusDesc
        204No Content (삭제 완료)
        400Bad Request
        401Unauthorized
        403Forbidden
        404Not Found
        500Internal Server Error

        오류 코드

        비즈메시지 수신 결과 코드

        StatusError textDesc
        0000-정상 발송
        1001NoJsonBodyRequest Body가 Json형식이 아님
        1002InvalidHubPartnerKey파트너 키가 유효하지 않음
        1003InvalidSenderKey발신 프로필 키가 유효하지 않음
        1004NoValueJsonElementRequest BODY(Json)에서 name을 찾을 수 없음
        1005SenderNotFound발신 프로필을 찾을 수 없음
        1006DeletedSender삭제된 발신 프로필
        1007StoppedSender차단 상태의 발신 프로필
        1011ContractNotFound계약 정보를 찾을 수 없음
        1012InvalidUserKeyException잘못된 형식의 유저 키 요청
        1013InvalidAppLink유효하지 않은 app연결
        1014InvalidBizNum유효하지 않은 사업자번호
        1015TalkUserIdNotFonud유효하지 않은 app user id 요청
        1016BizNumNotEqual사업자등록번호 불일치
        1020InvalidReceiveUserException올바른 유저 식별자 값이 하나도 없는 경우
        1021BlockedProfile차단 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
        1022DeactivatedProfile닫힘 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
        1023DeletedProfile삭제된 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
        1024DeletingProfile삭제 대기 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
        1025SpammedProfile메시지 차단 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
        1026UnableUseMessageType해당 msg_type에서 사용할 수 없는 response_method 로 요청 (이미지 알림톡(AI)은 실시간으로 발송 불가)
        1027-채널 메시지 제재 상태로 인한 메시지 전송 실패
        1030InvalidParameterException잘못된 파라메터 요청
        1033-템플릿 타입과 메시지 타입 불일치
        2000FailedToCheckFriendshipException톡채널과 친구 관계 확인 시 에러 (시스템 에러)
        2003FailedToSendMessageByNoFriendshipException메시지 전송 실패 (테스트 서버에서 카카오톡 채널을 추가하지 않은 경우)
        2004FailedToMatchTemplateException템플릿 일치 확인 시 오류 발생 (카카오 내부 오류)
        2005FailedToReadImageException카카오에서 이미지 메타 정보 읽어오는 중 에러
        2006FailedToMatchSerialNumberPrefixPattern시리얼넘버 형식 불일치
        3000UnexceptedExcetpion예기치 않은 오류 발생
        3005AckTimeoutException메시지를 발송 했으나 수신확인 안 됨 (성공 불확실)
        3006FailedToSendMessageException카카오 내부 시스템 오류로 메시지 전송 실패
        3008InvalidPhoneNumberException전화번호 오류
        3010JsonParsseExcetpionJson 파싱 오류
        3011MessageNotFoundException메시지가 존재하지 않음
        3012SerialNumberDuplicatedException메시지 일련번호가 중복됨 (메시지 일련 번호는 고유의 값이 부여되어야 함)
        3013MessageEmptyException빈 메시지
        3014MessageLengthOverLimitException메시지 길이 제한 오류 (텍스트 타입 1000자 초과, 이미지 타입 400자 초과)
        3015TemplateNotFoundException템플릿을 찾을 수 없음
        3016NoMatchedTemplateException메시지 내용이 템플릿과 일치하지 않음
        3018NoSendAvailableException메시지를 전송할 수 없음
        3019MessageNoUserException톡유저가 아님
        3020MessageUserBlockedAlimTalkException알림톡 차단
        3021MessageNotSupportedKakaotalkException톡 최소 버전 미지원
        3022NoSendAvailableTimeException메시지 발송 가능한 시간이 아님 (친구 톡/마케팅 메시지는 08시~ 20시까지 발송 가능)
        3023MessageInvalidVideoException메시지에 포함된 비디오를 전송할 수 없음 (비디오 주소 또는 썸네일 이미지 주소가 올바르지 않거나 썸네일 이미지가 규격에 맞지 않음)
        3024MessageInvaildImageException메시지에 포함된 이미지를 전송할 수 없음
        3025ExceedMaxVariableLengthException변수 글자 수 제한 초과
        3026Button chat_extra(event)-InvalidExtra(EventName)Exception '([A-Za-z0-9_]{1,50})'상담/봇 전환 버튼 extra, event 글자수 제한 초과
        3027NoMatchedTemplateButtonException버튼 내용이 템플릿과 일치 하지 않음
        3028NoMatchedTemplateTitleException메시지 강조 표기 타이틀이 템플릿과 일치하지 않음
        3029ExceedMaxTitleLengthException메시지 강조 표기 타이틀 길이 제한 초과 (50자)
        3031-텍스트 유형 불일치
        3030NoMatchedTemplateWithMessageTypeException메시지 타입과 템플릿 강조유형이 일치하지 않음
        3031NoMatchedTemplateHeaderException헤더가 템플릿과 일치하지 않음
        3032ExceedMaxHeaderLengthException헤더 길이 제한 초과(16 자)
        3033NoMatchedTemplateItemHighlightException아이템 하이라이트가 템플릿과 일치하지 않음
        3034ExceedMaxItemHighlightTitleLengthException아이템 하이라이트 타이틀 길이 제한 초과 (이미지 없는 경우 30 자, 이미지 있는 경우 21 자)
        3035ExceedMaxItemHighlightDescriptionLengthException아이템 하이라이트 디스크립션 길이 제한 초과 (이미지 없는 경우 19 자, 이미지 있는 경우 14 자)
        3036NoMatchedTemplateItemListException아이템 리스트가 템플릿과 일치하지 않음
        3037ExceedMaxItemDescriptionLengthException아이템 리스트의 아이템의 디스크립션 길이 제한 초과(23 자)
        3038NoMatchedTemplateItemSummaryException아이템 요약 정보가 템플릿과 일치하지 않음
        3039ExceedMaxItemSummaryDescriptionLengthException아이템 요약정보의 디스크립션 길이 제한 초과(14 자)
        3040InvalidItemSummaryDescriptionException아이템 요약 정보의 디스크립션에 허용되지 않은 문자 포함(통화기호/코드, 숫자, 콤마, 소수점, 공백을 제외한 문자 포함)
        3041MessageInvalidWideItemListLengthException와이드 아이템 리스트 개수 최소, 최대 개수 불일치
        3042NoMatchedTemplateRepresentLinkException대표 링크가 템플릿과 일치하지 않음
        3046ExceedMaxAdditionalContentLengthException부가 정보 최대 길이 제한 오류
        3047ExceedMaxCommerceTitleLengthException커머스 정보 상품명 최대 길이 제한 오류
        3050MessageNotSupportedUnsubscribeException수신 동의 거부 스펙 (N 타입) 미지원
        3051InvalidateCarouselItemMinException or InvalidateCarouselItemMaxException캐러셀 아이템 리스트 개수 최소, 최대 개수 불일치
        3052CarouselMessageLengthOverLimitException캐러셀 아이템 메시지 길이 초과
        3056WideItemListTitleLengthOverLimitException와이드 아이템 리스트 타이틀 길이 제한 오류
        3058CarouselHeaderLengthOverLimitException캐러셀 헤더 길이 제한 오류
        3059MessageNotSupportedCouponException쿠폰 스펙 미지원
        4000ResponseHistoryNotFoundException메시지 전송 결과를 찾을 수 없음
        4001UnKnownMessageStatusError알수 없는 메시지 상태
        7011-시리얼 넘버 패턴 에러
        7014-메시지 유효 시간 초과 에러
        8512-수신자 타입 찾을 수 없음
        8514-request_id 찾을 수 없음
        8520-지원하지 않는 상품 타입 오류
        8521-지원하지 않는 메시지 타입 오류
        8522-지원하지 않는 텍스트 유형 오류
        8523-지원하지 않는 response method 오류
        8530-수신자 목록 사이즈 오류
        8999-내부 서버 오류
        9998현재 서비스를 제공하고 있지 않습니다.시스템에 문제가 발생하여 담당자 확인 중
        9999시스템에 알 수 없는 문제 발생, 담당자 확인 중시스템에 문제가 발생하여 담당자 확인 중
        B000Prepare to relay failed중계사 발송을 위한 사전 작업 실패
        B001Request to relay failed중계사 발송 실패
        B002Filtering for request to relay failed잘못된 요청으로 인해 필터링됨
        B003Invalid phone number format올바르지 않은 발신번호 포멧
        B004Quota Exceed쿼터 초과
        B005Message processing timeout exceed메시지 요청 시간과 처리 시간의 차이가 허용 범위를 벗어남
        B400Invalid Request메시지 형식 오류
        B999Unexpected server error예기치 못한 에러

        이 문서가 도움이 되었습니까?

        Changing your password will log you out immediately. Use the new password to log back in.
        First name must have atleast 2 characters. Numbers and special characters are not allowed.
        Last name must have atleast 1 characters. Numbers and special characters are not allowed.
        Enter a valid email
        Enter a valid password
        Your profile has been successfully updated.