XMS

XMS는 SMS, LMS, MMS, ISM(국제 SMS), ILM(국제 LMS) 메시지를 사용자에게 발송할 수 있습니다.

안내

모든 BizMessage API를 호출하기 전, OAuth 2.0 인증 API를 선제적으로 호출해야 합니다.

API 기능별 예제는 Sample Code 문서를 참고하시기 바랍니다.

주의
스테이징 서버는 카카오 운영 서버와 연동되어 있어 실제 메시지가 발송되므로, 메시지 오발송에 주의하시기 바랍니다.

XMS 발송

XMS를 발송하는 API는 다음과 같습니다.

Request

Request Syntax

코드예제XMS 발송 Request Syntax

BASH

curl -X POST "https://{base_url}/v2/send/xms" \
-H  "accept: */*" \
-H  "authorization: Bearer {oauthToken}" \
-H  "Content-Type: application/json" \
-d  '{
		  "cid": "202210181600001",
		  "message_type": "SM",
		  "phone_number": "01000000000",
		  "message": " 메시지",
		  "sender_no": "15000000",
		  "title": " 타이틀"
		}'

표API 호출 방식

메서드	요청 URL
POST	`https://{base_url}/v2/send/xms`

표XMS 발송 Path Parameter

파라미터	유형	필수 여부	대분류	구분	설명
base_url	String	`필수`	운영	일반	`bizmsg-web.kakaoenterprise.com`
				금융권	`bizmsg-bank.kakaoenterprise.com`
				증권	`bizmsg-stock.kakaoenterprise.com`
				공공 기관	`bizmsg-gov.kakaoenterprise.com`
			스테이징	일반	`stg-user.bizmsg.kakaoenterprise.com`
				금융권	`stg-bizmsg-bank.kakaoenterprise.com`
				증권	`stg-bizmsg-stock.kakaoenterprise.com`
				공공 기관	`stg-bizmsg-gov.kakaoenterprise.com`

Request Header

표XMS 발송 Request Header

파라미터	타입	필수 여부	설명
accept	String	`필수`	`/`로 고정
authorization	String	`필수`	`Bearer {oauthToken}` - `{oauthToken}`: OAuth 2.0 인증 API로 발급받은 액세스 토큰
Content-Type	String	`필수`	`application/json`로 고정

Request Elements

표XMS 발송 Request Elements

프로퍼티	타입	필수 여부	설명
client_id	String	`선택`	고객사 ID
cid	String	`필수`	고객사 정의 Key ID
message_type	String	`필수`	메시지 타입 - text(3)
			`SM`: SMS
			`LM`: LMS
			`MM`: MMS
			`ISM`: 국제 SMS
			`ILM`: 국제 LMS
phone_number	String	`필수`	수신자 전화번호(국가코드(`82`)를 포함) - text(16)
nat_cd	String	`선택`	국제 발송 시 국가코드 - text(10)
message	String	`필수`	수신자에게 전달할 XMS 메시지 - text(2000)
sender_no	String	`필수`	고객사 전화번호 - text(16)
title	String	`선택`	LMS, MMS 전송 시 타이틀 - text(60)
content_group_id	String	`선택`	[MMS] 전송 파일 그룹 ID - MMS 이미지 업로드 API의 응답 결과 값 - MMS 발송 시에만 필요한 값으로 데이터가 있을 경우만 사용
biz_no	String	`선택`	최초 발신자 식별 코드 (재판사용)
tax_cd1	String	`선택`	정산 코드1 - 고객사가 정산을 위해 정의하여 사용하는 변수 - text(50)
tax_cd2	String	`선택`	정산 코드2 - 고객사가 정산을 위해 정의하여 사용하는 변수 - text(50)

Response

Response Syntax

코드예제XMS 발송 Response Syntax

JSON

{
  "code": "200",
  "uid": "221018080314511j7usTgzgQDOXvIk",
  "cid": "202210181600001",
  "result": {
    "detail_code": "NRM0000",
    "detail_message": "성공"
  }
}

Response Elements

