14.1개요

본 문서는 https 프로토콜을 통해 데이터를 json 형식으로 가공하여 GET, POST method를 사용하여 전송하고, json형식의 결과 데이터를 parsing하여 처리할 수 있음을 전제로 작성되었다.
제휴한 SMS 통해 사용자에게 SMS/LMS/MMS 메시지 전송할수 있다.(현재는 M&Wize, gabia 만 가능)

14.2용어 정의

14.2.1약어

MMS: Multimedia Message Service
SMS: Short Message Service
LMS: Long Message Service, 2000byte 로 구성된 메시지

14.2.2고객사 구분값/발신프로필키

앰앤와이즈에서 제공하는 고객사 구분값 및 발신 프로필키

14.3선결 조건

SMS API를 사용하여 메시지 전송을 대행하기 위해 아래의 조건이 선결되어야 한다.

14.3.1앰엔와이즈 사용고객

[앰앤와이즈] 고객사 구분값, 발신프로필키를 발급
엠엔와이즈 서버/포트 방화벽을 미리 해제

14.3.2Kakao i 사용고객

[카카오엔터프라이즈] 고객사 구분값, 발신프로필키를 발급
서버/포트 방화벽을 미리 해제
미리 알림톡 탬플릿을 설정해서 승인을 받아야 한다.

14.3.3INFOBANK 사용고객

Bizgo 에서 연동계정 추가(OMNI API) 및 연동계정 아이디 생성
Bizgo 에서 발신번호 등록
서버/포트 방화벽을 미리 해제

14.4설정(API 서버설정)

SMS API를 사용하여 메시지 전송을 대행하기 sms.conf 파일을 설정해야 한다.

14.4.1sms.conf

#//////////////////////////////////////////////////
# sms configuration 
#//////////////////////////////////////////////////

[api]
domain        = test3.nexuscommunity.net
api_port    = 8447
https        = no
cert_password   = D8529C7ED77EA93989E64B4C16CF8767
provider_list = kakaoi, nexus, infobank

[sms]
sms_mode    = polling   
#realtime: real time resopnse , polling: Result inquiry by request.
sms_provider    = kakaoi  #mnwise, gabia, kakaoi, infobank
sms_polling_time = 60 # result polling second
sms_max_polling = 30  # result request max coun

[dbms]
type        = MariaDB
host        = 10.10.30.45  # qa dev 121.170.212.215
username    = nexus
password    = EC6AF30FAD902C6912A3E4EC9B02EF3A
database    = sms
port        = 3306
encrypt     = 3103CF8FE41CCD91D587A17B4018EE40


[thread]
max_client    = 1024

#//////////////////////////////////////////////////
# provider info 
# provider_list 의 개수만큼 아래에 세팅한다.
#//////////////////////////////////////////////////

[nexus]
host        = 127.0.0.1
port        = 8443
mng_host    = 127.0.0.1
mng_port    = 8443

[mnwise]
host        = wt-api.carrym.com
port        = 8443
company_code    = ubase
sender_key    = 16056ed0f96cca0bdc72e88b6e96452547c10c5b
mng_host    = wt-api.carrym.com
mng_port    = 8445

[gabia]
host        = sms.gabia.com
port        = 443
sms_id        = nexuscube
api_key        = 91ea5b11c80c018e29a9520763fdd82a

[kakaoi]
host        = stg-web.bizmsg.kakaoenterprise.com
port        = 443
api_id        = R000000029
api_key        = R000000029_Ry+bwRrCQK2VdsGakoUGig

mng_host    = stg-web.bizmsg.kakaoenterprise.com
mng_port    = 443
mng_id        = R000000029
mng_key        = R000000029_Ry+bwRrCQK2VdsGakoUGig

result_complete    = no


[infobank]
host        = omni.ibapi.kr 
port        = 443
api_id      = 2158_om_i5450lk1
api_key     = 2646MX

#//////////////////////////////////////////////////
# nxpostsms 대체시 설정해 준다.
#//////////////////////////////////////////////////
[uconnect_dbms]
type        = MariaDB 
host        = 10.10.30.45 # 빈값이면 결과값 반영안함.  43: 개발 :q 45:caas
username    = nexus
password    = EC6AF30FAD902C6912A3E4EC9B02EF3A
database    = JEDAI_CUBE
port        = 3306
encrypt     = 3103CF8FE41CCD91D587A17B4018EE40

14.5전송 API

14.5.1Host

카카오 중계 서버
[개발서버] http://jedai.nexuscommunity.net:8070/

14.5.2SMS 전송 요청

[Request]

path : /sms/send
method : POST
header
Content-type: application/json
parameter (json array포맷) : [{sender_key:"", }, ...]

[Parameter]

키	타입	필수	설명	예제
sender_key	text(40)	Y/N	UKAKAO 프로필 키 KAKAO i 일 경우 보내면 안된다.	"sender_key":"2662e99eb7a1f21abb3955278e9955f5a9a99b62"
provider	text	N	제휴 회사(mnwise, kakaoi, gabia, infobank)	"provider":"mnwise"
client_id	text(40)	Y/N	KAKAO I 클라이언트 아이디 (빈값 허용)	"client_id":""
phone_number	text(16)	Y	수신자 전화번호	"phone_number":"01012345678"
message	text(90)	N	사용자에게 전달될 메시지 (공백 포함 90자로 제한)	"message":"고객님의 택배가 금일 (18~20)시에 배달 예정입니다."
sender_number	text(19)	N	발신자 전화번호	"sender_number":"15881600"
serial_number	text(39)	N	메시지일련번호(고유값) - 자동생성	"serial_number":"20230515-100DA-6461EE99"

