본문으로 건너뛰기

메시지 발송

POST
/messages/v4/send-many/detail

하나 이상의 메시지를 발송하는 API입니다. 만 건을 초과하는 메시지 발송이 필요한 경우 그룹 메시지 API를 사용하는 것을 권장합니다.

  • 발신번호는 사전 등록 필수 → 발신번호 관리
  • 발송 내역 확인 → 문자발송 내역
  • 데이터 보관기간: 6개월 (생성일 기준)
  • 발송할 수 있는 메시지가 없을 경우 자세한 에러 내역을 결과로 반환
  • 6개월이 지난 내역은 조회 불가능

메시지 타입별 비교

구분내용 길이 제한필수 필드선택 필드주요 특징autoTypeDetect 조건
SMS (단문)
90 byte
(한글 45자)
messages.from
messages.to
messages.text
없음
일반 문자 메시지
text 필드가 90byte 이하일 경우
LMS (장문)
2,000 byte
(한글 1,000자)
messages.from
messages.to
messages.text
messages.subject
장문 문자 메시지
(수신자 데이터 통신 필요)
text 필드가 90byte를 초과하거나
subject 필드가 있을 경우
MMS (사진 문자)
2,000 byte
(한글 1,000자)
messages.from
messages.to
messages.text
messages.imageId
messages.subject
이미지 첨부 가능
(수신자 데이터 통신 필요)
이미지: JPG, 최대 200KB
imageId 필드가 있을 경우
카카오 알림톡 (ATA)
한글 1,000자
(변수 치환 후 기준)
messages.to
kakaoOptions.pfId
kakaoOptions.templateId
from
text
subject

[kakaoOptions]
disableSms
title
buttons
variables
replacements
사전 등록된 템플릿 사용
변수 치환 가능
실패 시 문자 대체 발송 가능
해당 없음
카카오 친구톡 (CTA)
1,000자
messages.to
messages.text
kakaoOptions.pfId
from
subject

[kakaoOptions]
buttons
disableSms
adFlag
replacements
수신자가 채널 친구여야 함
템플릿 없이 자유로운 내용 작성
광고 발송 가능 (adFlag)
해당 없음
카카오 이미지 친구톡 (CTI)
400자
messages.to
messages.text
kakaoOptions.pfId
kakaoOptions.imageId
from
subject

[kakaoOptions]
buttons
disableSms
adFlag
replacements
친구톡에 이미지 첨부

[이미지]
JPG/PNG
최대 500KB
특정 사이즈 제약 있음
해당 없음

카카오톡 알림톡(ATA)

사전에 등록된 템플릿 내용으로 알림톡을 발송하게 됩니다.
알림톡의 경우 템플릿으로 내용을 미리 정해놓지만 변수(치환문구)를 포함할 수 있어 발송할 때에도 내용을 지정해야 합니다.
본문 이외에도 강조 표기문구, 아이템 리스트, 부가정보 등을 모두 합하여 변수 치환 후 1,000자를 넘을 수 없습니다.

템플릿 변수 설정 방법

messages.kakaoOptions.variables 파라미터를 사용하면 템플릿의 변수만 간단히 지정할 수 있습니다.

인터랙티브 예제를 통해 카카오 알림톡 템플릿의 변수 설정 방법을 직접 체험해보세요!

  • 카카오 알림톡 미리보기: 각 항목을 클릭하여 내용을 수정할 수 있습니다
  • JSON 데이터: 변수 값이 실시간으로 반영됩니다
  • 양방향 동기화: 왼쪽에서 수정하면 오른쪽 JSON이 업데이트되고, JSON을 직접 수정해도 왼쪽 미리보기가 변경됩니다
알림톡 도착

안녕하세요,고객님!

회원 유형
가입일
회원 ID

🎉 가입 혜택


친구톡 (CTA)