표XMS 발송 Response Elements

프로퍼티	타입	필수 여부	설명
code	String	`필수`	메시지 발송 결과 코드
			`100`: 발송 진행 중(처리 중)
			`200`: 성공
			`400`: 권한 오류
			`410`: 입력값이 유효하지 않음
			`420`: 파일/이미지 관련 오류
			`500`: 내부 시스템 오류
			`510`: 발송 실패
			`520`: 실패되었으나 재발송 가능
uid	String	`선택`	메시지 Key ID
cid	String	`선택`	고객사 정의 Key ID
	Object	`선택`	세부 결과 정보(참고용)
detail_code	String	`선택`	세부 결과 코드(참고용)
detail_message	String	`선택`	세부 결과 메시지(참고용)

MMS 파일 업로드

다음은 MMS 발송 시 첨부할 파일을 업로드하기 위한 API 기능에 대한 설명입니다.

Request

Request Syntax

코드예제MMS 파일 업로드 Request Syntax

BASH

curl -X 'POST' \
  'https://{base_url}/v2/upload/message/mms/files' \
  -H 'accept: */*' \
  -H 'Authorization: {oauthToken}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'images=@test_img.jpg;type=image/jpeg'

표API 호출 방식

메서드	요청 URL
POST	`https://{base_url}/v2/upload/message/mms/files`

표MMS 파일 업로드 Path Parameter

파라미터	유형	필수 여부	대분류	구분	설명
base_url	String	`필수`	운영	일반	`bizmsg-web.kakaoenterprise.com`
				금융권	`bizmsg-bank.kakaoenterprise.com`
				증권	`bizmsg-stock.kakaoenterprise.com`
				공공 기관	`bizmsg-gov.kakaoenterprise.com`
			스테이징	일반	`stg-user.bizmsg.kakaoenterprise.com`
				금융권	`stg-bizmsg-bank.kakaoenterprise.com`
				증권	`stg-bizmsg-stock.kakaoenterprise.com`
				공공 기관	`stg-bizmsg-gov.kakaoenterprise.com`

Request Header

표MMS 파일 업로드 Request Header

파라미터	타입	필수 여부	설명
accept	String	`필수`	`/`로 고정
authorization	String	`필수`	`Bearer {oauthToken}` - `{oauthToken}`: OAuth 2.0 인증 API로 발급받은 액세스 토큰
Content-Type	String	`필수`	`multipart/form-data`로 고정

Request Elements

표MMS 파일 업로드 Request Elements

프로퍼티	타입	필수 여부	설명
files	List	`필수`	MMS 파일 정보로 다음의 사양을 충족해야 함 - 파일 수: 최대 3개 - 파일 형식:`jpg` - 파일 크기: 총합 최대 200KB

Response

Response Syntax

코드예제MMS 파일 업로드 Response Syntax

JSON

{
  "code": "200",
  "result": {
    "detail_code": "NRM00000",
    "detail_message": "성공"
  },
  "content_group_id": "20221018-16522115ca"
}

Response Elements

표MMS 파일 업로드 Response Elements

프로퍼티	타입	필수 여부	설명
code	String	`필수`	메시지 발송 결과 코드
			`100`: 발송 진행 중(처리 중)
			`200`: 성공
			`400`: 권한 오류
			`410`: 입력값이 유효하지 않음
			`420`: 파일/이미지 관련 오류
			`500`: 내부 시스템 오류
			`510`: 발송 실패
			`520`: 실패되었으나 재발송 가능
	Object	`선택`	세부 결과 정보(참고용)
detail_code	String	`선택`	세부 결과 코드(참고용)
detail_message	String	`선택`	세부 결과 코드(참고용)
content_group_id	String	`선택`	업로드된 파일 List Group ID - MMS 메시지 발송 전송 시 파라미터에 입력

XMS 발송 리스트 조회

XMS 발송 리스트를 조회하는 API는 다음과 같습니다.

Request

Request Syntax

코드예제XMS 발송 리스트 조회 Request Syntax

BASH

