알림톡 서비스

알림톡 서비스 API 규격서

IWINV 알림톡 REST API 규격서 입니다.

 

목차 

  알림톡 발송

  템플릿

  전송 결과

  잔액 조회

 

 

 알림톡 발송 


 

기본정보


 

HEADERS 

    Content-Type

    AUTH

application/json;charset=UTF-8

base64_encode ( API Key )

 
 

알림톡 발송

알림톡의 발송 가능 문자수는 한/영 구분 없이 1,000자까지 발송 가능합니다.

반드시 변수 포함 1,000자 이내로 작성해주셔야 합니다.

발신번호는 '발신번호 관리'에서 등록된 번호여야 합니다.


 

URL

    POST  https://biz.service.iwinv.kr/api/send/


BODY

{

     "templateCode": "10030", 

     "reserve": "Y",

     "sendDate": "2021-07-20 05:00:00",

     "reSend": "Y",

     "resendCallback": "01000000000",

     "resendType": "Y",

     "resendTitle": "smstitle",

     "resendContent": "smscontent",

     "list":

     [

         {

              "phone": "01012341234",

              "templateParam": ["11","2","3"]

         },

         {

              "phone": "01012341235",

              "templateParam": ["1","2","3"]

         },

         {

              "phone": "01012341236",

              "templateParam": ["1","2","3"]

         }

    ]

}



  값   타입   필수   설명   예시
templateCode String O 사용 가능한 템플릿 코드 10001
reserve String X (기본 N) 예약발송 여부(N:즉시발송, Y:예약발송) Y , N
sendDate String X 발송 시각(예약 발송인 경우 필수, 예약 발송은 현재 시간 15분 이후 한달 이전까지만 가능합니다.) yyyy-MM-dd HH:mm:ss
reSend String X (기본 N) 알림톡 발송 실패 시 대체 문자 전송 기능(Y:대체 발송, N:대체 발송 없음) Y , N
resendCallback String X 발신번호   010-0000-0000 혹은 01000000000
resendType String X (기본 Y) 대체 발송 내용 타입 (Y:알림톡 내용, N:직접 입력) Y , N
resendTitle String X 실패 시 LMS 대체 문자 제목   -
resendContent String X 실패 시 대체 문자 내용(대체 발송 내용 타입 직접 입력 시 필수)   SMS(90Bytes 이하) / LMS(91~2000 Bytes)
list Array O 수신자 리스트(최대 1000명) -
- phone Array O 수신번호 010-0000-0000 혹은 01000000000
- templateParam Array X 템플릿 변수(템플릿 내용 중 치환할 항목(변수) 포함 시 필수) [["항목1","항목2","항목3"],["항목1","항목2","항목3"]]
 

응답

{

    "code": 200,

    "message": "메시지가 발송되었습니다",

    "success": 3,

    "fail": 1

}

 

  값   타입   설명
code Integer 응답 코드
message String 응답 코드 결과 메시지
success Integer 정상적으로 전송 요청된 연락처 개수
fail Integer 전송 요청되지 않은 연락처 개수

 

 

 

          -- 맨 위로 --

 

템플릿


 

 

기본정보


  

HEADERS

    Content-Type

    AUTH

application/json;charset=UTF-8

base64_encode ( API Key )

 

 

 

템플릿 리스트

 등록된 템플릿 목록을 조회합니다. 


 

URL

    POST https://biz.service.iwinv.kr/api/template/

 

BODY

 

{

    "pageNum": "1",

    "pageSize": "15",

    "templateCode": "10030",

    "templateName": "test1",

    "templateStatus": "R"

}

 

  값   타입   필수   설명   예시
pageNum Integer X 페이지 번호(기본:1) 1
pageSize Integer X 조회 건수(기본:15, 최대:1000) 10
templateCode String X 템플릿 코드 10001
templateName String X 템플릿 이름 템플릿 이름
templateStatus String X 템플릿 상태 코드(Y:사용가능, I:검수중, R:부결(반려)) Y

 

 

응답

{

    "code": 200,

    "message": "정상적으로 호출하였습니다.",

    "totalCount": 2,

    "list":

     [

          {

               "templateCode": "10036",

               "templateName": "알림",

               "templateContent": "#{이름} 고객님 우리 회사와 거래하여주셔서 감사합니다.",

               "status": "Y",

               "createDate": "2021-06-21 10:01:31",

               "buttons":

               [

                    {

                          "ordering": null,

                          "name": "iwinv",

                          "linkType": "WL",

                          "linkTypeName": "웹링크",

                          "linkMo": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}",

                          "linkPc": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}",

                          "linkIos": null,

                          "linkAnd": null

                     }

                ]

           }

     ]

}

 

  값   타입   설명