친구톡은 수신자가 발송하는 채널에 친구가 추가되어 있을 경우에만 성공적으로 전송되며 친구가 아닌 대상에게 발송할 경우 발송에 실패하고 가격은 환불됩니다. 대체발송을 허용할 경우 친구가 아닌 사용자에게도 문자(SMS, LMS)로 다시 발송됩니다. 본문은 1,000자를 넘길 수 없습니다.

알림톡과 다르게 사전에 템플릿을 등록할 필요 없이 원하는 내용을 바로 작성하여 전송할 수 있으며 광고도 보낼 수 있습니다.
광고성 친구톡을 보낼 경우 messages.kakaoOptions.adFlag 필드를 true로 설정해야 합니다.


이미지 친구톡 (CTI)

친구톡과 동일하지만 이미지를 첨부하여 보낼 수 있으며 가격이 다릅니다. 본문은 400자를 넘을 수 없습니다.

  • 이미지 타입: kakao
  • 권장 크기: 720px * 720px
  • 크기 제한: 가로 500px 미만 또는 가로:세로 비율이 2:1 미만 또는 3:4 초과시 업로드 불가
  • 용량 제한: 최대 500KB
  • 파일 형식: JPG, PNG

대체발송

알림톡(ATA), 친구톡(CTA), 이미지 친구톡(CTI), RCS의 경우 기본적으로 대체발송이 활성화되어 있으며, messages.kakaoOptions.disableSms (카카오) 또는 messages.rcsOptions.disableSms (RCS)를 true로 설정하지 않는 한 발송에 실패하면 문자(SMS, LMS)로 대체 발송을 시도합니다.

대체발송 조건

대체발송이 정상적으로 동작하려면 요청 본문에 다음 조건을 모두 만족해야 합니다.

  • messages.kakaoOptions.disableSms: false로 설정
  • messages.rcsOptions.disableSms: false로 설정
  • messages.from: 사전 등록된 발신번호 명시

알림톡, 친구톡 발송 시 from 필드는 빈 값도 허용되지만, 대체발송을 원한다면 반드시 사전 등록된 발신번호를 명시해야 합니다. 조건을 만족하지 않으면 알림톡/친구톡 발송 실패 시 그대로 실패로 종결됩니다.


발신번호 사전 등록하러 가기

실패 원인타입설명
알림톡
정보성 메시지
기술적 전달 실패에 기반한 대체발송
카카오톡 미사용
-
수신자가 카카오톡을 사용하지 않거나 해당 번호에 카카오톡 계정이 없는 경우
채널 차단
-
수신자가 발신자인 카카오 비즈니스 채널을 차단한 경우
네트워크 불안정
-
수신자의 네트워크 상태가 불안정하여 메시지를 수신할 수 없는 경우
시스템 장애
-
카카오 시스템의 일시적인 장애
친구톡
광고성 메시지
정책적 규칙을 포함한 대체발송
채널 미추가
-
친구톡은 해당 카카오 비즈니스 채널을 친구로 추가한 사용자에게만 발송 가능합니다. 채널을 추가하지 않은 수신자에게는 즉시 실패 처리되고 대체발송이 실행됩니다.
야간 발송 시간 제한
-
오후 8시 50분부터 다음 날 오전 8시까지는 친구톡 발송이 제한됩니다. 이 시간대에 발송을 시도한 모든 친구톡 메시지는 예외 없이 발송 실패로 처리되며, 대체발송이 설정되어 있다면 모두 문자 메시지로 전환됩니다.
RCS
리치 커뮤니케이션
기술적 및 정책적 제약에 기반한 대체발송
RCS 미지원
-
수신자의 단말기나 통신사에서 RCS를 지원하지 않는 경우
브랜드 미승인
-
RCS 브랜드가 승인되지 않았거나 승인 과정 중인 경우
네트워크 불안정
-
RCS 서버와의 통신이 불안정하거나 일시적 장애가 발생한 경우

대체발송 시 원래 메시지 타입의 가격은 환불되고 각 문자 타입에 맞는 금액이 차감됩니다.

