메시지 발송

SMS/LMS/MMS 메시지를 발송합니다. From 번호는 계정에 등록된 번호여야 합니다.

KCT 통합메시징 Agent를 통해 실제 발송되며, 발송 결과는 webhook으로 비동기 수신합니다.

메시지 타입별 사용법

SMS (단문, EUC-KR 90byte 이하 = 한글 45자):

1 { "To": "010...", "From": "070...", "Body": "안녕하세요" }

통신사 SMS 상한은 EUC-KR 90byte 입니다. 이를 넘겨 Type: "sms" 로 보내면 400 body_too_long 입니다. Type 을 생략하면 긴 본문은 LMS 로 자동 발송되므로, 길이가 런타임에 정해지는 경우(템플릿 치환 등)에는 생략하시는 편이 안전합니다.

LMS (장문, 2000자 이하, 첨부 없음):

1 { "To": "010...", "From": "070...", "Body": "긴 내용...", "Type": "lms", "Subject": "제목" }

MMS (이미지 첨부, 최대 3개):

1 { "To": "010...", "From": "070...", "Body": "사진", "Type": "mms", "MediaUrl": ["https://example.com/photo.jpg"] }

알림톡 (Kakao 를 실으면 알림톡입니다 — Type 은 생략하십시오):

1 {
2   "To": "010...", "From": "070...",
3   "Kakao": {
4     "ChannelId": "clx9kak0001", "TemplateId": "clx9tpl0001",
5     "Variables": { "고객명": "홍길동", "#{금액}": "12,000" }
6   },
7   "Fallback": { "Body": "주문이 접수되었습니다." }
8 }

알림톡은 승인된 템플릿으로만 보낼 수 있고, 본문·버튼·아이템 리스트는 템플릿에 검수된 그대로 발송됩니다. 요청에서 바꿀 수 있는 것은 Variables 뿐입니다 — 본문의 #{변수} 는 물론 버튼 링크와 강조 문구에 들어간 변수도 같은 목록으로 채워집니다.

발송에 실패하면(수신자가 카카오톡을 쓰지 않는 등) Fallback 문구가 문자로 대신 나갑니다. 이때 문자는 별도의 메시지 1건으로 기록되고 문자 단가로 청구됩니다.

SMS/LMS/MMS 메시지를 발송합니다. From 번호는 계정에 등록된 번호여야 합니다. KCT 통합메시징 Agent를 통해 실제 발송되며, 발송 결과는 webhook으로 비동기 수신합니다. ### 메시지 타입별 사용법 **SMS** (단문, EUC-KR 90byte 이하 = 한글 45자): ```json { "To": "010...", "From": "070...", "Body": "안녕하세요" } ``` 통신사 SMS 상한은 **EUC-KR 90byte** 입니다. 이를 넘겨 `Type: "sms"` 로 보내면 `400 body_too_long` 입니다. **`Type` 을 생략하면 긴 본문은 LMS 로 자동 발송**되므로, 길이가 런타임에 정해지는 경우(템플릿 치환 등)에는 생략하시는 편이 안전합니다. **LMS** (장문, 2000자 이하, 첨부 없음): ```json { "To": "010...", "From": "070...", "Body": "긴 내용...", "Type": "lms", "Subject": "제목" } ``` **MMS** (이미지 첨부, 최대 3개): ```json { "To": "010...", "From": "070...", "Body": "사진", "Type": "mms", "MediaUrl": ["https://example.com/photo.jpg"] } ``` **알림톡** (`Kakao` 를 실으면 알림톡입니다 — `Type` 은 생략하십시오): ```json { "To": "010...", "From": "070...", "Kakao": { "ChannelId": "clx9kak0001", "TemplateId": "clx9tpl0001", "Variables": { "고객명": "홍길동", "#{금액}": "12,000" } }, "Fallback": { "Body": "주문이 접수되었습니다." } } ``` 알림톡은 **승인된 템플릿으로만** 보낼 수 있고, 본문·버튼·아이템 리스트는 템플릿에 검수된 그대로 발송됩니다. 요청에서 바꿀 수 있는 것은 `Variables` 뿐입니다 — 본문의 `#{변수}` 는 물론 **버튼 링크와 강조 문구에 들어간 변수도 같은 목록으로 채워집니다.** 발송에 실패하면(수신자가 카카오톡을 쓰지 않는 등) `Fallback` 문구가 문자로 대신 나갑니다. 이때 문자는 **별도의 메시지 1건**으로 기록되고 문자 단가로 청구됩니다.