code Integer 응답 코드
message String 응답 코드 결과 메시지
totalCount Integer 등록된 템플릿 총 개수
list JSON 템플릿 리스트
- templateCode String 템플릿 코드
- templateName String 등록된 템플릿 명
- templateContent String 등록된 템플릿 내용
- status String 상태(Y:사용가능, I:검수중, R:부결(반려))
- createDate String 사용 가능 일시
- buttons Array 템플릿 버튼 정보
-- ordering String 버튼 순서(1~5)
-- name String 버튼명
-- linkType String 버튼 타입(WL:웹링크, AL:앱링크, DS:배송조회, BK:봇키워드, MD:메시지전달)
-- linkTypeName String 버튼 타입명
-- linkMo String 모바일 웹 링크(WL)
-- linkPc String PC 웹 링크(WL)
-- linkIos String IOS 앱링크(AL)
-- linkAnd String 안드로이드 앱링크(AL)

 

 

 

템플릿 생성

알림톡은 미리 지정한 템플릿만 사용 가능합니다. 

한/영 구분 없이 띄어쓰기 포함 1,000자까지 발송 가능합니다. 

템플릿 검수 기간은 2~3 영업일 소요되며, 신청한 내용에 따라 더 걸릴 수 있습니다.


 

 

URL 

    POST  https://biz.service.iwinv.kr/api/template/add/

 

BODY

{

    "templateName": "템플릿명",

     "templateContent": "템플릿 내용",

    "buttons":

    [

         {

             "type": "WL",

             "name": "웹링크",

             "linkMo": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}",

             "linkPc": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}"

         },

         {

             "type": "AL",

             "name": "앱링크",

             "linkIos": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}",

             "linkAnd": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}"

         },

         {

             "type": "DB",

             "name": "배송조회"

         },

         {

             "type": "BK",

             "name": "봇 키워드"

         },

         {

             "type": "MD",

             "name": "메시지 전달"

         }

    ]

}

 

  값   타입   필수   설명   예시
templateName String O 템플릿명(최대 15자) 템플릿명
templateContent String O 템플릿 내용(최대1000자) 가변 항목은 #{항목} 형태로 최대 10개까지 등록이 가능합니다.
buttons JSON X 템플릿 버튼(최대 5개) -
- type String X 버튼 타입 WL:웹링크, AL:앱링크, DB:배송조회, BK:봇 키워드, MD:메시지 전달
- name String X 버튼 이름(버튼이 있는 경우 필수, 최대 15자) -
- linkMo String X 모바일 웹 링크(WL 타입일 경우 필수, 최대200자) http:// 또는 Https://
- linkPc String X PC 웹 링크(WL 타입일 경우 필수, 최대200자) http:// 또는 Https://
- linkIos String X IOS 앱 링크(AL 타입일 경우 필수, 최대200자) -
- linkAnd String X Android 앱 링크(AL 타입일 경우 필수, 최대200자) -

 

응답

{

    "code": 200,

    "message": "정상적으로 템플릿을 생성하였습니다."

}

 

  값   타입   설명
code Integer 응답 코드
message String 응답 코드 결과 메시지

 

 

 

 템플릿 수정

템플릿 상태가 부결인 경우, 템플릿 내용을 수정해서 재 검수 요청을 하실 수 있습니다.


 

 

URL

    POST https://biz.service.iwinv.kr/api/template/modify/

 

 

BODY

{

    "templateCode": "10031",

    "templateName": "템플릿명",

    "templateContent": "템플릿 내용",

    "buttons":

    [

        {

             "type": "WL",

             "name": "웹링크",

             "linkMo": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}",

             "linkPc": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}"

        },

        {

             "type": "AL",

             "name": "앱링크",

             "linkIos": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}",

             "linkAnd": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}"

        },

        {

             "type": "DB",

             "name": "배송조회"

        },

        {

             "type": "BK",

             "name": "봇 키워드"

        },

        {

             "type": "MD",

             "name": "메시지 전달"

        },

    ]

}

 

 

  값   타입   필수   설명   예시
templateCode String O 템플릿 코드 -
templateName String O 템플릿명(최대15자) -
templateContent String O 템플릿 내용(최대 1000자) -
buttons JSON X 템플릿 버튼(최대 5개) -
- type String X 버튼 타입 WL:웹링크, AL:앱링크, DB:배송조회, BK:봇 키워드, MD:메시지 전달
- name String X 버튼 이름(버튼이 있는 경우 필수, 최대 15자) -
- linkMo String X 모바일 웹 링크(WL 타입일 경우 필수, 최대200자) http:// 또는 Https://
- linkPc String X PC 웹 링크(WL 타입일 경우 필수, 최대200자) http:// 또는 Https://
- linkIos String X IOS 앱 링크(AL 타입일 경우 필수, 최대200자) -
- linkAnd String X Android 앱 링크(AL 타입일 경우 필수, 최대200자) -

 

 

 

응답

{

    "code": 200,

    "message": "정상적으로 템플릿을 생성하였습니다."

}

 

     타입   설명
code Integer 응답 코드
message String 응답 코드 결과 메시지

 

 

 

템플릿 삭제

