그룹 메시지 추가

Request

[PUT] https://api.coolsms.co.kr/messages/v4/groups/:groupId/messages

그룹에 메시지를 추가합니다. 접수 실패건은 저장되지만 발송은 되지 않습니다.

그룹메시지 추가 API에 다음 3가지 제한사항이 있습니다.

하나의 요청의 총 데이터 크기는 15MB를 넘을 수 없습니다.
하나의 요청에 수신번호는 10,000 개를 넘을 수 없습니다.
하나의 그룹에 담을 수 있는 메시지는 1,000,000 개 제한입니다.

홈페이지의 문자발송 내역에서 전송결과 내역을 확인하실 수 있습니다. (로그인 필요)

전송 내역(메시지 그룹, 메시지 목록)의 보관기간은 생성일 기준 6개월 입니다. 6개월이 지난 내역은 조회가 불가능합니다.

Authorization 인증 필요

_{Authorization 인증이란?}

계정 권한	회원 권한	계정 상태	회원 상태	계정 인증
`message:write`	`role-message:write`	`ACTIVE`	`ACTIVE`

Path Parameters

Name	Description
:groupId	메시지 그룹 아이디

Request Structure

{
    "messages": [
        {
            "to": "string",
            "from": "string",
            "text": "string",
            "type": "string",
            "country": "string",
            "subject": "string",
            "imageId": "string",
            "kakaoOptions": {
                "pfId": "string",
                "templateId": "string",
                "title": "string",
                "adFlag": "boolean",
                "disableSms": "boolean",
                "imageId": "string",
                "variables": {},
                "quickReplies": [
                    null
                ],
                "highlight": {},
                "header": "string",
                "item": {},
                "buttons": [
                    {
                        "buttonName": "string",
                        "buttonType": "string",
                        "linkMo": "string",
                        "linkPc": "string",
                        "linkAnd": "string",
                        "linkIos": "string"
                    }
                ]
            },
            "naverOptions": {
                "talkId": "string",
                "templateId": "string",
                "disableSms": "boolean",
                "variables": {},
                "buttons": [
                    {
                        "buttonName": "string",
                        "buttonType": "string",
                        "linkMo": "string",
                        "linkPc": "string",
                        "linkAnd": "string",
                        "linkIos": "string"
                    }
                ]
            },
            "rcsOptions": {
                "brandId": "string",
                "templateId": "string",
                "copyAllowed": "boolean",
                "variables": {},
                "mmsType": "string",
                "commercialType": "boolean",
                "disableSms": "boolean",
                "additionalBody": [
                    {
                        "title": "string",
                        "description": "string",
                        "imageId": "string",
                        "buttons": [
                            {
                                "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": [
                    {
                        "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": {
                "fileIds": [
                    "string"
                ]
            },
            "voiceOptions": {
                "voiceType": "string",
                "headerMessage": "string",
                "tailMessage": "string",
                "replyRange": "number",
                "counselorNumber": "string"
            },
            "customFields": {},
            "autoTypeDetect": "boolean"
        }
    ]
}

Body Params

Name	Type	Required	Description
messages	`array`	O	발송할 메시지 내용

Body / messages

Name	Type	Required	Description
to	`string`	O	수신번호. 발송할 때는 숫자만 입력해야 됩니다. 해외로 발송할 경우 "+"(더하기) 기호와 국가 번호는 제외하고 입력해주세요. 국가번호는 `country` 필드에 입력해야 합니다.
from	`string`		발신번호. 사전 등록된 전화번호만 사용 가능합니다. 문자(SMS, LMS, MMS, FAX)를 보낼 때는 필수입니다. 알림톡, 친구톡을 보내는 경우에는 빈 값도 허용되지만 대체발송 시 문자 발송은 실패합니다.
text	`string`		메시지 내용. SMS: 90byte 제한 나머지: 2000byte 제한
type	`string`		메시지 타입 SMS: 단문 문자 LMS: 장문 문자 MMS: 사진 문자 ATA: 알림톡 CTA: 친구톡 CTI: 친구톡 + 이미지 NSA: 네이버 스마트 알림 RCS_SMS: RCS 단문 문자 RCS_LMS: RCS 장문 문자 RCS_MMS: RCS 사진 문자 RCS_TPL: RCS 템플릿 문자 RCS_ITPL: RCS 이미지 템플릿 문자 RCS_LTPL: RCS LMS 템플릿 문자 FAX: 팩스 VOICE: 보이스콜
country	`string`		국가번호 (기본: 82, 미국(캐나다):1, 중국: 86, 일본: 81)
subject	`string`		메시지 제목. 40byte 제한. LMS, MMS, FAX 에서만 사용 가능합니다. ATA, CTA, CTI, NSA, RCS_SMS, RCS_LMS, RCS_MMS, RCS_TPL에서도 설정 가능하지만 LMS 혹은 MMS로 대체발송 될 때 사용됩니다. 설정하지 않았을 경우 메시지 본문 내용 앞 40byte가 자동으로 들어갑니다.
imageId	`string`		MMS 발송 시 사용되는 이미지의 고유 아이디. 이미지 타입이 `MMS`일 경우에만 사용 가능합니다. 이미지 관리 페이지 (로그인 필요) 이미지 관리 API
kakaoOptions	`object`		친구톡, 알림톡을 보내기 위한 옵션
naverOptions	`object`		네이버 스마트 알림을 보내기 위한 옵션
rcsOptions	`object`		RCS 문자를 보내기 위한 옵션
faxOptions	`object`		설명 없음
voiceOptions	`object`		보이스 옵션
customFields	`object`		확장 필드로 사용. 키는 30자, 값은 100자 제한
autoTypeDetect	`boolean`		"type" 필드를 직접 지정하지 않았을 경우 자동으로 타입을 지정하게 할 수 있는 값입니다. 기본값: `true`

Body / messages / kakaoOptions

Name	Type	Description
pfId	`string`	카카오톡 채널 연동 아이디 카카오톡 채널 관리 페이지 (로그인 필요) 카카오톡 채널 관리 API
templateId	`string`	알림톡 템플릿 연동 아이디 알림톡 템플릿 관리 페이지 (로그인 필요) 알림톡 템플릿 관리 API
title	`string`	강조표기문구
adFlag	`boolean`	친구톡 광고 문자 여부. 친구톡 광고를 보낼 때 해당 값을 제대로 설정하지 않으면 카카오톡 채널 사용에 패널티가 가해질 수 있습니다. 기본값: `false`
disableSms	`boolean`	대체발송여부. `false` 로 설정했을 경우 해당건이 발송에 실패하게 됐을 때 문자로(SMS, LMS, MMS)로 대체 발송됩니다. 대체 발송이 될 경우 기존 가격은 환불되고 각 문자 타입에 맞는 금액이 차감됩니다. 기본값: `false`
imageId	`string`	이미지 친구톡 발송 시 사용되는 이미지의 고유 아이디. 이미지 타입이 `KAKAO`일 경우에만 사용 가능합니다. 이미지 관리 페이지 (로그인 필요) 이미지 관리 API
variables	`object`	카카오톡 템플릿 대체 문구 입력 오브젝트
quickReplies	`array`	바로 연결. 최소 1개, 최대 10개.
highlight	`object`	알림톡 하이라이트. 강조 유형이 아이템 리스트일 때만 사용 가능합니다.
header	`string`	알림톡 헤더. 강조 유형이 아이템 리스트일 때만 사용 가능합니다. 변수 포함 가능. 최대 16자
item	`object`	알림톡 아이템. 목록과 요약이 있습니다. 강조 유형이 아이템 리스트일 때만 사용 가능합니다.
buttons	`array`	알림톡, 친구톡 템플릿 버튼 목록

Body / messages / kakaoOptions / variables

Name	Type	Required	Description

Body / messages / kakaoOptions / highlight

Name	Type	Required	Description

Body / messages / kakaoOptions / item

Name	Type	Required	Description

Body / messages / kakaoOptions / buttons

Name	Type	Required	Description
buttonName	`string`	O	버튼 이름
buttonType	`string`	O	버튼 유형. 버튼 유형 안내 문서
linkMo	`string`		모바일 링크(WL 웹링크)
linkPc	`string`		웹 링크(WL 웹링크)
linkAnd	`string`		안드로이드 링크(AL 앱링크)
linkIos	`string`		IOS 링크(AL 앱링크)

Body / messages / naverOptions

Name	Type	Description
talkId	`string`	테스트에서 발급된 네이버 톡톡 연동 아이디
templateId	`string`	네이버 스마트 알림 템플릿 아이디
disableSms	`boolean`	대체발송여부. `false` 로 설정했을 경우 해당건이 발송에 실패하게 됐을 때 문자로(SMS, LMS, MMS)로 대체 발송됩니다. 대체 발송이 될 경우 기존 가격은 환불되고 각 문자 타입에 맞는 금액이 차감됩니다. 기본값: `false`
variables	`object`	네이버 템플릿 대체 문구 입력 오브젝트
buttons	`array`	네이버 스마트 알림 템플릿 버튼 목록

Body / messages / naverOptions / variables

Name	Type	Required	Description

Body / messages / naverOptions / buttons

Name	Type	Required	Description
buttonName	`string`		버튼 이름
buttonType	`string`	O	버튼 타입.
linkMo	`string`		모바일 링크
linkPc	`string`		웹 링크
linkAnd	`string`		안드로이드 앱 링크
linkIos	`string`		아이폰 앱 링크

Body / messages / rcsOptions

Name	Type	Description
brandId	`string`	브랜드 아이디
templateId	`string`	RCS 템플릿 아이디
copyAllowed	`boolean`	문자 복사 가능 여부
variables	`object`	RCS 템플릿 대체 문구 입력 오브젝트
mmsType	`string`	사진 문자 타입. 타입: "M3", "S3", "M4", "S4", "M5", "S5", "M6", "S6" (M: 중간 사이즈. S: 작은 사이즈. 숫자: 사진 개수)
commercialType	`boolean`	광고 문자 여부
disableSms	`boolean`	대체발송여부. `false` 로 설정했을 경우 해당건이 발송에 실패하게 됐을 때 문자로(SMS, LMS, MMS)로 대체 발송됩니다. 대체 발송이 될 경우 기존 가격은 환불되고 각 문자 타입에 맞는 금액이 차감됩니다. 기본값: `false`
additionalBody	`array`	RCS 사진 문자 전송 시 필요한 오브젝트
buttons	`array`	RCS 템플릿 버튼 목록

Body / messages / rcsOptions / variables

Name	Type	Required	Description

Body / messages / rcsOptions / additionalBody

Name	Type	Required	Description
title	`string`	O	슬라이드 제목
description	`string`	O	슬라이드 설명
imageId	`string`		MMS 발송 시 사용되는 이미지의 고유 아이디. 이미지 타입이 `MMS`일 경우에만 사용 가능합니다. 이미지 관리 페이지 (로그인 필요) 이미지 관리 API
buttons	`array`		슬라이드에 추가되는 버튼 목록 최대 2개

Body / messages / rcsOptions / additionalBody / buttons

Name	Type	Required	Description
buttonType	`string`	O	'WL'(웹링크), 'ML'(지도[좌표]), 'MQ'(지도[쿼리]), 'MR'(위치공유), 'CA'(캘린더생성), 'CL'(복사), 'DL'(전화걸기), 'MS'(메시지보내기)
buttonName	`string`	O	버튼 이름
link	`string`		버튼 타입 ML, MQ에 사용되는 링크
latitude	`string`		버튼 타입 ML에 사용되는 위도 좌표
longitude	`string`		버튼 타입 ML에 사용되는 경도 좌표
label	`string`		버튼 타입 ML에 사용되는 레이블
query	`string`		버튼 타입 MQ에 사용되는 쿼리
title	`string`		버튼 타입 CA에 사용되는 일정 이름
startTime	`date`		버튼 타입 CA에 사용되는 일정 시작일
endTime	`date`		버튼 타입 CA에 사용되는 일정 종료작일
text	`string`		메시지 내용. SMS: 90byte 제한 나머지: 2000byte 제한
phone	`string`		핸드폰 번호 버튼 타입 DL과 MS에 사용됨

Body / messages / rcsOptions / buttons

Name	Type	Required	Description
buttonType	`string`	O	'WL'(웹링크), 'ML'(지도[좌표]), 'MQ'(지도[쿼리]), 'MR'(위치공유), 'CA'(캘린더생성), 'CL'(복사), 'DL'(전화걸기), 'MS'(메시지보내기)
buttonName	`string`	O	버튼 이름
link	`string`		버튼 타입 ML, MQ에 사용되는 링크
latitude	`string`		버튼 타입 ML에 사용되는 위도 좌표
longitude	`string`		버튼 타입 ML에 사용되는 경도 좌표
label	`string`		버튼 타입 ML에 사용되는 레이블
query	`string`		버튼 타입 MQ에 사용되는 쿼리
title	`string`		버튼 타입 CA에 사용되는 일정 이름
startTime	`date`		버튼 타입 CA에 사용되는 일정 시작일
endTime	`date`		버튼 타입 CA에 사용되는 일정 종료작일
text	`string`		메시지 내용. SMS: 90byte 제한 나머지: 2000byte 제한
phone	`string`		핸드폰 번호 버튼 타입 DL과 MS에 사용됨

Body / messages / faxOptions

Name	Type	Required	Description
fileIds	`array`		설명 없음

Body / messages / voiceOptions

Name	Type	Description
voiceType	`string`	'MALE', 'FEMALE' (보이스 타입 '남자', '여자')
headerMessage	`string`	머리말, 통화 시작시 나오는 메시지 (최대 70Byte)
tailMessage	`string`	맺음말, 통화가 끝나고 나오는 메시지, 상담원 연결 시 나오지 않음, 머리말이 있어야 사용가능 (최대 70Byte)
replyRange	`number`	통화 내용이 나온 후 1~3번까지의 버튼으로 받는 답변 (수신자에게서 입력받을 숫자, 1~3까지 입력가능, '3'입력 시 1~3번까지 누를 수 있음.)

EX) 안녕하십니까. 쇼핑몰 사이트를 이용해주셔서 감사합니다. 제공해드리는 상품에 대한 만족도를 선택해주세요. 1번 만족. 2번 보통. 3번 불만족 | | counselorNumber | string | | 상담원번호, 번호 입력 시 통화 내용이 나온 후 0번을 누르면 상담원 연결 (replyRange가 없으면 0번외엔 누를 수 없음 ) |

Body / messages / customFields

Name	Type	Required	Description

Response

Response Structure

{
    "errorCount": "number",
    "resultList": [
        {
            "to": "string",
            "from": "string",
            "type": "string",
            "country": "string",
            "messageId": "string",
            "statusCode": "string",
            "statusMessage": "string",
            "accountId": "string"
        }
    ]
}

Response Description

Response /

Name	Type	Should Return	Description
errorCount	`number`		접수 실패 카운트
resultList	`array`		모든 메시지의 접수 결과 목록

Response / resultList

Name	Type	Should Return	Description
to	`string`	O	수신번호
from	`string`	O	발신번호
type	`string`	O	메시지 타입 SMS: 단문 문자 LMS: 장문 문자 MMS: 사진 문자 ATA: 알림톡 CTA: 친구톡 CTI: 친구톡 + 이미지 NSA: 네이버 스마트 알림 RCS_SMS: RCS 단문 문자 RCS_LMS: RCS 장문 문자 RCS_MMS: RCS 사진 문자 RCS_TPL: RCS 템플릿 문자 RCS_ITPL: RCS 이미지 템플릿 문자 RCS_LTPL: RCS LMS 템플릿 문자 FAX: 팩스 VOICE: 보이스콜
country	`string`	O	국가번호 (기본: 82, 미국(캐나다):1, 중국: 86, 일본: 81)
messageId	`string`	O	메시지 아이디
statusCode	`string`	O	상태 코드 참고
statusMessage	`string`	O	상태 메시지 참고
accountId	`string`	O	계정 고유 번호

문서 생성일 : 2024-11-26

그룹 메시지 추가

목차​

Request​

Authorization 인증 필요​

Path Parameters​

Request Structure​

Body Params​

Body / messages​

Body / messages / kakaoOptions​

Body / messages / kakaoOptions / variables​

Body / messages / kakaoOptions / highlight​

Body / messages / kakaoOptions / item​

Body / messages / kakaoOptions / buttons​

Body / messages / naverOptions​

Body / messages / naverOptions / variables​

Body / messages / naverOptions / buttons​

Body / messages / rcsOptions​

Body / messages / rcsOptions / variables​

Body / messages / rcsOptions / additionalBody​

Body / messages / rcsOptions / additionalBody / buttons​

Body / messages / rcsOptions / buttons​

Body / messages / faxOptions​

Body / messages / voiceOptions​

Body / messages / customFields​

Response​

Response Structure​

Response Description​

Response /​

Response / resultList​

목차