[Response]

키		타입	필수	설명	예제
code		text		응답코드(200인정상/나머지는 오류)
data		array
	code	text(4)	Y	처리 결과 코드	"code ":"EW" <5.1 오류코드 에서 확인 가능>
	serial_number	text	Y	결과 조회시 사용할 키	"serial_number": "SMS-0001-62061C90"
	cid	text	Y	serial_number 와 동일
	message	text	Y	응답 메시지	"message": "SMS\/MMS Sending"

14.5.3LMS 전송 요청

[Request]

path : /lms/send
method : POST
header
Content-type: application/json
parameter (json array포맷) : [{sender_key:"", }, ...]

[Parameter]

키	타입	필수	설명	예제
sender_key	text(40)	Y/N	발신 프로필 키 KAKAO i 는 보내면 안된다.	"sender_key":"2662e99eb7a1f21abb3955278e9955f5a9a99b62"
provider	text	N	제휴 회사(mnwise, kakaoi, gabia, infobank)	"provider":"mnwise"
client_id	text(40)	Y/N	KAKAO I 클라이언트 아이디 (빈값 허용)	"client_id":""
phone_number	text(16)	Y	수신자 전화번호	"phone_number":"01012345678"
subject	text(40)	N	LMS 제목
message	text(2000)	Y	사용자에게 전달될 메시지 (공백 포함 2000자로 제한)	"message":"고객님의 택배가 금일 (18~20)시에 배달 예정입니다."
sender_number	text(19)	N	발신자 전화번호	"sender_number":"15881600"
serial_number	text(39)	N	메시지일련번호(고유값) - 자동생성	"serial_number":"20230515-100DA-6461EE99"

[Response]

키		타입	필수	설명	예제
code		text		응답코드(200인정상/나머지는 오류)
data		array
	code	text(4)	Y	처리 결과 코드	"code ":"EW" <5.1 오류코드 에서 확인 가능>
	serial_number	text	Y	결과 조회시 사용할 키	"serial_number": "SMS-0001-62061C90"
	cid	text	Y	serial_number 와 동일
	message	text	Y	응답 메시지	"message": "SMS\/MMS Sending"

14.5.4MMS 전송 요청

[Request]

path : /mms/send
method : POST
header
Content-type: application/json
parameter (json array포맷) : [{sender_key:"", }, ...]

infobank
- 만료일(expired)이 지난 이미지를 포함한 MMS 전송 요청에 대한 응답은 성공을 반환하며, 차후 Polling 처리에서 전송 결과를 조회 시 실패가 반환 됩니다.

[Parameter]

키	타입	필수	설명	예제
sender_key	text(40)	Y/N	발신 프로필 키 KAKAO i 는 보내면 안된다.	"sender_key":"2662e99eb7a1f21abb3955278e9955f5a9a99b62"
provider	text	N	제휴 회사 (mnwise,, gabia, infobank)	"provider":"mnwise"
phone_number	text(16)	Y	수신자 전화번호	"phone_number":"01012345678"
subject	text(40)	N	MMS 제목
message	text(2000)	Y	사용자에게 전달될 메시지 (공백 포함 2000자로 제한)	"message":"고객님의 택배가 금일 (18~20)시에 배달 예정입니다."
sender_number	text(19)	N	발신자 전화번호	"sender_number":"15881600"
files	array	Y	첨부파일	최대 3개, 1건당 200KB이하
serial_number	text(39)	N	메시지일련번호(고유값) - 자동생성	"serial_number":"20230515-100DA-6461EE99"

files 상세

키		타입	필수	설명
files				파일
	seq	text(1)	Y	값: 1, 2, 3
	file_id	text(100)	Y	전송할 이미지 id (이미지 업로드 참조)

[Response]

키		타입	필수	설명	예제
code		text		응답코드(200인정상/나머지는 오류)
data		array
	code	text(4)	Y	처리 결과 코드	"code ":"EW" <5.1 오류코드 에서 확인 가능>
	serial_number	text	Y	결과 조회시 사용할 키	"serial_number": "SMS-0001-62061C90"
	cid	text	Y	serial_number와 동일
	message	text	Y	응답 메시지	"message": "SMS\/MMS Sending"

14.5.5MMS 전송 요청(KAKAO I)

[Request]

path : /mms/send
method : POST
header
Content-type: application/json
parameter (json array포맷) : [{sender_key:"", }, ...]

[Parameter]

키	타입	필수	설명	예제
client_id	text(40)	Y/N	KAKAO I 클라이언트 아이디 (빈값 허용)	"client_id":""
provider	text	N	kakaoi	"provider":"kakaoi"
phone_number	text(16)	Y	수신자 전화번호	"phone_number":"01012345678"
subject	text(40)	N	MMS 제목
message	text(2000)	Y	사용자에게 전달될 메시지 (공백 포함 2000자로 제한)	"message":"고객님의 택배가 금일 (18~20)시에 배달 예정입니다."
sender_number	text(19)	N	발신자 전화번호	"sender_number":"15881600"
content_group_id	text	Y/N	첨부파일 GROUD ID - MMS 이미지 업로드 응답값	content_group_id":"230306174403503d+UVz

