메세지 발송 결과(WebHook)

GMS의 결과값을 고객사 callback URL로 전달합니다.

WebHook API (v1) 는 2023년 12월 31일 이후 deprecated 예정입니다. 같은 기능의 WebHook API (v2) 이용을 권장합니다.

고객사 callback URL 정보는 서비스 신청 시 입력하거나 [서비스 콘솔 / 연동 정보 / Callback URL]에서 수정할 수 있습니다.

고객사 callback URL에 대한 CJ API GATEWAY의 접근을 허용해야 합니다. (IP, PORT)

WebHook API (v2)

고객사가 요청한 메시지에 대한 처리 결과를 고객사의 callback URL로 전달합니다. (API PLEX Gateway -> 고객사 URL)

고객사 server에서 webhook을 수신하지 못하였을 시 10회 재시도합니다.

GMS 메세지 결과를 고객사에 전달하는 API (v2)

POST {Callback URL}

Headers

Name	Type	Description
Content-Type*	string	application/json;charset=utf-8

200: OK 응답 반환 완료

Webhook body (API PLEX ➡ 고객사)

{
    "results": [
        {
            "messageId": "user_key1",
            "to": "8210xxxxxxxx",
            "sentAt": "2023-06-06T13:36:19.258+0900",
            "doneAt": "2023-06-06T13:36:21.902+0900",
            "smsCount": 1,
            "mccMnc": "45006",
            "mcc": "450",
            "mnc": "06",
            "billing": true,
            "status": {
                "groupId": 3,
                "groupName": "DELIVERED",
                "id": 5,
                "name": "DELIVERED_TO_HANDSET",
                "description": "Message delivered to handset"
            },
            "error": {
                "groupId": 0,
                "groupName": "OK",
                "id": 0,
                "name": "NO_ERROR",
                "description": "No Error",
                "permanent": false
            },
            "echo_to_webhook": “echo test”
        }
    ]
}

키		타입	필수	설명
results		object array	Y	발송결과에 대한 배열 (배열 형식이지만 1건씩 전송됨)
	to	string	Y	수신번호
	messageId	string	Y	메시지고유 키
	sentAt	string	Y	발송 시간 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
	doneAt	string	Y	최종 처리 시간 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
	smsCount	number	Y	메시지 본문이 분할된 수 (분할 정책)
	mccMnc	string	N	국가 코드 + 네트워크 코드 (우측 상단 ‘메뉴얼 다운로드’ 에서 코드표 확인 가능)
	mcc	string	N	mobile country code (국가 코드) (우측 상단 ‘메뉴얼 다운로드’ 에서 코드표 확인 가능)
	mnc	string	N	mobile network code (네트워크 코드) (우측 상단 ‘메뉴얼 다운로드’ 에서 코드표 확인 가능)
	billing	boolean	Y	과금 여부 (null 또는 없는 경우는 과금하지 않음)
	echo_to_webhook	string	Y	사용자가 요청 시 입력한 webhook을 받을 때 함께 받을 string
	status	object	Y	상태 정보(status 상세 참조)
	error	object	N	에러 정보(error 상세 참조)

status 상세

키	타입	필수	설명
id	number	Y	status id (메시지 결과 코드 참조)
groupId	number	N	status group id (메시지 상태 그룹 코드 참조)
groupName	string	N	status group name (메시지 상태 그룹 코드 참조)
description	string	Y	상태 메시지

error 상세

키	타입	필수	설명
id	number	N	error id (서비스 오류 코드 참조)
groupId	number	N	error group id (서비스 오류 그룹 코드 참조)
groupName	string	N	error group name (서비스 오류 그룹 코드 참조)
description	string	N	error 메시지
permanent	boolean	N	영구성 여부(true or false)

메시지 분할

• 각 통신사가 정한 기준 대로 메시지 본문이 분할 됩니다.

• 최종 이용 금액 = 분할 발송 된 건 * 건 당 가격

아래 표는 예시이며, 실제 분할 기준은 통신사 별로 다르므로 정확한 분할 개수를 알기 위해서는 webhook body의 smsCount를 참조해야 합니다.