Authentication

AuthorizationBearer

API Key를 Bearer 토큰으로 전달

Path parameters

accountIdstringRequired

계정 ID

Request

This endpoint expects an object.

TostringRequired

수신 번호. 국내 표기(010-1234-5678·01012345678)와 +82 E.164 를 모두 받아 국내 표기로 정규화해 저장합니다. 국내 이동전화·지역번호·050X 안심번호·대표번호 (1[5-9]XX-XXXX)만 지원하며, 그 밖의 값(앞 0 이 빠진 1012345678, + 없는 8210…, 폐지된 015·018 등)은 400 invalid_phone 입니다.

수신 번호. 국내 표기(`010-1234-5678`·`01012345678`)와 `+82` E.164 를 모두 받아 국내 표기로 정규화해 저장합니다. 국내 이동전화·지역번호·050X 안심번호·대표번호 (`1[5-9]XX-XXXX`)만 지원하며, 그 밖의 값(앞 0 이 빠진 `1012345678`, `+` 없는 `8210…`, 폐지된 015·018 등)은 `400 invalid_phone` 입니다.

FromstringRequired

발신 번호 (계정에 등록된 번호)

BodystringOptional

메시지 본문. 문자에는 필수입니다.

알림톡에는 넣을 수 없습니다(400 kakao_body_not_allowed) — 본문은 템플릿이 정합니다. 대신 Kakao.Variables 를 채우십시오. 응답의 body 에는 변수를 치환한 결과가 담깁니다.

메시지 본문. 문자에는 필수입니다. **알림톡에는 넣을 수 없습니다**(`400 kakao_body_not_allowed`) — 본문은 템플릿이 정합니다. 대신 `Kakao.Variables` 를 채우십시오. 응답의 `body` 에는 변수를 치환한 결과가 담깁니다.

TypeenumOptional

메시지 유형. 생략하면 실린 항목에 맞춰 자동으로 고릅니다 — Kakao 가 있으면 ata, MediaUrl 이 있으면 mms, Subject 가 있거나 본문이 EUC-KR 90byte(한글 45자)를 넘으면 lms, 그 외에는 sms 입니다.

명시하면 그대로 따릅니다. sms 로 명시한 본문이 90byte 를 넘으면 400 body_too_long 입니다 — 잘린 채로 발송되지 않도록 막습니다.

ata 와 Kakao 는 서로를 요구합니다. Type: "ata" 인데 Kakao 가 없거나, Kakao 를 실으면서 다른 Type 을 명시하면 400 입니다.

메시지 유형. **생략하면 실린 항목에 맞춰 자동으로 고릅니다** — `Kakao` 가 있으면 `ata`, `MediaUrl` 이 있으면 `mms`, `Subject` 가 있거나 본문이 EUC-KR 90byte(한글 45자)를 넘으면 `lms`, 그 외에는 `sms` 입니다. 명시하면 그대로 따릅니다. `sms` 로 명시한 본문이 90byte 를 넘으면 `400 body_too_long` 입니다 — 잘린 채로 발송되지 않도록 막습니다. `ata` 와 `Kakao` 는 **서로를 요구합니다.** `Type: "ata"` 인데 `Kakao` 가 없거나, `Kakao` 를 실으면서 다른 `Type` 을 명시하면 `400` 입니다.

Allowed values:

SubjectstringOptional

메시지 제목 (LMS/MMS에서 사용)

MediaUrllist of stringsOptional

MMS 첨부 이미지 URL (최대 3개). jpg, jpeg, png, bmp만 지원. 장당 300KB 이하.

Type이 sms일 때는 사용 불가
Type이 mms이고 MediaUrl이 없으면 LMS로 전송
Type이 mms이고 MediaUrl이 있으면 MMS로 전송

