그룹 메시지 추가

Request

PUT https://api.solapi.com/messages/v4/groups/:groupId/messages

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

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

  • 하나의 요청의 총 데이터 크기는 15MB를 넘을 수 없습니다.

  • 하나의 요청에 수신번호는 10,000 개를 넘을 수 없습니다.

  • 하나의 그룹에 담을 수 있는 메시지는 1,000,000 개 제한입니다.

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

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

Authorization 인증 필요 [?]

계정 권한
회원 권한
계정 상태
회원 상태
계정 인증

message:write

role-message:write

ACTIVE

ACTIVE

Path Parameters

Name
Description

:groupId

메시지 그룹 아이디

Request Structure

{
    "messages": "Array"
}

Body Params

Name
Type
Required
Description

messages

Array

O

발송할 메시지 내용

Body / messages

Name
Type
Required
Description

to

string

O

수신번호

from

string

O

발신번호 사전 등록된 전화번호만 사용 가능

text

string

O

메시지 내용 한글 1,000자, 영문 2,000자 제한

type

string

메시지 타입

country

string

국가번호 (기본: 82, 미국(캐나다):1, 중국: 86, 일본: 81)

subject

string

메시지 제목 한글 20자, 영문 40자 제한

imageId

string

Storage API에 등록된 이미지 아이디 참고

kakaoOptions

object

친구톡, 알림톡을 보내기 위한 옵션

naverOptions

object

네이버 스마트 알림을 보내기 위한 옵션

rcsOptions

object

설명 없음

customFields

object

확장 필드로 사용. 키는 30자, 값은 100자 제한

autoTypeDetect

boolean

타입 설정이 없을 경우 자동으로 설정함. 기본 값은 true

replacementText

string

설명 없음

Body / messages / kakaoOptions

Name
Type
Required
Description

pfId

string

테스트에서 발급된 카카오톡 채널의 연동 아이디

pfGroupId

string

설명 없음

templateId

string

알림톡 템플릿 아이디

disableSms

boolean

대체 발송 여부

imageId

string

Storage API에 등록된 이미지 아이디 참고

buttons

array

알림톡 템플릿 버튼 목록

title

string

설명 없음

Body / messages / kakaoOptions / buttons

Name
Type
Required
Description

buttonName

string

O

버튼 이름

buttonType

string

O