encoding	smsCount	characters
GSM	1	160
GSM	2	306
GSM	3	459
GSM	4	612
GSM	5	765
UNICODE	1	70
UNICODE	2	134
UNICODE	3	201
UNICODE	4	268
UNICODE	5	335

대한민국의 메시지 분할

대한민국은 EUC-KR encofing을 사용하며 별도의 기준으로 분할 됩니다.

encoding	smsCount	characters
GSM	1	140
GSM	2	272
GSM	3	408
EUC-KR	1	70
EUC-KR	2	136
EUC-KR	3	204

Response body (고객사 ➡ API PLEX)

{
    "code": "100",
    "desc": "success"
}

키	타입	필수	설명
code	string	Y	webhook 수신 결과 코드 (정상 수신시 "100") 정상적으로 webhook 수신 시 응답에 code를 “100”으로 고정하여 발송
desc	string	Y	webhook 수신 결과 상세 (ex: "desc":"success")

WebHook API (v1) (deprecated on 2023.12.31)

고객사가 요청한 메시지에 대한 처리 결과를 고객사의 callback URL로 전달합니다. (API PLEX Gateway -> 고객사 URL)

GMS 메세지 결과를 고객사에 전달하는 API (v1)

POST {ClientURL}

Headers

Name	Type	Description
Content-Type*	string	application/json;charset=utf-8

200: OK 응답 반환 완료

Webhook body (API PLEX ➡ 고객사)

{
    "results": [
        {
            "messageId": "string",
            "to": "string",
            "sentAt": "string",
            "doneAt": "string",
            "smsCount": 1,
            "status": {
                "groupId": "number",
                "groupName": "string",
                "id": "number",
                "name": "string",
                "description": "string"
            },
            "error": {
                "groupId": "number",
                "groupName": "string",
                "id": "number",
                "name": "string",
                "description": "string",
                "permanent": "true/false"
            }
        }
    ]
}

키		타입	설명
results			발송결과에 대한 배열 (배열 형식이지만 1건씩 전송됨)
	to	string	메시지 수신자
	messageId	string	메시지고유 키 (발송 시 unique 하게 설정 하여 발송)
	sentAt	string	발송일자
	doneAt	string	완료일자
	smsCount	number	메시지 본문이 분할된 수 (분할 정책)
	status	object	메시지 상태(status 상세 참조)
	error	object	에러(error 상세 참조)

status 상세

키	타입	설명
id	number	status id (메시지 상태 코드 참조)
groupId	number	status group id (메시지 상태 그룹 코드 참조)
groupName	string	status group name (메시지 상태 그룹 코드 참조)
description	string	상태 메시지

error 상세

키	타입	설명
id	number	error id(서비스 오류 코드 참조)
groupId	number	error group id (서비스 오류 그룹 코드 참조)
groupName	string	error group name (서비스 오류 그룹 코드 참조)
description	string	error 메시지
permanent	boolean	영구성 (true or false)

메시지 분할

• 각 통신사가 정한 기준 대로 메시지 본문이 분할 됩니다.

• 최종 이용 금액 = 분할 발송 된 건 * 건 당 가격

아래 표는 예시이며, 실제 분할 기준은 통신사 별로 다르므로 정확한 분할 개수를 알기 위해서는 webhook body의 smsCount를 참조해야 합니다.

encoding	smsCount	characters
GSM	1	160
GSM	2	306
GSM	3	459
GSM	4	612
GSM	5	765
UNICODE	1	70
UNICODE	2	134
UNICODE	3	201
UNICODE	4	268
UNICODE	5	335

대한민국의 메시지 분할

대한민국은 EUC-KR encofing을 사용하며 별도의 기준으로 분할 됩니다.

encoding	smsCount	characters
GSM	1	140
GSM	2	272
GSM	3	408
EUC-KR	1	70
EUC-KR	2	136
EUC-KR	3	204

Response body (고객사 ➡ API PLEX)

{
    "code": "string",
    "desc": "string"
}

키	타입	필수	설명
code	string	Y	접수결과코드 (정상 수신시 "100")
desc	string	Y	접수결과코드상세 (ex: "desc":"Success")