[Response]

키		타입	필수	설명	예제
code		text		응답코드(200인정상/나머지는 오류)
data		array
	code	text(4)	Y	처리 결과 코드	"code ":"EW" <5.1 오류코드 에서 확인 가능>
	result	Object	Y	Object	결과 오브젝트
	uid	text	Y	응답 서버 ID
	cid	text	Y	전송 ID

[응답]

{
  "code": "200",
  "data": [
    {
      "code": "100",
      "result": {
        "detail_code": "",
        "detail_message": "SMS발송접수성공"
      },
      "uid": "230306175527205wail1ByPQcqv2Kt",
      "cid": "SMS-0002-6405AA04"
    }
  ]
}

14.5.6MMS 이미지 업로드(KAKAO I)

파일 업로드 시 다음의 사양을 충족시켜야 합니다.
- 파일수:최대3개
- 파일 형식: jpg
- 파일 크기: 총합 최대 200KB

[Request]

path : /mms/kakaoi/file
method : POST
header
Content-type: multipart/form-data
parameter (image)

[Parameter]

키	타입	필수	설명
images	binary	Y	업로드할 이미지 파일 배열

[Response] 응답 바디는 JSON객체로 아래 값을 참고 해주세요.

키		타입	설명
code		text	결과 코드 < 코드 정의 에서 확인 가능>
result		object	결과 OBJECT
	detail_code	text	결과 code
	detail_message	text	결과 Message
content_group_id		text	MMS 파일 업로드시 사용되는 그룹 ID

[Example]

curl -v -H "Expect:" -H "Content-type: multipart/form-data" -X POST "http://10.10.30.47:8447/mms/kakaoi/file" -F "images=@220_184.jpg" -F "images=@300_240.jpg"

[응답]

{
  "code": "200",
  "result": {
    "detail_code": "",
    "detail_message": "성공"
  },
  "content_group_id": "230306174403503d+UVz"
}

14.5.7MMS 이미지 업로드(INFOBANK)

파일 업로드 시 다음의 사양을 충족시켜야 합니다.
- 파일수:최대1개
- 파일 형식: jpg(jpeg)
- 최대 파일 크기: 300KB
- 제한 사이즈: 가로 1,500 세로 1,440 이하

만료일(expired)이 지난 이미지를 포함한 MMS 전송 요청에 대한 응답은 성공을 반환하며,

차후 Polling 처리에서 전송 결과를 조회 시 실패가 반환 됩니다.

[Request]

path : /mms/infobank/file
method : POST
header
Content-type: multipart/form-data
parameter (image)

[Parameter]

키	타입	필수	설명
file	binary	Y	업로드할 이미지 파일

[Response] 응답 바디는 JSON객체로 아래 값을 참고 해주세요.

키	타입	설명
code	text	결과 코드 < 코드 정의 에서 확인 가능>
message	text	응답 메시지
serial_number	text	업로드 이미지 id

[Example]

curl -v -H "Expect:" -H "Content-type: multipart/form-data" -X POST "http://10.10.30.47:8447/mms/infobank/file" -F "images=@220_184.jpg"

[응답]
{
  "code": "200", 
  "message": "OK", 
  "serial_number": "2158_om_i5450lk1_542d588c3f5b4d6e84e55983ba73eef3" 
}

{
  "code":"A000",
  "result":"Success",
  "data":
  {
    "fileKey":"2158_om_i5450lk1_5baf5dbb6d07418394f43b98a9ab5bc0",
    "expired":"2024-08-08T16:23:40+09:00"
  }
}

14.5.8MMS 이미지 업로드

MMS 전송에 사용될 이미지를 미리 업로드 해야 MMS 전송을 할수 있다.
이미지 파일은 200KB 이하 JPG 파일만 가능하다.
권장 해상도 : 220*184(해상도는 변경 가능하지만 특정 폰에서 표시를 못함)

[Request]

path : /image/mms
method : POST
header
Content-type: multipart/form-data
parameter (image)

[Parameter]

키	타입	필수	설명
image	binary	Y	업로드할 이미지 파일

[Response] 응답 바디는 JSON객체로 아래 값을 참고 해주세요.

키	타입	설명
code	text	결과 코드 < 코드 정의 에서 확인 가능>
message	text	응답 메시지
serial_number	text	업로드 이미지 id

[Example]

curl -v -H "Expect:" -H "Content-type: multipart/form-data" -X POST "http://127.0.0.1:8080/image/mms" -F "image=@720_720.png"


[응답]

{ 
 "code": "200", 
 "message": "OK", 
 "serial_number": "SMS-0001-61D4F2A4" 
}

14.5.9알림톡 전송(Kakao i , M&Wize, Nexus )

[Request]

path : /alimtalk/send
method : POST
header
Content-type: application/json
parameter (json)

[Parameter]