친구톡 발송이 실패하여 문자 메시지로 대체 발송될 때, 솔라피 시스템은 정보통신망법의 광고성 정보 전송 규제를 준수하기 위해 메시지 본문에 (광고) 문구를 자동으로 추가합니다. 자세한 내용은 해당 문서를 확인해주세요.


대체발송 시 메시지 콘텐츠 변환

카카오톡의 리치 미디어 환경에서 문자 메시지 환경으로 채널이 전환될 때, 솔라피 시스템은 정보 손실을 최소화하고 핵심 내용을 보존하는 방향으로 콘텐츠를 변환합니다.

콘텐츠 유형변환 방식
텍스트 콘텐츠
알림톡/RCS 템플릿의 경우 템플릿의 내용이, 친구톡/RCS의 경우 `messages.text` 필드에 입력한 내용이 대체발송 문자로 전송됩니다.
버튼 (웹/앱 링크)
버튼의 이름과 연결된 URL이 문자 메시지 본문에 텍스트 형태로 포함됩니다. 예시 이미지를 참고해주세요.
이미지
이미지가 포함된 친구톡은 MMS로 대체발송되지 않고 LMS로 전환됩니다.
이미지는 URL 링크 형태로 LMS 메시지 본문에 포함됩니다.

Body Params

NameTypeRequiredDescription
messages
Array<Object>
O
발송할 메시지 내용
scheduledDate
date
-
메시지 예약 날짜. 날짜가 지정되면 해당 시간에 메시지가 발송됩니다. 만약 현재 시간보다 이전으로 지정하면 즉시 발송됩니다. 예약 즉시 일일발송량에 영향을 주며 잔액은 발송 시 차감됩니다.
strict
boolean
-
엄격 검사 여부. 기본값: `false`
- 유요하지 않은 문자 검사(아닐 시 자체적으로 삭제).
- LMS 나 MMS에서 제목 여부 검사. (아닐 시 문자 내용에서 제목을 구함).
- 템플릿을 발송 전 검사(아닐 시 발송 후 실패).
agent
Object
-
에이전트
allowDuplicates
boolean
-
중복 수신번호 허용 여부. 기본값: `false`
showMessageList
boolean
-
응답에 메시지도 포함시킬지 선택 여부.

Response

NameTypeShould ReturnDescription
failedMessageList
Array<Object>
O
등록 실패된 메시지 목록. 여기 목록에 포함되어 있는 메시지는 발송되지 않은 메시지입니다.
groupInfo
Object
O
발송 요청한 메시지들의 그룹 정보

Structures