불필요한 템플릿을 삭제해도 완전히 삭제된 것이 아닌 카카오 서버에 데이터가 남아있습니다.

템플릿 삭제 후 삭제된 동일한 템플릿명은 사용이 불가합니다.


 

 

URL

POST https://biz.service.iwinv.kr/api/template/delete/

 

BODY

{

    "templateCode": "10036"

}

 

  값   타입   필수   설명   예시
templateCode String O 템플릿 코드 -

 

 

 응답

{

    "code": 200,

    "messgae": "선택하신 템플릿이 삭제되었습니다."

}

 

  값   타입   설명
code Integer 응답 코드
message String 응답 코드 결과 메시지

 

  

 

          -- 맨 위로 --

 

 

전송 결과


 

 

기본정보


 

 

HEADER 

    Content-Type

    AUTH

application/json;charset=UTF-8

base64_encode ( API Key )

 

 

 

전송 내역 조회

조회 시작일을 지정하여 조회하실 수 있습니다.

시작일 입력하지 않은 경우 오늘 기준 7일 전 전송 내역이 조회됩니다. 


 

 

URL 

    URL https://biz.service.iwinv.kr/api/history/

 

BODY  

{

    "pageNum": "1",

    "pageSize": "15",

    "reserve": "N",

    "startDate": "2021-04-05",

    "endDate": "2021-06-23",

    "seqNo": "17",

    "phone": "010-0123-0123"

}

 

  값   타입   필수   설명   예시
pageNum Integer X 페이지 번호(기본:1) 1
pageSize Integer X 조회 건수(기본:15, 최대:1000) 10
reserve String X 예약발송 여부(N:즉시발송, Y:예약발송) Y , N
startDate String X 발송 요청 시작일자(yyyy-MM-dd HH:mm:ss) 2021-01-01 13:00:00
endDate String X 발송 요청 마감일자(yyyy-MM-dd HH:mm:ss) 2021-01-01 13:00:00
seqNo Integer X 메시지 ID -
phone String X 수신번호 010-0000-0000 혹은 01000000000

 

 

응답

{

    "code": 200,

    "totalCount": 1,

    "message": "데이터가 조회되었습니다.",

    "list":

    [

        {

            "seqNo": 17,

            "phone": "01000000000",

            "callback": "16884879",

            "templateCode": "10034",

            "sendMessage": "홍길동 운영 중인 사이트에 문제가 발생하였습니다",

            "reserve": "N",

            "requestDate": "2021-06-23 15:22:39",

            "sendDate": "2021-06-23 15:22:40",

            "receiveDate": "2021-06-23 15:22:50",

            "statusCode": "OK",

            "statusCodeName": "성공",

            "resendStatus": null,

            "resendStatusName": null,

            "buttons": {

                 "link1": null,

                 "link2": null,

                 "link3": null,

                 "link4": null,

                 "link5": null

            }

        }

    ]

}

   

  값   타입   설명
code Integer 응답 코드(200:조회 성공)
totalCount Integer 전송 메시지 총 개수
message String 응답 코드 결과 메시지
list Array 전송 목록
- seqNo String 메시지 ID
- phone String 수신번호
- callback String 발신번호
- templateCode String 템플릿 코드
- sendMessage String 전송한 메시지
- reserve String 예약발송 여부(N:즉시발송, Y:예약발송)
- requestDate String 요청일
- sendDate String 전송일
- receiveDate String 수신일
- statusCode String 알림톡 발송 요청 상태 코드
- statusCodeName String 알림톡 발송 요청 상태 코드명
- resendStatus String 대체 발송 상태 코드
- resendStatusName String 대체 발송 상태 코드명
- buttons Array 버튼 내용

 

 

 

예약 문자 취소

예약 취소는 발송 예정시간 15분 이전의 문자만 가능합니다.


 

 

 

URL

    URL https://biz.service.iwinv.kr/api/cancel/

 

BODY

{

    "seqNo": "17"

}

 

  값   타입   필수   설명   예시
seqNo Array O 메시지ID -

 

응답

{

    "code": 200,

     "message": "알림톡 예약 발송이 삭제되었습니다."

}

 

  값   타입   설명
code Integer 응답 코드
message String 응답 코드 결과 메시지

 

 

          -- 맨 위로 --

 

 

 

 

잔액 조회


 

 

기본정보
 
HEADER 

    Content-Type

    AUTH

application/json;charset=UTF-8

base64_encode ( API Key )

 

 

 

잔액 조회

자동 결제(충전)된 요금에서 메시지 발송 후 남은 금액과 메시지 발송 실패 시 반환된 금액의 합계입니다.


 

  

URL

 

    URL https://biz.service.iwinv.kr/api/charge/

  

응답

{

       "code": 200,

        "message": "데이터가 조회되었습니다.",

        "charge": 10000.0

}


   값     타입     설명
code Integer 응답 코드(200:조회 성공)
message String 응답 코드 결과 메시지
charge Float 잔액

 

 

          -- 맨 위로 --