API

그룹 메시지 추가

작성일 2026.03.05 | 수정일 2026.03.05

PUT/messages/v4/groups/:groupId/messages

Parameters

groupId*— 메시지를 추가할 그룹의 아이디

그룹에 발송할 메시지를 추가합니다. PENDING 상태인 그룹에만 메시지를 추가할 수 있으며, 한 번에 최대 10,000건까지 추가할 수 있습니다.

대량의 메시지를 발송해야 할 경우, 이 API를 여러 번 호출하여 나누어 추가한 뒤 한꺼번에 발송할 수 있습니다. 그룹당 최대 1,000,000건의 메시지를 담을 수 있습니다.

strict 모드에 따른 동작 차이:
strict: false (기본값): 유효한 메시지만 추가되고, 유효성 검증에 실패한 메시지는 건너뜁니다. errorCount에서 실패 건수를 확인할 수 있습니다.
strict: true: 메시지 중 하나라도 유효성 검증에 실패하면 전체 추가가 취소됩니다.

Body Params

Name	Type	Required	Description
messages	array	*	메시지 객체 배열. 최소 1건 이상 필요
to	string	*	수신번호. 하이픈(-) 없이 숫자만 입력 (예: 01012345678)
from	string		발신번호. 사전에 등록된 발신번호만 사용 가능
type	string		메시지 타입. SMS, LMS, MMS, ATA, CTA, CTI, NSA, RCS_SMS, RCS_LMS, RCS_MMS, RCS_TPL, RCS_ITPL, RCS_LTPL, FAX, VOICE. 미지정 시 text 길이에 따라 자동 감지
text	string		메시지 본문 내용
country	string		수신자의 국가 코드. 기본값: 82(대한민국)
subject	string		메시지 제목. LMS, MMS 등 장문 메시지에서 사용
imageId	string		MMS 발송 시 첨부할 이미지의 아이디. 이미지 업로드 API로 미리 등록 필요
autoTypeDetect	boolean		true이면 text 길이에 따라 SMS/LMS를 자동으로 결정
customFields	object		메시지별 사용자 정의 메타 데이터
hint	object		발송 시 참고할 힌트 정보
kakaoOptions	object		카카오 알림톡(ATA)/친구톡(CTA, CTI) 발송 시 필요한 옵션
pfId	string		카카오 채널 아이디
senderKey	string		발신프로필 키
templateId	string		알림톡 템플릿 아이디
templateCode	string		알림톡 템플릿 코드
title	string		강조표기 핵심 문구
adFlag	boolean		광고 표시 여부
disableSms	boolean		카카오 발송 실패 시 SMS 대체 발송 비활성화 여부
imageId	string		카카오 이미지 아이디
buttons	array		버튼 목록
buttonName	string	*	버튼 이름
buttonType	string	*	버튼 타입. WL(웹링크), AL(앱링크), DS(배송조회), BK(봇키워드), MD(메시지전달), AC(채널추가) 등
linkMo	string		모바일 웹 링크
linkPc	string		PC 웹 링크
schemeIos	string		iOS 앱 스킴
schemeAndroid	string		Android 앱 스킴
chatExtra	string		봇키워드/메시지전달 시 전달할 추가 데이터
targetOut	boolean		외부 브라우저에서 열기 여부
quickReplies	array		바로연결 버튼 목록
name	string	*	바로연결 버튼 이름
linkType	string	*	링크 타입. WL(웹링크), AL(앱링크) 등
linkMo	string		모바일 웹 링크
linkPc	string		PC 웹 링크
schemeIos	string		iOS 앱 스킴
schemeAndroid	string		Android 앱 스킴
chatExtra	string		봇키워드/메시지전달 시 전달할 추가 데이터
header	string		템플릿 헤더 텍스트
highlight	object		하이라이트 정보
title	string	*	하이라이트 제목
description	string	*	하이라이트 설명
item	object		아이템리스트형 정보
list	array	*	아이템 목록
title	string	*	항목 제목
description	string	*	항목 설명
summary	object		합계/요약 정보
title	string	*	요약 제목 (예: 결제금액)
description	string	*	요약 값 (예: 59,000원)
naverOptions	object		네이버 톡톡 발송 시 필요한 옵션
talkId	string		네이버톡톡 채널 아이디
templateId	string		네이버톡톡 템플릿 아이디
disableSms	boolean		실패 시 SMS 대체 발송 비활성화 여부
buttons	array		버튼 목록
buttonCode	string		버튼 코드
buttonName	string	*	버튼 이름
buttonType	string	*	버튼 타입
linkMo	string		모바일 웹 링크
linkPc	string		PC 웹 링크
rcsOptions	object		RCS 메시지 발송 시 필요한 옵션
brandId	string		RCS 브랜드 아이디
templateId	string		RCS 템플릿 아이디
mmsType	string		MMS 타입. M3~M6(가로형), S3~S6(세로형)
copyAllowed	boolean		내용 복사 허용 여부
commercialType	boolean		광고성 메시지 여부
disableSms	boolean		실패 시 SMS 대체 발송 비활성화 여부
additionalBody	array		슬라이드 정보 목록 (MMS 타입에서 사용)
title	string		슬라이드 제목
description	string		슬라이드 설명
imageId	string		슬라이드 이미지 아이디
buttons	array		슬라이드별 버튼 목록. RCS 버튼 구조와 동일
buttons	array		버튼 목록
buttonType	string	*	버튼 타입. WL(웹링크), DL(전화걸기) 등
buttonName	string	*	버튼 이름
link	string		웹 링크 URL (WL 타입)
phone	string		전화번호 (DL 타입)
faxOptions	object		팩스 발송 시 필요한 옵션
fileIds	array	*	팩스 파일 아이디 목록. 파일 업로드 API로 미리 등록 필요
voiceOptions	object		음성 메시지(TTS) 발송 시 필요한 옵션
voiceType	string		음성 타입. MALE(남성) 또는 FEMALE(여성)
headerMessage	string		본문 앞에 추가되는 헤더 안내 메시지
tailMessage	string		본문 뒤에 추가되는 마무리 메시지
replyRange	number		응답 대기 범위 (초)
counselorNumber	string		상담원 연결 번호

