메시지 발송

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 에 넣습니다. 한 번 올린 이미지는 여러 발송에 재사용합니다.

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

Path Parameters

Response Body