curl -X 'POST' \
  'https://{base_url}/v2/info/message/search' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {oauthToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "start_date": "2022-10-18",
  "end_date": "2022-10-18",
  "size": 1000
}'

표API 호출 방식

메서드	요청 URL
POST	`https://{base_url}/v2/info/message/search`

표XMS 발송 리스트 조회 Path Parameter

파라미터	유형	필수 여부	대분류	구분	설명
base_url	String	`필수`	운영	일반	`bizmsg-web.kakaoenterprise.com`
				금융권	`bizmsg-bank.kakaoenterprise.com`
				증권	`bizmsg-stock.kakaoenterprise.com`
				공공 기관	`bizmsg-gov.kakaoenterprise.com`
			스테이징	일반	`stg-user.bizmsg.kakaoenterprise.com`
				금융권	`stg-bizmsg-bank.kakaoenterprise.com`
				증권	`stg-bizmsg-stock.kakaoenterprise.com`
				공공 기관	`stg-bizmsg-gov.kakaoenterprise.com`

Request Header

표XMS 발송 리스트 조회 Request Header

파라미터	타입	필수 여부	설명
accept	String	`필수`	`/`로 고정
Authorization	String	`필수`	`Bearer {oauthToken}` - `{oauthToken}`: OAuth 2.0 인증 API로 발급받은 액세스 토큰
Content-Type	String	`필수`	`application/json`로 고정

Request Elements

표XMS 발송 리스트 조회 Request Elements

프로퍼티	타입	필수 여부	설명
start_date	String	`선택`	검색 시작일 - 형식: `yyyy-mm-dd`(date) - 시작일 입력 시 종료일도 필수 입력, 입력값이 없을 경우 당일 데이터를 검색
end_date	String	`선택`	검색 종료일 - 형식: `yyyy-mm-dd`(date) - 종료일 입력 시 시작일도 필수 입력, 입력값이 없을 경우 당일 데이터를 검색
client_id	String	`선택`	발송 고객사 ID
size	Integer	`선택`	페이지 당 리스트 수 - 최댓값: 1000 - int32
last_uid	String	`선택`	조회한 페이지 리스트의 마지막 메시지 Key ID - 다음 페이지 조회 시 필수
etc1	String	`선택`	고객사 정의 값 1 - text(50)
etc2	String	`선택`	고객사 정의 값 2 - text(50)
status_code	String	`선택`	메시지 상태 코드 - 상세 정보는 API 메시지 상태 코드 참고

Response

Response Syntax

코드예제XMS 발송 리스트 조회 Response Syntax

JSON

{
  "status": "200",
  "code": "200",
  "count": 4,
  "next": false,
  "code_detail": {
    "detail_code": "NRM00000",
    "detail_message": "성공"
  },
  "results": [
    {
      "uid": "221018080314511j7usTgzgQDOXvIk",
      "reg_date": "2022-10-18T08:03:15",
      "status_code": "API_200",
      "kko_status_code": "0000",
      "cid": "11329b64174a4738b049e2a74e93c5c1"
    }
  ]
}

Response Elements

표XMS 발송 리스트 조회 Response Elements

프로퍼티	타입	필수 여부	설명
status	String	`필수`	메시지 발송 결과 코드
			`100`: 발송 진행 중(처리 중)
			`200`: 성공
			`400`: 권한 오류
			`410`: 입력값이 유효하지 않음
			`420`: 파일/이미지 관련 오류
			`500`: 내부 시스템 오류
			`510`: 발송 실패
			`520`: 실패되었으나 재발송 가능
code	String	`선택`	응답 상태 코드
count	Integer	`선택`	결과 정보 조회 시 리스트 수 - int64
next	Boolean	`선택`	페이지 조회 시 다음 페이지 여부
last_uid	String	`선택`	조회한 페이지 리스트의 마지막 메시지 Key ID
	Object	`선택`	메시지 상태 상세 코드
detail_code	String	`선택`	상세 코드
detail_message	String	`선택`	상세 메시지
	Array	`선택`	메시지 결과 조회 리스트
