Skip to navigation
ClawOps APIMessages

메시지 발송

View as Markdown

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

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

메시지 타입별 사용법

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

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

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

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

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

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

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

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

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

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

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

브랜드 메시지 (Brand 를 실으면 브랜드 메시지입니다 — Type 은 생략하십시오):

{
  "To": "010...", "From": "070...",
  "Brand": {
    "ChannelId": "clx9kak0001", "TemplateId": "clx9bms0001",
    "Variables": { "고객명": "홍길동" }
  }
}

카카오 브랜드 메시지는 채널을 추가한 친구에게 나가는 광고성 메시지입니다. 알림톡과 달리 검수가 없어 등록한 템플릿을 바로 쓸 수 있고, 대신 두 가지 제약이 있습니다.

  • 광고성이라 야간에 보낼 수 없습니다. 오후 8시 50분 ~ 다음 날 오전 8시(KST)는 422 kakao_brand_night_blocked 입니다. 접수 전에 막으므로 예약되지 않습니다.
  • 대체발송이 없습니다. 카카오톡을 쓰지 않는 수신자에게 문자로 대신 나가지 않습니다. Fallback 을 실으면 400 kakao_fallback_not_allowed 입니다.

Brand.TemplateId 는 브랜드 템플릿 목록 API 의 data[].id 입니다. (광고) 표기와 수신거부 안내는 카카오가 자동으로 붙이므로 본문에 넣지 마십시오.

자유형 — 템플릿 없이 말풍선을 직접 싣기

TemplateId 대신 Free 에 말풍선을 실으면 템플릿을 등록하지 않고 보냅니다. 종료된 친구톡을 대신하는 방식입니다.

{
  "To": "010...", "From": "070...",
  "Brand": {
    "ChannelId": "clx9kak0001",
    "Free": {
      "chatBubbleType": "TEXT",
      "content": "이번 주 신메뉴가 나왔어요.",
      "buttons": [{ "name": "메뉴 보기", "linkType": "WL", "linkMobile": "https://example.com" }]
    }
  }
}

TemplateId 와 Free 는 정확히 하나만 실어야 합니다. 둘 다 실으면 어느 쪽으로 나갈지 정해 드릴 수 없고, 둘 다 없으면 보낼 말풍선이 없습니다 — 400 invalid_input.

  • 변수를 쓸 수 없습니다. 값을 채워 줄 템플릿이 없어서 #{이름} 이 치환되지 않은 채 그대로 발송됩니다. 그래서 Free 안에 #{…} 가 있으면 400 으로 막습니다. 값을 채우려면 템플릿을 등록해 TemplateId 로 보내십시오.
  • 말풍선 규격은 유형(chatBubbleType)이 정합니다. TEXT 는 본문만, IMAGE· WIDE·COMMERCE 는 이미지가 필요하고, CAROUSEL_FEED·CAROUSEL_COMMERCE 는 카드를 2~6장 싣습니다. 어긋나면 무엇이 잘못됐는지 400 본문이 알려 줍니다.
  • 이미지가 필요한 유형은 POST /v1/accounts/{accountId}/kakao/brand-images 로 먼저 올리고 받은 id 를 imageId 에 넣습니다. 한 번 올린 이미지는 여러 발송에 재사용합니다.

⚠️ 자유형은 검수를 거치지 않습니다. 요청에 실은 버튼 링크가 그대로 톡에 렌더되므로 링크를 만들어 넣는 쪽에서 확인하십시오.

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 입니다.

FromstringRequired

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

BodystringOptional

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

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

TypeenumOptional

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

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

ata↔Kakao, bms↔Brand 는 서로를 요구합니다. 한쪽만 있거나 다른 Type 을 명시하면 400 입니다. Kakao 와 Brand 를 함께 실어도 400 입니다(kakao_type_conflict) — 어느 쪽으로 나갈지 정해 드릴 수 없습니다.

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로 전송

알림톡·브랜드 메시지에는 쓸 수 없습니다(400 kakao_media_not_allowed) — 이미지는 템플릿에 넣으십시오.

IdempotencyKeystringOptional1-255 characters

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

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

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

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

KakaoobjectOptional

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

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

BrandobjectOptional

카카오 브랜드 메시지로 보냅니다. 이 항목이 있으면 브랜드 메시지입니다 — Type 은 생략하십시오.

채널을 추가한 친구에게만 나갑니다. 발신 채널은 콘솔의 「카카오톡 채널」에서 연결한 것이어야 합니다.

보내는 방식이 둘입니다 — 템플릿형(TemplateId)과 자유형(Free). 자세한 설명과 예시는 이 엔드포인트 설명을 보십시오.

FallbackobjectOptional

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

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

브랜드 메시지에는 쓸 수 없습니다(400 kakao_fallback_not_allowed) — 대체발송 자체가 없습니다.

Response

발송 요청 성공

messageIdstringOptional
statusenumOptional
Allowed values:
typeenumOptional

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

Allowed values:
subjectstring or nullOptional

메시지 제목 (LMS/MMS)

tostringOptional
fromstringOptional
bodystring or nullOptional
numMediaintegerOptional

첨부 이미지 수

mediaUrllist of stringsOptional

첨부 이미지 URL 목록

directionenumOptional
Allowed values:
accountIdstringOptional
dateCreateddatetimeOptional
dateUpdateddatetime or nullOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
422
Unprocessable Entity Error
429
Too Many Requests Error