키	타입	필수	설명	예제
client_id	text	N	Kakao I 용(비즈메지즈 어드민 client id)	"client_id":"R00000029"
provider	text	N	제휴 회사(mnwise, kakaoi, nexus)	"provider":"mnwise"
sender_key	text(40)	Y/N	발신 프로필 키	"sender_key":"2662e99eb7a1f21abb3955278e9955f5a9a99b62"
phone_number	text(16)	N	사용자 전화번호 (국가코드(82)를 포함한 전화번호) phone_number 혹은 app_user_id 둘 중 하나는 반드시 있어야 한다.	"phone_number":"821012345678"
template_code	text(30)	Y	템플릿 코드 (실제 발송할 메시지 유형으로 등록된 템플릿의 코드)	"template_code":"A001_01"
message_type	text(2)	Y	(AT: 알림톡)	"message_type":"AT"
message	text(1000)	N	사용자에게 전달될 메시지 (공백 포함 1000자로 제한)	"message":"고객님의 택배가 금일 (18~20)시에 배달 예정입니다."
sender_no	text	Y	발신자 전화번호
title	text(50)	N	템플릿 내용 중 강조 표기할 핵심 정보 (CBT, 템플릿 검수 가이드 참고)	"title":"20분 내 도착 예정"
header	text(16)	N	메시지 상단에 표기할 제목	"header":"포인트 적립 안내"
timeout	number	N	타임아웃(초) (성공 여부를 결정하기 위한 시간)	"timeout":30
button	json	N	메시지에 첨부할 내용 (링크 버튼 / "target":"out" 속성 추가시 아웃링크)	"button":[{"name":"버튼명","type":"WL","url_pc":"http://naver.com", "url_mobile":"http://daum.net","target":"out"}]
quick_reply	json	N	메시지에 첨부할 바로연결 (링크 버튼 / "target":"out" 속성 추가시 아웃링크) M&Wise 미사용	"quick_reply":[{"name":"버튼명","type":"WL","url_pc":"http://naver.com", "url_mobile":"http://daum.net","target":"out"}]
fall_back_yn	boolean	Y	부달전송사용여부	"fall_back_yn":true
fall_back_sender_key	text(40)	Y/N	부달용 발신프로필키	provider 가 Nexus 일 경우 필요하다.
fall_back_message_type	text(2)	N	부달발송시메시지타입 SM: SM, LM: LMS 가능
fall_back_title	text	N	부달발송메시지제목
fall_back_message	text(2000)	N	부달발송메시지본문
price	number	N	모먼트 광고 전환 최적화 전용 메시지 내 포함된 가격/금액/결제금액	"price":39900
currency_type	text(3)	N	모먼트 광고 전환 최적화 전용 메시지 내 포함된 가격/금액/결제금액의 통화단위 KRW, USD, EUR 등 국제 통화 코드 사용	"currency_type":"KRW"

[button 정의]

키	타입	필수	설명
name	text(14)	Y	버튼명
type	text(2)	Y	버튼 타입 아래 button 타입에서 확인 가능
url_pc	text	N	pc 환경에서 버튼 클릭 시 이동할 url
url_moblie	text	N	mobile 환경에서 버튼 클릭 시 이동할 url
scheme_ios	text	N	mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme
scheme_android	text	N	mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme
chat_extra	text(50)	Y	상담톡/봇 전환 시 전달할 메타정보
chat_event	text(50)	N	봇 전환 시 연결할 봇 이벤트명
biz_form_id	number	N	카카오 폼 ID 값 (type 이 BF 일 경우는 필수)

[quick_reply 정의]

키	타입	필수	설명
name	text(14)	Y	버튼명
type	text(2)	Y	버튼 타입 아래 button 타입에서 확인 가능
url_pc	text	N	pc 환경에서 버튼 클릭 시 이동할 url
url_moblie	text	N	mobile 환경에서 버튼 클릭 시 이동할 url
scheme_ios	text	N	mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme
scheme_android	text	N	mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme
chat_extra	text(50)	Y	상담톡/봇 전환 시 전달할 메타정보
chat_event	text(50)	N	봇 전환 시 연결할 봇 이벤트명
biz_form_id	number	N	카카오 폼 ID 값 (type 이 BF 일 경우는 필수)

[SAMPLE]

curl  -H "Accept: application/json" -H "Content-type: application/json" \
-X POST -d \
 '{"client_id":"R000000029_001", "button":[{"name":"홈페이지 바로가기","type":"WL","url_mobile":"https://www.nexus.co.kr"}],"message_type":"AT","phone_number":"821029115543","message":"안녕하세요  넥서스 커뮤니티 입니다.\n장형길님의 콜백이 정상적으로 등록 되었습니다.","sender_key":"78c9e4d941c6db2de7c0fa54374e2988cd323a57","template_code":"NEXUS_CALLBACK_01", "sender_no":"15776824","fall_back_yn":true, "fall_back_message_type":"SM", "fall_back_message":"안녕하세요  넥서스 커뮤니티 입니다.\n#{성명}님의 콜백이 정상적으로 등록 되었습니다." }' \
   http://127.0.0.1:8080/alimtalk/send

[Response]

키		타입	필수	설명
code		text	N	메시지 발송코드(Kakao i API 참조, M&Wize API 참조)
uid		text	N	메시지 Key id(kakao)
cid		text	N	사용자 정의 Key id(nexus)
serial_number		text	N	사용자 정의 key id(nexus)
result		json		Kakao i API 참조
	detail_code	text(4)	N	세부 결과 코드 (참고용)
	detail_message	text	N	세부 결과 메시지 (참고용)

[SAMPLE]

{
  "code": "100",
  "result": {
    "detail_code": "0000",
    "detail_message": "성공"
  },
  "uid": "221028151754418ozx~erYqSi+5N6g",
  "cid": "SMS-0001-635B7412"
}

14.5.9.1button 타입별 속성

필수 파라메터를 모두 입력하셔야 정상적인 발송이 가능합니다.