uid	String	`선택`	메시지의 Key ID
cid	String	`선택`	고객사 정의 Key ID
reg_date	String	`선택`	메시지 등록일
status_code	String	`선택`	메시지 상태 코드 - 상세 정보는 API 메시지 상태 코드 참고
kko_status_code	String	`선택`	카카오톡에서 전송되는 처리 결과 코드
sms_status_code	String	`선택`	SMS 처리 결과 코드
error_message	String	`선택`	에러 메시지 (오류 시 존재하는 값)
tax_cd1	String	`선택`	정산 코드1 - 고객사가 정산을 위해 정의하여 사용할 수 있는 변수 - text(50)
tax_cd2	String	`선택`	정산 코드1 - 고객사가 정산을 위해 정의하여 사용할 수 있는 변수 - text(50)
etc1	String	`선택`	고객사 정의 Value1 - 고객사가 정의하여 사용하는 변수 - text(50)
etc2	String	`선택`	고객사 정의 Value 2 - 고객사가 정의하여 사용하는 변수 - text(50)
etc3	String	`선택`	고객사 정의 Value 3 - 고객사가 정의하여 사용하는 변수 - text(50)
etc4	String	`선택`	고객사 정의 Value 4 - 고객사가 정의하여 사용하는 변수 - text(50)
etc5	String	`선택`	고객사 정의 Value 5 - 고객사가 정의하여 사용하는 변수 - text(50)
etc6	String	`선택`	고객사 정의 Value 6 - 고객사가 정의하여 사용하는 변수 - text(50)
etc7	String	`선택`	고객사 정의 Value 7 - 고객사가 정의하여 사용하는 변수 - text(50)
etc8	String	`선택`	고객사 정의 Value 8 - 고객사가 정의하여 사용하는 변수 - text(50)
etc9	String	`선택`	고객사 정의 Value 9 - 고객사가 정의하여 사용하는 변수 - text(50)
etc10	String	`선택`	고객사 정의 Value 10 - 고객사가 정의하여 사용하는 변수 - text(50)

XMS 발송 리스트 상세 조회

메시지 발송 결과를 상세하게 조회할 수 있는 API 기능에 대한 설명입니다.

Request

Request Syntax

코드예제XMS 발송 리스트 상세 조회 Request Syntax

BASH

curl -X 'GET' \
  'https://{base_url}/v2/info/message/search/detail/{uid}' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {oauthToken}'

표API 호출 방식

메서드	요청 URL
GET	`https://{base_url}/v2/info/message/search/detail/{uid}`

표XMS 발송 리스트 상세 조회 Path Parameter

파라미터	유형	필수 여부	대분류	구분	설명
base_url	String	`필수`	운영	일반	`bizmsg-web.kakaoenterprise.com`
				금융권	`bizmsg-bank.kakaoenterprise.com`
				증권	`bizmsg-stock.kakaoenterprise.com`
				공공 기관	`bizmsg-gov.kakaoenterprise.com`
			스테이징	일반	`stg-user.bizmsg.kakaoenterprise.com`
				금융권	`stg-bizmsg-bank.kakaoenterprise.com`
				증권	`stg-bizmsg-stock.kakaoenterprise.com`
				공공 기관	`stg-bizmsg-gov.kakaoenterprise.com`
uid	String	`필수`			메시지 Key ID - ex. `21018173501346cxU7zEswSYSsTmS`

Request Header

표XMS 발송 리스트 상세 조회 Request Header

파라미터	타입	필수 여부	설명
accept	String	`필수`	`/`로 고정
Authorization	String	`필수`	`Bearer {oauthToken}` - `{oauthToken}`: OAuth 2.0 인증 API로 발급받은 액세스 토큰

Response

Response Syntax

코드예제XMS 발송 리스트 상세 조회 Response Syntax

JSON