{6 properties
"messages":
[1 items...]
{16 properties...}
"to": "string",
"from": "string",
"text": "string",
"type": "string",
"country": "string",
"subject": "string",
"imageId": "string",
"kakaoOptions":
{17 properties...}
"pfId": "string",
"templateId": "string",
"senderKey": "string",
"title": "string",
"adFlag": "boolean",
"templateCode": "string",
"buttonName": "string",
"buttonUrl": "string",
"disableSms": "boolean",
"imageId": "string",
"variables":
{3 properties...}
"#{홍길동}": "string",
"#{010-0000-0000}": "string",
"#{2021년 6월 17일}": "string"
}
,
"quickReplies":
[1 items...]
{8 properties...}
"name": "string",
"linkType": "string",
"linkMo": "string",
"linkPc": "string",
"linkAnd": "string",
"linkIos": "string",
"chatExtra": "string",
"targetOut": "boolean"
}
]
,
"highlight":
{1 properties...}
"title": "string"
}
,
"header": "string",
"item":
{2 properties...}
"list":
[1 items...]
{1 properties...}
"description": "string"
}
]
,
"summary":
{1 properties...}
"description": "string"
}
}
,
"buttons":
[1 items...]
{8 properties...}
"buttonName": "string",
"buttonType": "string",
"linkMo": "string",
"linkPc": "string",
"linkAnd": "string",
"linkIos": "string",
"chatExtra": "string",
"targetOut": "boolean"
}
]
,
"bms":
{1 properties...}
"targeting": "string"
}
}
,
"naverOptions":
{5 properties...}
"talkId": "string",
"templateId": "string",
"disableSms": "boolean",
"variables":
{3 properties...}
"#{홍길동}": "string",
"#{010-0000-0000}": "string",
"#{2021년 6월 17일}": "string"
}
,
"buttons":
[1 items...]
{7 properties...}
"buttonCode": "string",
"buttonName": "string",
"buttonType": "string",
"linkMo": "string",
"linkPc": "string",
"linkAnd": "string",
"linkIos": "string"
}
]
}
,
"rcsOptions":
{9 properties...}
"brandId": "string",
"templateId": "string",
"copyAllowed": "boolean",
"variables":
{3 properties...}
"{{홍길동}}": "string",
"{{010-0000-0000}}": "string",
"{{2021년 6월 17일}}": "string"
}
,
"mmsType": "string",
"commercialType": "boolean",
"disableSms": "boolean",
"additionalBody":
[1 items...]
{4 properties...}
"title": "string",
"description": "string",
"imageId": "string",
"buttons":
[1 items...]
{12 properties...}
"buttonType": "string",
"buttonName": "string",
"link": "string",
"latitude": "string",
"longitude": "string",
"label": "string",
"query": "string",
"title": "string",
"startTime": "date",
"endTime": "date",
"text": "string",
"phone": "string"
}
]
}
]
,
"buttons":
[1 items...]
{12 properties...}
"buttonType": "string",
"buttonName": "string",
"link": "string",
"latitude": "string",
"longitude": "string",
"label": "string",
"query": "string",
"title": "string",
"startTime": "date",
"endTime": "date",
"text": "string",
"phone": "string"
}
]
}
,
"faxOptions":
{1 properties...}
"fileIds":
[1 items...]
{
}
]
}
,
"voiceOptions":
{6 properties...}
"voiceType": "string",
"headerMessage": "string",
"tailMessage": "string",
"replyRange": "number",
"counselorNumber": "string",
"variables":
{
}
}
,
"customFields":
{1 properties...}
"key": "string"
}
,
"autoTypeDetect": "boolean",
"hint":
{
}
,
"replacements":
[1 items...]
{4 properties...}
"to": "string",
"from": "string",
"text": "string",
"customFields":
{1 properties...}
"key": "string"
}
}
]
}
]
,
"scheduledDate": "date",
"strict": "boolean",
"agent":
{3 properties...}
"appId": "string",
"osPlatform": "string",
"sdkVersion": "string"
}
,
"allowDuplicates": "boolean",
"showMessageList": "string"
}
{2 properties
"failedMessageList":
[1 items...]
{8 properties...}
"to": "string",
"from": "string",
"type": "string",
"country": "string",
"messageId": "string",
"statusCode": "string",
"statusMessage": "string",
"accountId": "string"
}
]
,
"groupInfo":
{28 properties...}
"count":
{9 properties...}
"total": "number",
"sentTotal": "number",
"sentFailed": "number",
"sentSuccess": "number",
"sentPending": "number",
"sentReplacement": "number",
"refund": "number",
"registeredFailed": "number",
"registeredSuccess": "number"
}
,
"countForCharge":
{23 properties...}
"sms":
{2 properties...}
"82": "number",
"101": "number"
}
,
"lms":
{2 properties...}
"82": "number",
"101": "number"
}
,
"mms":
{2 properties...}
"82": "number",
"101": "number"
}
,
"ata":
{2 properties...}
"82": "number",
"101": "number"
}
,
"cta":
{2 properties...}
"82": "number",
"101": "number"
}
,
"cti":
{2 properties...}
"82": "number",
"101": "number"
}
,
"nsa":
{2 properties...}
"82": "number",
"101": "number"
}
,
"rcs_sms":
{2 properties...}
"82": "number",
"101": "number"
}
,
"rcs_lms":
{2 properties...}
"82": "number",
"101": "number"
}
,
"rcs_mms":
{2 properties...}
"82": "number",
"101": "number"
}
,
"rcs_tpl":
{2 properties...}
"82": "number",
"101": "number"
}
,
"rcs_itpl":
{2 properties...}
"82": "number",
"101": "number"
}
,
"rcs_ltpl":
{2 properties...}
"82": "number",
"101": "number"
}
,
"fax":
{2 properties...}
"82": "number",
"101": "number"
}
,
"voice":
{2 properties...}
"82": "number",
"101": "number"
}
,
"bms_text":
{2 properties...}
"82": "number",
"101": "number"
}
,
"bms_image":
{2 properties...}
"82": "number",
"101": "number"
}
,
"bms_wide":
{2 properties...}
"82": "number",
"101": "number"
}
,
"bms_wide_item_list":
{2 properties...}
"82": "number",
"101": "number"
}
,
"bms_carousel_feed":
{2 properties...}
"82": "number",
"101": "number"
}
,
"bms_premium_video":
{2 properties...}
"82": "number",
"101": "number"
}
,
"bms_commerce":
{2 properties...}
"82": "number",
"101": "number"
}
,
"bms_carousel_commerce":
{2 properties...}
"82": "number",
"101": "number"
}
}
,
"balance":
{5 properties...}
"requested": "number",
"replacement": "number",
"additional": "number",
"refund": "number",
"sum": "number"
}
,
"point":
{5 properties...}
"requested": "number",
"replacement": "number",
"additional": "number",
"refund": "number",
"sum": "number"
}
,
"app":
{3 properties...}
"profit":
{23 properties...}
"sms": "number",
"lms": "number",
"mms": "number",
"ata": "number",
"cta": "number",
"cti": "number",
"nsa": "number",
"rcs_sms": "number",
"rcs_lms": "number",
"rcs_mms": "number",
"rcs_tpl": "number",
"rcs_itpl": "number",
"rcs_ltpl": "number",
"fax": "number",
"voice": "number",
"bms_text": "number",
"bms_image": "number",
"bms_wide": "number",
"bms_wide_item_list": "number",
"bms_carousel_feed": "number",
"bms_premium_video": "number",
"bms_commerce": "number",
"bms_carousel_commerce": "number"
}
,
"app": "string",
"version": "string"
}
,
"serviceMethod": "string",
"sdkVersion": "string",
"osPlatform": "string",
"log":
[1 items...]
{7 properties...}
"createAt": "date",
"message": "string",
"oldBalance": "number",
"newBalance": "number",
"oldPoint": "number",
"newPoint": "number",
"totalPrice": "number"
}
]
,
"status": "string",
"dateSent": "date",
"scheduledDate": "date",
"dateCompleted": "date",
"isRefunded": "boolean",
"flagUpdated": "boolean",
"prepaid": "boolean",
"strict": "boolean",
"masterAccountId": "string",
"allowDuplicates": "boolean",
"_id": "string",
"accountId": "string",
"apiVersion": "string",
"customFields":
{1 properties...}
"key": "string"
}
,
"hint": "string",
"groupId": "string",
"price":
{1 properties...}
"82":
{23 properties...}
"sms": "number",
"lms": "number",
"mms": "number",
"ata": "number",
"cta": "number",
"cti": "number",
"nsa": "number",
"rcs_sms": "number",
"rcs_lms": "number",
"rcs_mms": "number",
"rcs_tpl": "number",
"rcs_itpl": "number",
"rcs_ltpl": "number",
"fax": "number",
"voice": "number",
"bms_text": "number",
"bms_image": "number",
"bms_wide": "number",
"bms_wide_item_list": "number",
"bms_carousel_feed": "number",
"bms_premium_video": "number",
"bms_commerce": "number",
"bms_carousel_commerce": "number"
}
}
,
"dateCreated": "date",
"dateUpdated": "date"
}
}