버튼타입	속성	타입	필수	설명
WL	url_mobile	text	Y	버튼 클릭 시 이동할 pc/mobile환경별 web url
	url_pc	text	N
AL	scheme_android	text	-	scheme_ios, scheme_android, url_mobile 중 2가지 필수 입력 mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme
	scheme_ios	text	-	mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme
	url_mobile	text	-	mobile 환경에서 버튼 클릭 시 이동할 url
	url_pc	text	N	pc 환경에서 버튼 클릭 시 이동할 url
BK	-	-	-	해당 버튼 텍스트 전송
BC	-	-	-	상담톡을 이용하는 카카오톡 채널만 이용가능
	chat_extra	text	N	상담톡 전환 시 전달할 메타정보
BT	-	-	-	카카오 I 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용가능
	chat_extra	text	N	봇 전환 시 전달할 메타정보
	chat_event	text	N	봇 전환 시 연결할 봇 이벤트명
AC	-	-	-	버튼 클릭 시 카카오톡 채널 추가
BF	biz_form_id	number		카카오 비즈니스에서 생성한 비즈니스폼 ID

14.5.10알림톡 자동 발송(Tenant 정보로 알림톡 발송)

[Request]

path : /alimtalk/auto/send
method : POST
header
Content-type: application/json
parameter (json)

[Parameter]

키	타입	필수	설명	예제
tenant	text	Y	테넌트명	tenant:"1"
auto_type	text	Y	자동 발송 템플릿 구분 BOT_END: 봇과의 통화 종료시 CALL_END: 상담사와의 통화 종료시 SAMRT_CALLBACK:스마트콜백신청시 CHAT: 상담톡 전환시	auto_type:"BOT_END"
phone_number	text(16)	N	사용자 전화번호 (국가코드(82)를 포함한 전화번호)	"phone_number":"821012345678"
message_type	text(2)	Y	(AT: 알림톡)	"message_type":"AT"
timeout	number	N	타임아웃(초) (성공 여부를 결정하기 위한 시간)	"timeout":30
sender_no	text		발신번호
fall_back_yn	boolean	Y	부달전송사용여부	"fall_back_yn":true
fall_back_message_type	text(2)	N	부달발송시메시지타입 SM: SM, LM: LMS 가능
fall_back_title	text	N	부달발송메시지제목(LM 일때 사용)
fall_back_message	text(2000)	N	부달발송메시지본문
chat_mode	text	N	탬플릿 채팅전환 버튼(TYPE:BC) 으로 정보 정달 또는 상담원 바로 연결 정보 전달 "AGENT" : 상담원 바로 연결 "INFO" : 상담정보 전달	chat_mode:"INFO"
uuid	text	N	탬플릿 채팅전환 버튼(TYPE:BC)로 등록된 경우 전달할 UUID(숫자값)	uuid:"12345"
dn	text	N	탬플릿 채팅전환 버튼(TYPE:BC)로 등록된 경우 전달할 상담원 DN	dn:"30019"
var_name1	text	N	알림톡 등록시 #{변수} 형태로 넣은 값. 알림톡 변수 명	"var_name1" : "고객명"
var_value1	text	N	알림톡 변수 값	var_value1" : "홍길동"
var_name2	text	N	알림톡 변수 명
var_value2	text	N	알림톡 변수 값
var_name3	text	N	알림톡 변수 명
var_value3	text	N	알림톡 변수 값
var_name4	text	N	알림톡 변수 명
var_value4	text	N	알림톡 변수 값
var_name5	text	N	알림톡 변수 명
var_value5	text	N	알림톡 변수 값

curl  -H "Accept: application/json" -H "Content-type: application/json" \
-X POST -d \
 '{"tenant":"10", "auto_type":"CALLBACK_01","phone_number":"821012345678", "message_type":"AT","fall_back_yn":true, "fall_back_message_type":"SM", "fall_back_message":"안녕하세요  넥서스 커뮤니티 입니다.\n#{성명}님의 콜백이 정상적으로 등록 되었습니다." }' \
   http://127.0.0.1:8080/alimtalk/auto/send

14.5.11알림톡 자동 발송(Tenant 정보와 템플릿 코드로 알림톡 발송)

테넌트 정보와 템플릿 코드를 받아서 알림톡을 전송 합니다.

[Request]

path : /alimtalk/auto/code
method : POST
header
Content-type: application/json
parameter (json)

[Parameter]

키	타입	필수	설명	예제
tenant	text	Y	테넌트명	"tenant":"1"
template_code	text	Y	템플릿 코드	"template_code":"TEMPLATE001"
phone_number	text(16)	N	사용자 전화번호 (국가코드(82)를 포함한 전화번호)	"phone_number":"821012345678"
message_type	text(2)	Y	(AT: 알림톡)	"message_type":"AT"
timeout	number	N	타임아웃(초) (성공 여부를 결정하기 위한 시간)	"timeout":30
sender_no	text		발신번호
fall_back_yn	boolean	Y	부달전송사용여부	"fall_back_yn":true
fall_back_message_type	text(2)	N	부달발송시메시지타입 SM: SM, LM: LMS 가능
fall_back_title	text	N	부달발송메시지제목(LM 일때 사용)
fall_back_message	text(2000)	N	부달발송메시지본문
uuid	text	N	탬플릿 채팅전환 버튼(TYPE:BC)로 등록된 경우 전달할 UUID(숫자값)	uuid:"12345"
var_name1	text	N	알림톡 등록시 #{변수} 형태로 넣은 값. 알림톡 변수 명	"var_name1" : "고객명"
var_value1	text	N	알림톡 변수 값	var_value1" : "홍길동"
var_name2	text	N	알림톡 변수 명
var_value2	text	N	알림톡 변수 값
var_name3	text	N	알림톡 변수 명
var_value3	text	N	알림톡 변수 값
var_name4	text	N	알림톡 변수 명
var_value4	text	N	알림톡 변수 값
var_name5	text	N	알림톡 변수 명
var_value5	text	N	알림톡 변수 값