Response

Name	Type	Required	Description
errorCount	number	*	유효성 검증에 실패한 메시지 건수. 0이면 모든 메시지가 정상 추가된 것
resultList	array	*	각 메시지의 추가 결과 목록
to	string	*	수신번호
from	string	*	발신번호
type	string	*	최종 결정된 메시지 타입. 자동 감지된 경우 감지 결과가 표시됨
country	string	*	수신 국가 코드
messageId	string	*	메시지 고유 아이디. M4V로 시작하는 32자 문자열
statusCode	string	*	접수 상태 코드. 2000이면 정상 접수
statusMessage	string	*	상태 코드에 대한 설명
accountId	string	*	계정 아이디

Structures

Request

{
  "messages": [
    {
      "to": "01012345678",
      "from": "0212345678",
      "text": "테스트 메시지입니다.",
      "type": "SMS"
    },
    {
      "to": "01087654321",
      "from": "0212345678",
      "text": "카카오 알림톡 테스트",
      "type": "ATA",
      "kakaoOptions": {
        "pfId": "KA01PF123456",
        "templateId": "KA01TP789012",
        "buttons": [
          {
            "buttonName": "확인하기",
            "buttonType": "WL",
            "linkMo": "https://example.com"
          }
        ]
      }
    }
  ]
}

Response

{
  "errorCount": 0,
  "resultList": [
    {
      "to": "01012345678",
      "from": "0212345678",
      "type": "SMS",
      "country": "82",
      "messageId": "M4V20260302143506CQKNPHTPCX4P5E",
      "statusCode": "2000",
      "statusMessage": "정상 접수(이통사로 , , 발송 , , , 예정)",
      "accountId": "23010100000001"
    },
    {
      "to": "01087654321",
      "from": "0212345678",
      "type": "ATA",
      "country": "82",
      "messageId": "M4V20260302143506DRLMPITQDX5Q6F",
      "statusCode": "2000",
      "statusMessage": "정상 접수(이통사로 발송 예정)",
      "accountId": "23010100000001"
    }
  ]
}