버튼 종류(AL: 앱링크, WL: 웹링크, DS: 배송조회, BK: 키워드, MD: 전달

linkMo

string

모바일 링크(WL 웹링크)

linkPc

string

웹 링크(WL 웹링크)

linkAnd

string

안드로이드 링크(AL 앱링크)

linkIos

string

IOS 링크(AL 앱링크)

Body / messages / naverOptions

Name
Type
Required
Description

talkId

string

설명 없음

templateId

string

알림톡 템플릿 아이디

disableSms

boolean

대체 발송 여부

buttons

array

네이버 스마트 알림 템플릿 버튼 목록

Body / messages / naverOptions / buttons

Name
Type
Required
Description

buttonType

string

O

설명 없음

linkMo

string

모바일 링크

linkPc

string

웹 링크

Body / messages / rcsOptions

Name
Type
Required
Description

brandId

string

설명 없음

templateId

string

알림톡 템플릿 아이디

copyAllowed

boolean

설명 없음

variables

object

설명 없음

commercialType

boolean

설명 없음

mmsType

string

설명 없음

disableSms

boolean

대체 발송 여부

additionalBody

array

설명 없음

buttons

array

설명 없음

Body / messages / rcsOptions / variables

Body / messages / rcsOptions / additionalBody

Name
Type
Required
Description

title

string

O

설명 없음

description

string

O

설명 없음

imageId

string

Storage API에 등록된 이미지 아이디 참고

buttons

array

설명 없음

Body / messages / rcsOptions / additionalBody / buttons

Name
Type
Required
Description

buttonType

string

O

설명 없음

link

string

설명 없음

latitude

string

설명 없음

longitude

string

설명 없음

label

string

설명 없음

query

string

설명 없음

title

string

설명 없음

startTime

date

설명 없음

endTime

date

설명 없음

text

string

메시지 내용 한글 1,000자, 영문 2,000자 제한

phone

string

설명 없음

Body / messages / rcsOptions / buttons

Name
Type
Required
Description

buttonType

string

O

설명 없음

link

string

설명 없음

latitude

string

설명 없음

longitude

string

설명 없음

label

string

설명 없음

query

string

설명 없음

title

string

설명 없음

startTime

date

설명 없음

endTime

date

설명 없음

text

string

메시지 내용 한글 1,000자, 영문 2,000자 제한

phone

string

설명 없음

Body / messages / customFields

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

메시지 타입

country

string

O

국가번호 (기본: 82, 미국(캐나다):1, 중국: 86, 일본: 81)

messageId

string

O

메시지 아이디

statusCode

string

O

상태 코드 참고

statusMessage

string

O

상태 메시지 참고

accountId

string

O

계정 고유 아이디

Samples

단문문자(SMS) 추가

Sample Request

{
    "messages": [
        {
            "to": "01000000001",
            "from": "0098615016338676",
            "text": "test message",
            "type": "SMS"
        }
    ]
}

Sample Response

{
    "errorCount": 0,
    "resultList": [
        {
            "to": "01000000001",
            "from": "0098615016338676",
            "type": "SMS",
            "statusMessage": "정상 접수(이통사로 접수 예정) ",
            "country": "82",
            "messageId": "M4V20211116140940SD3L5M1RW2DRI6V",
            "statusCode": "2000",
            "accountId": "12925149"
        }
    ]
}

Sample Code

var request = require('request');

var options = {
  headers: {
    Authorization:
      'HMAC-SHA256 apiKey=NCSAYU7YDBXYORXC, date=2019-07-01T00:41:48Z, salt=jqsba2jxjnrjor, signature=1779eac71a24cbeeadfa7263cb84b7ea0af1714f5c0270aa30ffd34600e363b4',
    'Content-Type': 'application/json'
  },
  body: {
    messages: [
      {
        to: '01000000001',
        from: '0098615016338676',
        text: 'test message',
        type: 'SMS'
      }
    ]
  },
  method: 'PUT',
  json: true,
  url:
    'http://api.solapi.com/messages/v4/groups/G4V20190607105937H3PFASXMNJG2JID/messages'
};

request(options, function(error, response, body) {
  if (error) throw error;
  console.log('result :', body);
});

장문문자(LMS) 추가

Sample Request

{
    "messages": [
        {
            "subject": "testSubject",
            "to": "01000000001",
            "from": "029302266",
            "text": "lms test message",
            "type": "LMS"
        }
    ]
}

Sample Response

{
    "errorCount": 0,
    "resultList": [
        {
            "to": "01000000001",
            "from": "029302266",
            "type": "LMS",
            "statusMessage": "정상 접수(이통사로 접수 예정) ",
            "country": "82",
            "messageId": "M4V20211116140940U8RCGHWDTQEVSNT",
            "statusCode": "2000",
            "accountId": "12925149"
        }
    ]
}

Sample Code

var request = require('request');

var options = {
  headers: {
    Authorization:
      'HMAC-SHA256 apiKey=NCSAYU7YDBXYORXC, date=2019-07-01T00:41:48Z, salt=jqsba2jxjnrjor, signature=1779eac71a24cbeeadfa7263cb84b7ea0af1714f5c0270aa30ffd34600e363b4',
    'Content-Type': 'application/json'
  },
  body: {
    messages: [
      {
        subject: 'testSubject',
        to: '01000000001',
        from: '029302266',
        text: 'lms test message',
        type: 'LMS'
      }
    ]
  },
  method: 'PUT',
  json: true,
  url:
    'http://api.solapi.com/messages/v4/groups/G4V20190607105937H3PFASXMNJG2JID/messages'
};

request(options, function(error, response, body) {
  if (error) throw error;
  console.log('result :', body);
});

포토문자(MMS) 추가

Sample Request

{
    "messages": [
        {
            "subject": "testSubject",
            "to": "01000000002",
            "from": "029302266",
            "text": "mms test message",
            "type": "MMS",
            "imageId": "TESTIMAGEID"
        }
    ]
}

Sample Response

{
    "errorCount": 0,
    "resultList": [
        {
            "to": "01000000002",
            "from": "029302266",
            "type": "MMS",
            "statusMessage": "정상 접수(이통사로 접수 예정) ",
            "country": "82",
            "messageId": "M4V20211116140940VRVU5VEWWXHTAS9",
            "statusCode": "2000",
            "accountId": "12925149"
        }
    ]
}

Sample Code

var request = require('request');

var options = {
  headers: {
    Authorization:
      'HMAC-SHA256 apiKey=NCSAYU7YDBXYORXC, date=2019-07-01T00:41:48Z, salt=jqsba2jxjnrjor, signature=1779eac71a24cbeeadfa7263cb84b7ea0af1714f5c0270aa30ffd34600e363b4',
    'Content-Type': 'application/json'
  },
  body: {
    messages: [
      {
        subject: 'testSubject',
        to: '01000000002',
        from: '029302266',
        text: 'mms test message',
        type: 'MMS',
        imageId: 'TESTIMAGEID'
      }
    ]
  },
  method: 'PUT',
  json: true,
  url:
    'http://api.solapi.com/messages/v4/groups/G4V20190607105937H3PFASXMNJG2JID/messages'
};

request(options, function(error, response, body) {
  if (error) throw error;
  console.log('result :', body);
});

알림톡(ATA) 추가

Sample Request

{
    "messages": [
        {
            "to": "01000000003",
            "from": "029302266",
            "text": "#{홍길동}님이 요청하신 출금 요청 처리가 완료되어 아래 정보로 입금 처리되었습니다.\n\n#{입금정보}\n\n관련하여 문의 있으시다면'1:1문의하기'를이용부탁드립니다.\n\n감사합니다.",
            "type": "ATA",
            "kakaoOptions": {
                "pfId": "KA01PF190227072057634pRBhbpAw1w1",
                "templateId": "test_2019030716320324334488006",
                "buttons": [
                    {
                        "buttonName": "앱 링크",
                        "buttonType": "AL",
                        "linkIos": "custom://scheme/test",
                        "linkAnd": "http://#{url}"
                    },
                    {
                        "buttonName": "웹 링크",
                        "buttonType": "WL",
                        "linkMo": "https://www.example.com"
                    },
                    {
                        "buttonName": "배송조회",
                        "buttonType": "DS"
                    },
                    {
                        "buttonName": "키워드",
                        "buttonType": "BK"
                    },
                    {
                        "buttonName": "전달",
                        "buttonType": "MD"
                    }
                ]
            }
        }
    ]
}

Sample Response

{
    "errorCount": 0,
    "resultList": [
        {
            "to": "01000000003",
            "from": "029302266",
            "type": "ATA",
            "statusMessage": "정상 접수(이통사로 접수 예정) ",
            "country": "82",
            "messageId": "M4V20211116140940XH4SPZIOMDYPWX9",
            "statusCode": "2000",
            "accountId": "12925149"
        }
    ]
}

Sample Code

var request = require('request');

var options = {
  headers: {
    Authorization:
      'HMAC-SHA256 apiKey=NCSAYU7YDBXYORXC, date=2019-07-01T00:41:48Z, salt=jqsba2jxjnrjor, signature=1779eac71a24cbeeadfa7263cb84b7ea0af1714f5c0270aa30ffd34600e363b4',
    'Content-Type': 'application/json'
  },
  body: {
    messages: [
      {
        to: '01000000003',
        from: '029302266',
        text:
          "#{홍길동}님이 요청하신 출금 요청 처리가 완료되어 아래 정보로 입금 처리되었습니다.\n\n#{입금정보}\n\n관련하여 문의 있으시다면'1:1문의하기'를이용부탁드립니다.\n\n감사합니다.",
        type: 'ATA',
        kakaoOptions: {
          pfId: 'KA01PF190227072057634pRBhbpAw1w1',
          templateId: 'test_2019030716320324334488006',
          buttons: [
            {
              buttonName: '앱 링크',
              buttonType: 'AL',
              linkIos: 'custom://scheme/test',
              linkAnd: 'http://#{url}'
            },
            {
              buttonName: '웹 링크',
              buttonType: 'WL',
              linkMo: 'https://www.example.com'
            },
            {
              buttonName: '배송조회',
              buttonType: 'DS'
            },
            {
              buttonName: '키워드',
              buttonType: 'BK'
            },
            {
              buttonName: '전달',
              buttonType: 'MD'
            }
          ]
        }
      }
    ]
  },
  method: 'PUT',
  json: true,
  url:
    'http://api.solapi.com/messages/v4/groups/G4V20190607105937H3PFASXMNJG2JID/messages'
};

request(options, function(error, response, body) {
  if (error) throw error;
  console.log('result :', body);
});

친구톡(CTA) 추가

Sample Request

{
    "messages": [
        {
            "to": "01000000004",
            "from": "029302266",
            "text": "cta test message",
            "type": "CTA",
            "kakaoOptions": {
                "pfId": "KA01PF190227072057634pRBhbpAw1w1"
            }
        }
    ]
}

Sample Response

{
    "errorCount": 0,
    "resultList": [
        {
            "to": "01000000004",
            "from": "029302266",
            "type": "CTA",
            "statusMessage": "정상 접수(이통사로 접수 예정) ",
            "country": "82",
            "messageId": "M4V20211116140940HIFSMRUYS6YCT3V",
            "statusCode": "2000",
            "accountId": "12925149"
        }
    ]
}

Sample Code

var request = require('request');

var options = {
  headers: {
    Authorization:
      'HMAC-SHA256 apiKey=NCSAYU7YDBXYORXC, date=2019-07-01T00:41:48Z, salt=jqsba2jxjnrjor, signature=1779eac71a24cbeeadfa7263cb84b7ea0af1714f5c0270aa30ffd34600e363b4',
    'Content-Type': 'application/json'
  },
  body: {
    messages: [
      {
        to: '01000000004',
        from: '029302266',
        text: 'cta test message',
        type: 'CTA',
        kakaoOptions: {
          pfId: 'KA01PF190227072057634pRBhbpAw1w1'
        }
      }
    ]
  },
  method: 'PUT',
  json: true,
  url:
    'http://api.solapi.com/messages/v4/groups/G4V20190607105937H3PFASXMNJG2JID/messages'
};

request(options, function(error, response, body) {
  if (error) throw error;
  console.log('result :', body);
});

친구톡 이미지 (CTI) 추가

Sample Request

{
    "messages": [
        {
            "to": "01000000004",
            "from": "029302266",
            "text": "cta test message",
            "type": "CTI",
            "kakaoOptions": {
                "pfId": "KA01PF190227072057634pRBhbpAw1w1",
                "imageId": "FILEID191113003354156UvCuw3tubTl"
            }
        }
    ]
}

Sample Response

{
    "errorCount": 0,
    "resultList": [
        {
            "to": "01000000004",
            "from": "029302266",
            "type": "CTI",
            "statusMessage": "정상 접수(이통사로 접수 예정) ",
            "country": "82",
            "messageId": "M4V20211116140940JK8UJ4JL9VJLWLZ",
            "statusCode": "2000",
            "accountId": "12925149"
        }
    ]
}

Sample Code

var request = require('request');

var options = {
  headers: {
    Authorization:
      'HMAC-SHA256 apiKey=NCSAYU7YDBXYORXC, date=2019-07-01T00:41:48Z, salt=jqsba2jxjnrjor, signature=1779eac71a24cbeeadfa7263cb84b7ea0af1714f5c0270aa30ffd34600e363b4',
    'Content-Type': 'application/json'
  },
  body: {
    messages: [
      {
        to: '01000000004',
        from: '029302266',
        text: 'cta test message',
        type: 'CTI',
        kakaoOptions: {
          pfId: 'KA01PF190227072057634pRBhbpAw1w1',
          imageId: 'FILEID191113003354156UvCuw3tubTl'
        }
      }
    ]
  },
  method: 'PUT',
  json: true,
  url:
    'http://api.solapi.com/messages/v4/groups/G4V20190607105937H3PFASXMNJG2JID/messages'
};

request(options, function(error, response, body) {
  if (error) throw error;
  console.log('result :', body);
});

커스텀 필드 사용

Sample Request

{
    "messages": [
        {
            "to": "01000000004",
            "from": "029302266",
            "text": "cta test message",
            "type": "CTA",
            "kakaoOptions": {
                "pfId": "KA01PF190227072057634pRBhbpAw1w1"
            },
            "customFields": {
                "customerId": "ID-123456789",
                "customerName": "홍길동",
                "customMsgId": "MSG-ID-123456"
            }
        }
    ]
}

Sample Response

{
    "errorCount": 0,
    "resultList": [
        {
            "to": "01000000004",
            "from": "029302266",
            "type": "CTA",
            "statusMessage": "정상 접수(이통사로 접수 예정) ",
            "country": "82",
            "messageId": "M4V20211116140940PFSHKJVXGXRWKMX",
            "statusCode": "2000",
            "accountId": "12925149",
            "customFields": {
                "customerId": "ID-123456789",
                "customerName": "홍길동",
                "customMsgId": "MSG-ID-123456"
            }
        }
    ]
}

Sample Code

var request = require('request');

var options = {
  headers: {
    Authorization:
      'HMAC-SHA256 apiKey=NCSAYU7YDBXYORXC, date=2019-07-01T00:41:48Z, salt=jqsba2jxjnrjor, signature=1779eac71a24cbeeadfa7263cb84b7ea0af1714f5c0270aa30ffd34600e363b4',
    'Content-Type': 'application/json'
  },
  body: {
    messages: [
      {
        to: '01000000004',
        from: '029302266',
        text: 'cta test message',
        type: 'CTA',
        kakaoOptions: {
          pfId: 'KA01PF190227072057634pRBhbpAw1w1'
        },
        customFields: {
          customerId: 'ID-123456789',
          customerName: '홍길동',
          customMsgId: 'MSG-ID-123456'
        }
      }
    ]
  },
  method: 'PUT',
  json: true,
  url:
    'http://api.solapi.com/messages/v4/groups/G4V20190607105937H3PFASXMNJG2JID/messages'
};

request(options, function(error, response, body) {
  if (error) throw error;
  console.log('result :', body);
});

to가 String일 경우

Sample Request

{
    "messages": [
        {
            "to": "01000000001",
            "from": "029302266",
            "text": "test message",
            "autoTypeDetect": true
        }
    ]
}

Sample Response

{
    "errorCount": 0,
    "resultList": [
        {
            "to": "01000000001",
            "from": "029302266",
            "type": "SMS",
            "statusMessage": "정상 접수(이통사로 접수 예정) ",
            "country": "82",
            "messageId": "M4V2021111614094048XSXSW8I6HWRFT",
            "statusCode": "2000",
            "accountId": "12925149"
        }
    ]
}

Sample Code

var request = require('request');

var options = {
  headers: {
    Authorization:
      'HMAC-SHA256 apiKey=NCSAYU7YDBXYORXC, date=2019-07-01T00:41:48Z, salt=jqsba2jxjnrjor, signature=1779eac71a24cbeeadfa7263cb84b7ea0af1714f5c0270aa30ffd34600e363b4',
    'Content-Type': 'application/json'
  },
  body: {
    messages: [
      {
        to: '01000000001',
        from: '029302266',
        text: 'test message',
        autoTypeDetect: true
      }
    ]
  },
  method: 'PUT',
  json: true,
  url:
    'http://api.solapi.com/messages/v4/groups/G4V20190607105937H3PTASXMNJG2JID/messages'
};

request(options, function(error, response, body) {
  if (error) throw error;
  console.log('result :', body);
});

to가 Array일 경우

Sample Request

{
    "messages": [
        {
            "to": [
                "01000000001",
                "01000000002"
            ],
            "from": "029302266",
            "text": "test message",
            "autoTypeDetect": true
        }
    ]
}

Sample Response

{
    "errorCount": 0,
    "resultList": [
        {
            "to": "01000000001",
            "from": "029302266",
            "type": "SMS",
            "statusMessage": "정상 접수(이통사로 접수 예정) ",
            "country": "82",
            "messageId": "M4V20211116140941AU30LAD3RLYALDM",
            "statusCode": "2000",
            "accountId": "12925149"
        },
        {
            "to": "01000000002",
            "from": "029302266",
            "type": "SMS",
            "statusMessage": "정상 접수(이통사로 접수 예정) ",
            "country": "82",
            "messageId": "M4V20211116140941Q2KKW0TQMC2TUSC",
            "statusCode": "2000",
            "accountId": "12925149"
        }
    ]
}

Sample Code

var request = require('request');

var options = {
  headers: {
    Authorization:
      'HMAC-SHA256 apiKey=NCSAYU7YDBXYORXC, date=2019-07-01T00:41:48Z, salt=jqsba2jxjnrjor, signature=1779eac71a24cbeeadfa7263cb84b7ea0af1714f5c0270aa30ffd34600e363b4',
    'Content-Type': 'application/json'
  },
  body: {
    messages: [
      {
        to: ['01000000001', '01000000002'],
        from: '029302266',
        text: 'test message',
        autoTypeDetect: true
      }
    ]
  },
  method: 'PUT',
  json: true,
  url:
    'http://api.solapi.com/messages/v4/groups/G4V20190607105937H3PTASXMNJG2JID/messages'
};

request(options, function(error, response, body) {
  if (error) throw error;
  console.log('result :', body);
});

to가 String인 경우와 Array인 경우가 합쳐진 경우

Sample Request

{
    "messages": [
        {
            "to": [
                "01000000001",
                "01000000002"
            ],
            "from": "029302266",
            "text": "test message",
            "autoTypeDetect": true
        },
        {
            "to": "01000000001",
            "from": "029302266",
            "text": "test message",
            "autoTypeDetect": true
        }
    ]
}

Sample Response

{
    "errorCount": 1,
    "resultList": [
        {
            "to": "01000000001",
            "from": "029302266",
            "type": "SMS",
            "statusMessage": "정상 접수(이통사로 접수 예정) ",
            "country": "82",
            "messageId": "M4V20211116140942SGF1FP1RYI9DXVZ",
            "statusCode": "2000",
            "accountId": "12925149"
        },
        {
            "to": "01000000002",
            "from": "029302266",
            "type": "SMS",
            "statusMessage": "정상 접수(이통사로 접수 예정) ",
            "country": "82",
            "messageId": "M4V202111161409426QMUPMTPA4BCYXT",
            "statusCode": "2000",
            "accountId": "12925149"
        },
        {
            "to": "01000000001",
            "from": "029302266",
            "type": "SMS",
            "statusMessage": "중복 수신번호",
            "country": "82",
            "messageId": "M4V20211116140942XEVQD6DN86SDJAE",
            "statusCode": "1026",
            "accountId": "12925149"
        }
    ]
}

Sample Code

var request = require('request');

var options = {
  headers: {
    Authorization:
      'HMAC-SHA256 apiKey=NCSAYU7YDBXYORXC, date=2019-07-01T00:41:48Z, salt=jqsba2jxjnrjor, signature=1779eac71a24cbeeadfa7263cb84b7ea0af1714f5c0270aa30ffd34600e363b4',
    'Content-Type': 'application/json'
  },
  body: {
    messages: '[object Object],[object Obj...'
  },
  method: 'PUT',
  json: true,
  url:
    'http://api.solapi.com/messages/v4/groups/G4V20190607105937H3PTASXMNJG2JID/messages'
};

request(options, function(error, response, body) {
  if (error) throw error;
  console.log('result :', body);
});

문서 생성일 : 2021-11-16

Previous그룹 생성Next그룹 메시지 목록 조회

Last updated

Was this helpful?