curl  -H "Accept: application/json" -H "Content-type: application/json" \
-X POST -d \
 '{"tenant":"10", "template_code":"CALLBACK_01","phone_number":"821012345678", "message_type":"AT","fall_back_yn":true, "fall_back_message_type":"SM", "fall_back_message":"안녕하세요  넥서스 커뮤니티 입니다.\n#{성명}님의 콜백이 정상적으로 등록 되었습니다." }' \
   http://127.0.0.1:8080/alimtalk/auto/code

[Response]

키		타입	필수	설명
code		text	N	메시지 발송코드(Kakao i API 참조)
uid		text	N	메시지 Key id(kakao)
cid		text	N	사용자 정의 Key id(nexus)
result		json		Kakao i API 참조
	detail_code	text(4)	N	세부 결과 코드 (참고용)
	detail_message	text	N	세부 결과 메시지 (참고용)

[SAMPLE]

{
  "code": "100",
  "result": {
    "detail_code": "0000",
    "detail_message": "성공"
  },
  "uid": "221028151754418ozx~erYqSi+5N6g",
  "cid": "SMS-0001-635B7412"
}

[Response]

키		타입	필수	설명
code		text	N	메시지 발송코드(Kakao i API 참조)
uid		text	N	메시지 Key id(kakao)
cid		text	N	사용자 정의 Key id(nexus)
result		json		Kakao i API 참조
	detail_code	text(4)	N	세부 결과 코드 (참고용)
	detail_message	text	N	세부 결과 메시지 (참고용)

[SAMPLE]

{
  "code": "100",
  "result": {
    "detail_code": "0000",
    "detail_message": "성공"
  },
  "uid": "221028151754418ozx~erYqSi+5N6g",
  "cid": "SMS-0001-635B7412"
}

14.5.12알림톡 템플릿 전체 목록 조회(현재는 Kakao i 연동만가능)

[Request]

path : /alimtalk/template/{sender_key}
method : GET
sender_key : 발신프로필키 (Biz Message 의 발신프로필 관리에서 확인할수 있습니다.)

[Parameter]

키	타입	필수	설명	예제
page	number	N	페이지번호(default:1)	page=1
rows	number	N	한 페이지에 보여줄 행의 수 (default: 100)	rows=100
startDate	text(10)	N	등록일 기준 검색 시작일 yyyy-MM-dd	startDate=2021-02-01
endDate	text(10)	N	등록일기준검색종료일yyyy-MM-dd	endDate=2021-02-01
kepStatus	text	N	검수 상태(N:Not Yet 아직진행하지않음, O:OK 통과, R:Reject 반려)	kepStatus=O

curl -v http://127.0.0.1:8080/alimtalk/template/78c9e4d941c6db2de7c0fa54374e2988cd323a57?kepStatus=O

[Response]

키		타입	설명
code		text	결과 코드(kakaoi Mng api 참조)
message		text	결과 메시지
page		number	현재 페이지
totalPage		number	총페이지수
totalCount		number	총템플릿수
hasNext		boolean	다음페이지존재여부
data		list	응답 데이터
	templateCode	text	템플릿코드
	templateName	text	템플릿이름
	templateStatus	text	템플릿 상태(S:중단, A:정상, R:대기(발송전))
	kepStatus	text	검수 상태 (N:Not Yet 아직진행하지않음, O:OK 통과, R:Reject 반려)
	categoryCode	text	템플릿 카테고리코드
	securityFlag	boolean	보안 템플릿 여부 (true:설정, false:미설정)
	regBy	text	등록자
	regDate	text	등록일
	updateBy	text	수정자
	updateDate	text	수정일

[SAMPLE]

{
  "page": 1,
  "code": "API_200",
  "message": "성공",
  "totalPage": 1,
  "totalCount": 1,
  "hasNext": false,
  "data": [
    {
      "templateCode": "NEXUS_CALLBACK_02",
      "templateName": "콜백 응답 02",
      "securityFlag": true,
      "templateStatus": "R",
      "kepStatus": "I",
      "categoryCode": "004002",
      "templateDormant": false,
      "templateBlock": false
    }
  ]
}

14.5.13알림톡 템플릿 상세조회(Kakao i, M&Wize 연동만가능)

[Request]

path : /alimtalk/template/{sender_key}/{templateCode}
method : GET
sender_key : 발신프로필키 (Biz Message 의 발신프로필 관리에서 확인할수 있습니다.)
templateCode : 알림톡 템플릿 코드 입니다.

curl -v http://127.0.0.1:8080/alimtalk/template/78c9e4d941c6db2de7c0fa54374e2988cd323a57/NEXUS_CALLBACK_01

[Response]

