Comment on page
SMS API Version 2
이 문서는 REST기반의 문자메시지(국내,해외문자,알림톡,친구톡) API로 예약 문자를 포함한 문자전송, 전송된 문자의 상태 확인, 잔액정보 및 예약취소 등의 작업을 요청하는 방법을 기술하고 있습니다. PHP, Java, Python, Delphi, C 등 다양한 언어로 구현된 샘플을 SDK 페이지에서 제공하고 있습니다..
인증을 위한 API Key 및 API Secret 코드는 문자메시지 > 환경설정 > API Key 관리 메뉴에서 발급 및 관리가 가능합니다. API Key 관리 문서를 참고하세요.
아래는 각 Resource의 역할을 테이블로 정리하였습니다. 상세한 설명을 보시려면 해당 Resource를 클릭하여 주세요.
Part | Resource | Description |
그룹메시지 | 그룹 생성 | |
그룹 목록 | | |
그룹 삭제 | | |
그룹 정보 리턴 | | |
메시지 추가 | | |
JSON형식으로 메시지 추가 | | |
추가된 메시지 목록 | | |
메시지 삭제 | | |
메시지 발송 | | |
이미지 | 이미지 업로드 | |
이미지 목록 | | |
이미지 정보 | | |
이미지 | | |
기타 | 문자발송 요청 | |
발송된 문자정보 조회 | | |
예약문자 취소 | | |
전액정보 조회 | | |
전송채널 상태 조회 | |
Version | Description |
1.1 | Android 누리고 푸시 지원
1만건 전송을 40초 이하로 단축 후불제 회원 지원 |
1.2 | iOS 누리고 푸시 지원
1만건 전송을 20초 이하로 단축 |
1.3 | 쿨서포터즈 정책 지원 반영 |
1.4 | status 리소스에 시간별, 일별 전송현황을 위한 date, unit 필드 추가 |
1.5 | Agent 정보 전송 |
1.6 | 카카오 알림톡 기능 추가 |
2.0 | 그룹 메시징 추가 |
대용량의 메시지를 안전하고 빠르게 전송하도록 그룹메시지를 위한 API를 제공합니다.
아래의 API 호출 흐름으로 대량의 그룹메시지를 보낼 수 있습니다.
new_group -> add_messages -> send
new_group 호출로 메시지를 담을 그룹을 생성하고 리턴된 그룹아이디를 키로 add_messages 호출로 메시지를 접수하고 send 호출로 접수된 메시지를 서버단에 전송을 수행합니다. 이로 인해 한번 접수된 메시지는 유실 없이 안정적으로 발송이 보장됩니다.
메시지를 담을 그룹을 생성하여 그룹아이디를 리턴합니다.
Mandatory | Field | Description |
Ο | 인증정보 | |
| charset | 한글 인코딩 방식을 지정합니다.
유니코드 UTF-8 일 경우 utf8,
완성형 한글(EUC-KR) 일 경우 euckr 으로 입력,
입력 없으면 utf8가 기본 |
| srk | |
| mode (현재 미지원) | test로 입력할 경우 CARRIER 시뮬레이터로 시뮬레이션됩니다. ** 수신번호를 반드시 01000000000 으로 테스트 **
예약필드 datetime는 무시됩니다. 결과값은 60 잔액에서 실제 차감되며 다음날 새벽에 재충전됩니다. |
| force_sms (현재 미지원) | 누리고푸시를 사용하더라도 강제로 문자 발송. true 혹은 false(기본) |
| only_ | 알림톡이 실패해도 문자메시지로 대체하여 발송하지 않습니다.
true 혹은 false(기본) |
| site_user | API를 호출하는 사이트에서 관리하는 유저 아이디 입력. 미입력시 __private__ 으로 입력됩니다.
해당 아이디 앞으로 등록된 발신번호를 확인합니다.
발신번호 등록 API를 참고하세요.
http://developer.coolsms.co.kr/SenderID_API |
| os_platform | 클라이언트의 OS 및 플랫폼 버전 예) CentOS 6.6 (v1.5에서 추가됨) |
| dev_lang | 개발 프로그래밍 언어 예) PHP 5.3.3 (v1.5에서 추가됨) |
| sdk_version | SDK 버전 예) PHP SDK 1.5 (v1.5에서 추가됨) |
| app_version | 어플리케이션 버전 예) Purplebook 4.1 (v1.5에서 추가됨) |
JSON 포맷으로 리턴 됩니다.
Mandatory | Field | Description |
O | group_id | 그룹 아이디 |
curl -XGET 'https://api.coolsms.co.kr/sms/2/new_group?api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a×tamp=1456364125'
{
"group_id":"565ba3d7d216a"
}
생성된 그룹 목록을 리턴합니다.
Mandatory | Field | Description |
Ο | 인증정보 |
JSON 포맷으로 리턴 됩니다.
Mandatory | Field | Description |
O | - | array 형식의 그룹아이디 목록 리턴 |
curl -XGET 'https://api.coolsms.co.kr/sms/2/group_list?api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a×tamp=1456364125'
[
"565ba3d7d216a",
"565ba3dea161b"
]
그룹을 삭제합니다. 담겨 있는 메시지도 함께 삭제됩니다.
Mandatory | Field | Description |
Ο | 인증정보 | |
O | group_ids | 삭제할 그룹 아이디 콤마(,)로 구분된 아이디 목록 입력 가능 |
JSON 포맷으로 리턴 됩니다.
Mandatory | Field | Description |
O | success_count | 삭제된 그룹 갯수 |
O | error_count | 오류 처리된 그룹 갯수 |
O | error_list | 오류 내역
["{인덱스}": "{오류코드}", ...] 형식 |
curl -XPOST 'https://api.coolsms.co.kr/sms/2/delete_groups' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a×tamp=1456364125&group_ids=565ba3d7d216a'
{
"success_count": 3,
"error_count": 2,
"error_list": [
4: "62",
5: "54"
]
}
그룹 정보를 리턴합니다.
Mandatory | Field | Description |
Ο | 인증정보 | |
O | group_id | 그룹 아이디 |
JSON 포맷으로 리턴 됩니다.
Mandatory | Field | Description |
O | group_id | 그룹 아이디 |
O | message_count | 그룹에 담긴 메시지 갯수 |
curl -XGET 'https://api.coolsms.co.kr/sms/2/groups/{group_id}' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a×tamp=1456364125&group_id=565ba3d7d216a'
{
"group_id":"565ba3d7d216a",
"message_count":970
}
그룹에 발송할 문자메시지를 추가합니다.
Mandatory | Field | Description |
Ο | 인증정보 | |
O | to | 수신번호 입력
콤마(,)로 구분된 수신번호 입력가능
예) 01012345678,01023456789,01034567890 |
O | from | 발신번호 입력
2015/10/16 발신번호 사전등록제에 의해 반드시 등록된 번호만 허용됩니다. (해외문자 제외)
예) 0212345678 |
O | text | 문자내용 |
| type | CTA(친구톡), ATA(알림톡), SMS(90바이트), LMS(장문 2,000바이트), MMS(장문+이미지)
미입력시 SMS
해외문자인 경우 SMS만 가능 |
| image_id | 발송할 이미지의 아이디 type이 MMS일 때 필수 |
| refname | 참조내용(이름) |
| country | 한국: 82, 일본: 81, 중국: 86, 미국: 1, 기타 등등 (기본 한국) |
| datetime | 예약시간을 YYYYMMDDHHMISS 포맷으로 입력 (입력 없거나 지난날짜를 입력하면 바로 전송)
예) 20131216090510 (2013년 12월 16일 9시 5분 10초에 발송되도록 예약) |
| subject | LMS, MMS 일때 제목 (40바이트) |
| template_code | 알림톡 Template Code |
| sender_key | 알림톡 Sender Key |
| button_name | 알림톡&친구톡 버튼이름 |
| button_url | 알림톡&친구톡 버튼URL |
제한 사항
to 필드의 전화번호 수는 최대 1,000개이며 넘을 경우 오류를 발생 (RecipientsTooMany)
한번의 Request의 총 데이터 크기는 2MB를 넘을 수 없습니다 (HTTP ERROR 413 발생)
발송형태별 제한사항
이동통신사 내부적으로 완성형한글로 변환되므로 영어 1바이트, 한글 2바이트로 취급됩니다.
구분 | 제한사항 |
SMS | 90바이트 까지 전송가능 (한글 45자) |
LMS | 2,000바이트 까지 전송가능 (한글 1,000자) |
MMS | 2,000바이트 텍스트 (한글 1,000자) 1개의 이미지 전송 (300KB. 2048x2048픽셀 이하인 JPEG, PNG, GIF 형식 파일) |
ATA | 카카오톡 알림톡으로 1,000자까지 발송, 친구등록이 안되어있는 계정에게도 발송가능 |
CTA | 카카오톡 찬구톡으로 1,000자까지 발송, 친구등록이 되어있어야 발송가능 |
JSON 포맷으로 리턴 됩니다.
Mandatory | Field | Description |
O | success_count | 접수 성공 갯수 |
O | error_count | 접수 오류 갯수 |
| error_list | 오류 발생 문자메시지 아이디 목록
["{인덱스}": "{오류코드}", ...] 형식
인덱스값은 0부터 시작 |
curl -XPOST https://api.coolsms.co.kr/sms/2/groups/GID565bA3D7D216A/add_messages -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a×tamp=1456364125&to=01012345678&from=029302266&text=Hello'
{
"success_count": 3,
"error_count": 2,
"error_list": [
0: "62",
4: "54"
]
}
추가하신 메시지의 전체 개수가 success_count로 리턴되면 정상적으로 서버에 접수 완료된 것이며, 에러가 발생한 메시지는 error count 와 error_list 가 리턴됩니다.
리턴된 error_code의 정보는 http://developer.coolsms.co.kr/Legacy_Result_Codes 을 참고하시면 됩니다. 여기서 리턴되는 Response의 내용은 서버에 전송 요청한 것에 대한 정보이며 실제 휴대전화로 전송한 것에 대한 정보가 아닙니다. sent 조회로 실제 전송된 결과를 확인하실 수 있습니다.
그룹에 발송할 문자메시지를 JSON 형식으로 접수합니다. 대량의 문자를 각각 다른 내용과 타입으로 보내고 싶을 때 용이 합니다.
Mandatory | Field | Description |
Ο | 인증정보 | |
O | messages | JSON 형식의 메시지 데이터 |
JSON Fields
Mandatory | Field | Description |
O | to | 수신번호 입력
콤마(,)로 구분된 수신번호 입력가능
예) 01012345678,01023456789,01034567890 |
O | from | 발신번호 입력
2015/10/16 발신번호 사전등록제에 의해 반드시 등록된 번호만 허용됩니다. (해외문자 제외)
예) 0212345678 |
O | text | 문자내용 |
| type | ATA(알림톡), CTA(친구톡), SMS(90바이트), LMS(장문 2,000바이트), MMS(장문+이미지)
미입력시 SMS
해외문자인 경우 SMS만 가능 |
| image_id | 발송할 이미지의 아이디 type이 MMS일 때 필수 |
| refname | 참조내용(이름) |
| country | 한국: 82, 일본: 81, 중국: 86, 미국: 1, 기타 등등 (기본 한국) |
| datetime | 예약시간을 YYYYMMDDHHMISS 포맷으로 입력 (입력 없거나 지난날짜를 입력하면 바로 전송)
예) 20131216090510 (2013년 12월 16일 9시 5분 10초에 발송되도록 예약) |
| subject | LMS, MMS 일때 제목 (40바이트) |
| template_code | 알림톡 Template Code |
| sender_key | 알림톡 Sender Key |
[ ] 안에 { } 가 여러 개 들어 갈 수 있는 구조로 되어있으며 각각의 { } 안에는 to, from, text 필드가 필수요소입니다.
[
{
"type": "SMS",
"to": "01000000000,01011111111,01022222222",
"from": "021234567",
"text": "Hello A"
},
{
"type": "LMS",
"to": "01000000000,01011111111,01022222222",
"from": "021234567",
"text": "Hello B"
"subject": "LMS Subject",
},
{
"type": "MMS",
"to": "01000000000,01011111111,01022222222",
"from": "021234567",
"text": "Hello C",
"subject": "MMS Subject",
"image_id": "abcdefg"
}
]
제한 사항
수신받을 전화번호 총 수(to 필드 전화번호 합계)는 최대 1,000개이며 넘을 경우 오류 발생. (RecipientsTooMany)
한번의 Request의 총 데이터 크기는 2MB를 넘을 수 없습니다 (HTTP ERROR 413 발생)
발송형태에 따른 제한사항
이동통신사 내부적으로 완성형한글로 변환되므로 영어 1바이트, 한글 2바이트로 취급됩니다.
구분 | 제한사항 |
SMS | 90바이트 까지 전송가능 (한글 45자) |
LMS | 2,000바이트 까지 전송가능 (한글 1,000자) |
MMS | 2,000바이트 텍스트 (한글 1,000자) 1개의 이미지 전송 (300KB. 2048x2048픽셀 이하인 JPEG, PNG, GIF 형식 파일) |
ATA | 카카오톡 알림톡으로 1,000자까지 발송, 친구등록이 안되어있는 계정에게도 발송가능 |
CTA | 카카오톡 찬구톡으로 1,000자까지 발송, 친구등록이 되어있어야 발송가능 |
Mandatory | Field | Description |
O | success_count | 접수 성공 갯수 |
O | error_count | 접수 오류 갯수 |
| error_list | 오류 발생 문자메시지 아이디 목록
["{인덱스}": "{오류코드}", ...] 형식
인덱스값은 0부터 시작 |
curl -XPOST https://api.coolsms.co.kr/sms/2/groups/565ba3d7d216a/add_messages -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a×tamp=1456364125&messages=JSONArray
[
{
"success_count": 3,
"error_count": 0,
},
{
"success_count": 1,
"error_count": 2,
"error_list": [
0: "62",
1: "54"
]
},
{
"success_count": 3,
"error_count": 0,
}
]
추가하신 메시지의 전체 개수가 success_count로 리턴되면 정상적으로 서버에 접수 완료된 것이며, 에러가 발생한 메시지는 error count 와 error_list 가 리턴됩니다.
리턴된 error_code의 정보는 http://www.coolsms.co.kr/Legacy_Result_Codes 을 참고하시면 됩니다. 여기서 리턴되는 Response의 내용은 서버에 전송 요청한 것에 대한 정보이며 실제 휴대전화로 전송한 것에 대한 정보가 아닙니다. sent 조회로 실제 전송된 결과를 확인하실 수 있습니다.
문자메시지 목록을 리턴합니다.
Mandatory | Field | Description |
Ο | 인증정보 | |
| offset | 조회할 목록의 시작 위치 Default) 0 |
| limit | 가져올 메시지의 갯수 Default) 20 |
JSON 포맷으로 리턴 됩니다.
Mandatory | Field | Description |
O | total_count | 전체 메시지 갯수 |
O | offset | 조회 목록의 시작 위치 |
O | limit | 가져올 메시지의 갯수 |
O | list | Array 형식의 메시지 목록 |
curl -XGET 'https://api.coolsms.co.kr/sms/2/groups/{group_id}/message_list' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a×tamp=1456364125'
{
"total_count":2,
"offset":0,
"limit":20,
"list":[
"565ba4e7d316b",
"565ab383dabcd"
]
}
그룹에 추가된 메시지를 삭제합니다.
Mandatory | Field | Description |
Ο | 인증정보 | |
O | message_ids | 콤마로 구분된 삭제할 메시지 아이디 목록 ex) MID565BA6D7E325C,MID565433E7D233A |
JSON 포맷으로 리턴 됩니다.
Mandatory | Field | Description |
O | success_count | 삭제 성공 갯수 |
O | error_count | 오류 갯수 |
| error_list | 오류 발생 코드 목록
["{인덱스}": "{오류코드}", ...] 형식
인덱스값은 0부터 시작 |
curl -XPOST 'https://api.coolsms.co.kr/sms/2/groups/{group_id}/delete_messages' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a×tamp=1456364125&message_ids=MID565BA6D7E325C,MID565433E7D233A,MID565643A66AB21'
서버는 json 포맷으로 삭제된 갯수를 리턴합니다.
{
"success_count": 1,
"error_count": 2,
"error_list": [
0: "1021",
2: "1021"
]
}
그룹메시지를 전송 요청합니다.
Mandatory | Field | Description |
Ο | 인증정보 |
JSON 포맷으로 리턴 됩니다.
Mandatory | Field | Description |
O | group_id | 전송 요청된 그룹 아이디 |
curl -XPOST 'https://api.coolsms.co.kr/sms/2/groups/{group_id}/send' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a×tamp=1456364125'
{
"group_id": "565ba3d7d216a"
}
이미지를 서버에 안전하게 미리 업로드하여 문자발송 때 사용할 수 있어 더욱 안정적인 발송을 보장합니다.
MMS 발송에 필요한 이미지 파일을 업로드 합니다.
MMS 발송 때 미리 업로드 된 이미지 파일을 사용하므로 발송과정에서 발생하는 오류률 현저히 줄어듭니다.
이미지 보관 기간은 7일입니다.
Mandatory | Field | Description |
Ο | 인증정보 | |
O | image | 이미지 내용 (파일명이 아니라 내용입니다.)
Form Submit 옵션 : method=POST enc-type=multipart/form
제한사항) 300KB, 2048x2048 이하, JPEG, PNG, GIF |
| image_encoding | 이미지 인코딩 방식 binary(Default), base64 |
JSON 포맷으로 리턴 됩니다.
리턴되는 image_id를 MMS 발송 시 {group_id}/add_messages 파라메터로 입력하셔야 합니다.
Mandatory | Field | Description |
O | image_id | 이미지 아이디 |
curl -XPOST 'https://api.coolsms.co.kr/sms/2/upload_image' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a×tamp=1456364125' -F 'image=@/path/to/my/file'
{
"image_id": IMG565BA2D9E4239"
}
서버에 업로드 되어 있는 이미지 목록을 리턴합니다.