MMS 첨부 이미지 URL (최대 3개). jpg, jpeg, png, bmp만 지원. 장당 300KB 이하. - Type이 sms일 때는 사용 불가 - Type이 mms이고 MediaUrl이 없으면 LMS로 전송 - Type이 mms이고 MediaUrl이 있으면 MMS로 전송

IdempotencyKeystringOptional1-255 characters

발송 멱등키. 같은 계정에서 같은 키로 다시 요청하면 발송하지 않고 1회차 결과를 그대로 돌려줍니다. 재시도·재실행 경로가 있는 호출자만 채우십시오.

미지정이면 매번 발송합니다(기존 동작). 빈 문자열은 400 입니다 — 템플릿에서 빈 값이 들어가 멱등이 조용히 꺼진 채 중복 발송되는 걸 막습니다.

⚠️ 순차 재시도를 막는 용도입니다. 같은 키로 동시에 두 요청이 들어오면 둘 다 발송될 수 있습니다.

⚠️ 본문이 달라도 검사하지 않습니다. 같은 키로 다른 To/Body 를 보내면 새 메시지는 발송되지 않고 1회차 결과가 201 로 돌아옵니다. 키는 메시지 한 건 단위로 만드십시오(order-1024-접수·order-1024-배송 처럼). 만료도 없습니다 — 한 번 쓴 키는 계정 안에서 영구히 같은 결과를 돌려줍니다.

발송 멱등키. 같은 계정에서 같은 키로 다시 요청하면 **발송하지 않고** 1회차 결과를 그대로 돌려줍니다. 재시도·재실행 경로가 있는 호출자만 채우십시오. 미지정이면 매번 발송합니다(기존 동작). 빈 문자열은 `400` 입니다 — 템플릿에서 빈 값이 들어가 멱등이 조용히 꺼진 채 중복 발송되는 걸 막습니다. ⚠️ 순차 재시도를 막는 용도입니다. 같은 키로 **동시에** 두 요청이 들어오면 둘 다 발송될 수 있습니다. ⚠️ **본문이 달라도 검사하지 않습니다.** 같은 키로 다른 To/Body 를 보내면 새 메시지는 발송되지 않고 1회차 결과가 `201` 로 돌아옵니다. 키는 *메시지 한 건* 단위로 만드십시오(`order-1024-접수`·`order-1024-배송` 처럼). 만료도 없습니다 — 한 번 쓴 키는 계정 안에서 영구히 같은 결과를 돌려줍니다.

KakaoobjectOptional

카카오 알림톡으로 보냅니다. 이 항목이 있으면 알림톡입니다 — Type 은 생략하십시오.

발신 채널과 템플릿은 콘솔의 「카카오톡 채널」·「알림톡 템플릿」에서 연결·승인한 것이어야 합니다. 승인되지 않았거나 휴면 상태인 템플릿은 422 입니다.

카카오 알림톡으로 보냅니다. **이 항목이 있으면 알림톡입니다** — `Type` 은 생략하십시오. 발신 채널과 템플릿은 콘솔의 「카카오톡 채널」·「알림톡 템플릿」에서 연결·승인한 것이어야 합니다. 승인되지 않았거나 휴면 상태인 템플릿은 `422` 입니다.

FallbackobjectOptional

알림톡이 발송 실패했을 때 대신 나갈 문자. 생략하면 템플릿 본문을 그대로 문자로 보냅니다.

대체 발송된 문자는 별도의 메시지 1건으로 기록되며 문자 단가로 청구됩니다.

Response

발송 요청 성공

messageIdstringOptional

statusenumOptional

typeenumOptional

ata 는 카카오 알림톡입니다. 본문(body)은 템플릿에 변수를 치환한 결과이며, 버튼·아이템 리스트·강조 문구는 템플릿에 검수된 대로 발송되어 이 값에는 담기지 않습니다.

subjectstring or nullOptional

메시지 제목 (LMS/MMS)

tostringOptional

fromstringOptional

bodystring or nullOptional

numMediaintegerOptional

첨부 이미지 수

mediaUrllist of stringsOptional

첨부 이미지 URL 목록

directionenumOptional

accountIdstringOptional

dateCreateddatetimeOptional

dateUpdateddatetime or nullOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

422

Unprocessable Entity Error