키		타입	설명
code		text	결과 코드(kakaoi Mng api 참조)
message		text	결과 메시지
data		list	응답 데이터
	templateCode	text	템플릿코드
	templateName	text	템플릿이름
	templateMessageType	text	템플릿 메시지 유형 (BA: 기본형, EX: 부가 정보형, AD: 광고 추가형, MI: 복합형)
	templateEmphasizeType	text	템플릿 강조표기 유형 (NONE: 선택안함, TEXT: 강조표기형)
	templateContent	text	템플릿내용
	templateExtra	text	부가 정보(템플릿 검수 가이드 참고, optional)
	templateAd	text	템플릿내수신동의요청또는간단광고문구(템플릿 검수 가이드 참고, optional)
	templateTitle	text	템플릿내용중강조표기할핵심정보(템플릿검수가이드 참고, optional)
	templateSubtitle	text	강조 표기 보조 문구 (템플릿 검수 가이드 참고, optional)
	status	text	템플릿 상태(S:중단, A:정상, R:대기(발송전))
	inspectionStatus	text	검수 상태(REG:등록, REQ:심사요청, APR:승인, REJ: 반려)
	categoryCode	text	템플릿 카테고리코드
	securityFlag	boolean	보안 템플릿 여부 (true:설정, false:미설정)
	buttons	list	버튼 정보
	quickReplies	list	바로연결 정보
	comments	list	댓글 정보 리스트
	createdAt	text	등록일
	modifiedAt	text	수정일

[SAMPLE]

[KAKAOI 응답결과]

{
  "code": "API_200",
  "message": "성공",
  "data": {
    "templateCode": "NEXUS_CALLBACK_01",
    "templateName": "콜백 응답 01",
    "templateContent": "안녕하세요  넥서스 커뮤니티 입니다.\n#{성명}님의 콜백이 정상적으로 등록 되었습니다. ",
    "templateImageName": null,
    "templateImageUrl": null,
    "securityFlag": false,
    "templateStatus": "A",
    "kepStatus": "O",
    "templateMessageType": "BA",
    "templateExtra": null,
    "templateAd": null,
    "templateTitle": null,
    "templateSubtitle": null,
    "templateEmphasizeType": "NONE",
    "categoryCode": "004002",
    "templateDormant": false,
    "templateBlock": false,
    "buttons": [
      {
        "ordering": 1.0,
        "name": "홈페이지 바로가기",
        "linkType": "WL",
        "linkMo": "https://www.nexus.co.kr"
      }
    ],
    "quickReplies": null,
    "templateItemHighlight": null,
    "templateItem": null,
    "templateComments": [
      
    ]
  }
}

[M&Wize 응답결과]

{
  "code": "200",
  "data": {
    "senderKey": "16056ed0f96cca0bdc72e88b6e96452547c10c5b",
    "senderKeyType": "S",
    "templateCode": "UBASEALIMTALK_00001",
    "templateName": "ALIMTALKUBASE_00001",
    "templateMessageType": "BA",
    "templateEmphasizeType": "NONE",
    "templateContent": "안녕하세요 유베이스 DT솔루션플랫폼팀입니다.\nUBASE IPCC 상품인 U Connect를 통한 알림톡 발송 테스트입니다.\n알림톡을 통한 시나리오봇, 상담톡 연계까지 제공드릴 예정입니다.\n감사합니다.",
    "inspectionStatus": "APR",
    "createdAt": "2021-02-15 09:24:00",
    "modifiedAt": "2023-04-17 19:10:26",
    "status": "A",
    "block": false,
    "dormant": true,
    "securityFlag": false,
    "categoryCode": "008002",
    "comments": [
      {
        "id": 1208717,
        "content": null,
        "userName": "검수자",
        "createdAt": "2021-02-15 13:52:32",
        "status": "APR",
        "attachment": [
          
        ]
      }
    ],
    "buttons": [
      
    ],
    "quickReplies": [
      
    ]
  }
}

14.6발송 결과 API

14.6.1발송 결과 조회

14.6.1.1발송 결과 조회(여러개)

polling 방식으로 전송후 발송 결과를 확인 할수 있다.
최대 30개만 가능합니다.

[Request]

SMS 결과

POST /sms/result

LMS 결과

POST /lms/result

MMS 결과

POST /mms/result

[Parameter]

키		타입	필수	설명
sender_key		text	Y	발신 프로필 키
serial_numbers		array
	serial_number	text	Y	SMS serial_number

[Response]

키		타입	설명
code		text	결과코드
data		array
	serial_number	text(39)	알림톡 발신 serial_number
	result_status	text(4)	메시지 상태 코드(SS: 성공, SF:실패, EF:요청실패, EW: 발송중)
	result_at	text(19)	결과를 응답한 시간
	result_message	text	결과 메시지(오류시 존재하는 값)

[Example]

curl  -H "Accept: application/json" -H "Content-type: application/json" \
-X POST -d \
 '{"sender_key":"940e873beb5fa749065277ca73b5485536e41548", "serial_numbers":[{"serial_number":"20210826-0009-61275F70"} , {"serial_number":"20210826-0000-6127420B"} ] }' \
  http://127.0.0.1:8080/sms/result

[Example(response)]

{
  "code": "200",
  "data": [
    { 
       "serial_number": "SMS-0001-61D54026", 
       "result_status": "EE" 
    }, 
    { 
     "serial_number": "SMS-0003-61D545DE", 
      "result_status": "SS", 
       "result_at": "20220105161710", 
       "result_message": "성공" 
     }
  ]
}

14.6.2발송 리스트 조회