{
  "code": "200",
  "code_detail": {
    "detail_code": "NRM00000",
    "detail_message": "성공"
  },
  "result": {
    "uid": "221018080314511j7usTgzgQDOXvIk",
    "reg_date": "2022-10-18T08:03:15",
    "message_type": "AT",
    "status_code": "API_200",
    "phone_number": "01000000000",
    "template_code": "test_kep_template_005",
    "req_date": "2022-10-18T08:03:14",
    "req_sms_yn": "N",
    "kko_status_code": "0000",
    "message": " 메시지",
    "cid": "11329b64174a4738b049e2a74e93c5c1"
  }
}

Response Elements

표XMS 발송 리스트 상세 조회 Reponse Elements

프로퍼티	타입	필수 여부	설명
code	String	`필수`	메시지 발송 결과 코드
			`100`: 발송 진행 중(처리 중)
			`200`: 성공
			`400`: 권한 오류
			`410`: 입력값이 유효하지 않음
			`420`: 파일/이미지 관련 오류
			`500`: 내부 시스템 오류
			`510`: 발송 실패
			`520`: 실패되었으나 재발송 가능
	Object	`선택`	메시지 상태 상세 코드
detail_code	String	`선택`	상세 코드
detail_message	String	`선택`	상세 메시지
	Object	`선택`	단일 메시지의 발송 결과 상세 조회
uid	String	`선택`	메시지의 Key ID
reg_date	String	`선택`	메시지 등록일(date)
message_type	String	`선택`	메시지 타입
			`AT`: 알림톡
			`AI`: 알림톡 이미지
			`FT`: 친구톡
			`FI`: 친구톡 이미지
			`FW`: 친구톡 와이드 이미지
			`SM`: SMS
			`LM`: LMS
			`MM`: MMS
			`ISM`: 국제 SMS
status_code	String	`선택`	메시지 상태 코드 - 상세 정보는 API 메시지 상태 코드 참고
phone_number	String	`선택`	수신자 전화번호(국가코드(`82`) 포함) - text(16)
template_code	String	`선택`	실제 발송할 메시지 유형으로 등록된 템플릿의 코드 - text(30)
req_date	String	`선택`	발송 요청일(결과 존재 시 존재하는 값)(date)
error_message	String	`선택`	에러 메시지(오류 시 존재)
req_sms_yn	String	`선택`	SMS 발송 요청 여부
req_sms_date	String	`선택`	SMS 발송 요청일(date-time)
sender_no	String	`선택`	고객사 발신 전화번호 - text(16)
sms_type	String	`선택`	대체발송 시 메시지 타입 - text(2)
			`SM`: SMS로 대체 발송
			`LM`: LMS로 대체 발송
			`MM`: MMS로 대체 발송
kko_status_code	String	`선택`	카카오톡에서 전송되는 처리 결과 코드
sms_status_code	String	`선택`	SMS 처리 결과 코드
message	String	`선택`	수신자에게 전달될 Kakao 메시지 - text(1000)
sms_message	String	`선택`	전달할 SMS 메시지 - text(4000)
title	String	`선택`	LMS, MMS 전송 시 TITLE - text(60)
cid	String	`선택`	고객사 정의 Key ID
kko_title	String	`선택`	템플릿 내용 중 강조 표기할 핵심 정보 - text(50)
nat_cd	String	`선택`	국제 발송 시 국가 코드
content_group_id	String	`선택`	[MMS] 전송할 파일 그룹 ID contentGroupId (MMS 전송 시 필수)
header	String	`선택`	메시지 상단에 표기할 제목

kakaoIdocumentation

Kakao i Connect Message::BizMessage(KOR)::API 호출 방식::API 레퍼런스::XMS 발송

페이지 이동경로

XMS

XMS 발송

Request

Request Syntax

Request Header

Request Elements

Response

Response Syntax

Response Elements

MMS 파일 업로드

Request

Request Syntax

Request Header

Request Elements

Response

Response Syntax

Response Elements

XMS 발송 리스트 조회

Request

Request Syntax

Request Header

Request Elements

Response

Response Syntax

Response Elements

XMS 발송 리스트 상세 조회

Request

Request Syntax

Request Header

Response

Response Syntax

Response Elements