14.6.2.1발송 리스트 조회(Kakao i 만)

다음은 메시지 발송 결과의 상태 리스트를 상세하게 조회할 수 있는 API 기능에 대한 설명입니다.
최대 1000개 조회만 가능합니다.
마지막 리스트의 uid 를 이용해 다음을 조회 할수 있습니다.

[Request]

POST /message/list

[Parameter]

키	타입	필수	설명
start_date	text	Y	검색 시작일 yyyy-MM-dd
end_date	text	Y	검색 종료일 yyyy-MM-dd
client_id	text	N	발송 고객사 ID
size	int32	Y	페이지 당 리스트 수 (Max 1000)
last_uid	text	N	조회한 페이지 리스트의 마지막 uid - 다음 페이지 조회시 필수
status_code	text	N	메시지 상태 코드 - 상세 정보는 Kakao i BizMessage API 메시지 상태 코드를 참고하십시오.

[Response]

키		타입	설명
status		text	응답상태코드
code		text	응답코드
count		int64	결과정보조회시리스트수
next		Boolean	페이지 조회시 다음 페이지 여부
last_uid		text	조회한 페이지 리스트의 마지막 uid
code_detail		object	메시지상태상세코드
	detail_code		상세 코드
	detail_message		상세 메시지
results		array	메시지 결과 조회 리스트
	uid	text	메시지의 Key ID
	cid	text	사용자 정의 Key Id
	reg_date	text	메시지 등록일
	status_code	text	메시지 상태 코드
	kko_status_code	text	카카오톡에서 전송되는 처리 결과 코드
	sms_status_code	text	SMS 처리 결과 코드
	error_message	text	에러 메시지 (오류시 존재하는 값)

[Example]

curl  -H "Accept: application/json" -H "Content-type: application/json" \
-X POST -d \
 '{"start_date":"2023-06-01", "end_date":"2023-06-02" , "size":100}' \
  http://127.0.0.1:8080/messege/list

[Example(response)]

{
  "status": "200",
  "code": "200",
  "count": 5,
  "next": true,
  "last_uid": "230601092948607W6g0URQgTS+1jEK",
  "code_detail": {
    "detail_code": "",
    "detail_message": "성공"
  },
  "results": [
    {
      "uid": "2306010926278538kaS2wmjSC2CGNR",
      "reg_date": "2023-06-01T09:26:28",
      "status_code": "API_200",
      "error_message": "NoSendAvailableException(20230601-2306010926278538kaS2wmjSC2CGNR)",
      "kko_status_code": "3018",
      "sms_status_code": "-100",
      "cid": "SMS-0133-6477E5B3"
    },
    {
      "uid": "230601092653251w8TaB4cFR4+AhN2",
      "reg_date": "2023-06-01T09:26:53",
      "status_code": "API_200",
      "error_message": "NoSendAvailableException(20230601-230601092653251w8TaB4cFR4+AhN2)",
      "kko_status_code": "3018",
      "sms_status_code": "-100",
      "cid": "SMS-0134-6477E5CD"
    },
    {
      "uid": "230601092730969x4LGbem+Sqes88m",
      "reg_date": "2023-06-01T09:27:31",
      "status_code": "API_200",
      "error_message": "NoSendAvailableException(20230601-230601092730969x4LGbem+Sqes88m)",
      "kko_status_code": "3018",
      "sms_status_code": "-100",
      "cid": "SMS-0135-6477E5F2"
    },
    {
      "uid": "230601092814528DDl+INBTQaWfGI8",
      "reg_date": "2023-06-01T09:28:15",
      "status_code": "API_200",
      "error_message": "NoSendAvailableException(20230601-230601092814528DDl+INBTQaWfGI8)",
      "kko_status_code": "3018",
      "sms_status_code": "-100",
      "cid": "SMS-0136-6477E61E"
    },
    {
      "uid": "230601092948607W6g0URQgTS+1jEK",
      "reg_date": "2023-06-01T09:29:49",
      "status_code": "API_200",
      "error_message": "NoSendAvailableException(20230601-230601092948607W6g0URQgTS+1jEK)",
      "kko_status_code": "3018",
      "sms_status_code": "-100",
      "cid": "SMS-0137-6477E67C"
    }
  ]
}

14.7FNU 테이블 생성

14.7.1FNU 테이블 생성

FUN SMS 발송을 위한 테이블 생성
TBL_SUBMIT_QUEUE_{AGENTID} 형식으로 생성

[Request]

SMS 결과

POST /sms/fun/table

[Parameter]

키	타입	필수	설명
sender_key	text(4)	Y	발신 프로필 키 (AGENT ID)

[Response]

키		타입	설명
code		text	결과코드(200:성공, 나머지 실패)
message		text	결과 메시지

[Example]

curl  -H "Accept: application/json" -H "Content-type: application/json" \
-X POST -d \
 '{"sender_key":"1111"}' \
  http://127.0.0.1:8447/sms/fnu/table

[Example(response)]

{
  "code": "200",
  "messeage": "OK"
}

14.7.2코드 정의

업체	code	설명
공통	SS	문자 발송 성공
공통	SF	문자 발송 실패
공통	EW	발송중
공통	EF	시스템 실패처리(공백, 크기 초과, 고객사 검증등)
공통	EE	시스템 오류(첨부 파일 오류 등)
공통	EO	시스템 타임아웃

14.Biz SMS APIBiz SMS API