SMS API Version 2

Overview

이 문서는 REST기반의 문자메시지(국내,해외문자,알림톡,친구톡) API로 예약 문자를 포함한 문자전송, 전송된 문자의 상태 확인, 잔액정보 및 예약취소 등의 작업을 요청하는 방법을 기술하고 있습니다. PHP, Java, Python, Delphi, C 등 다양한 언어로 구현된 샘플을 SDK 페이지에서 제공하고 있습니다..

모든 Request 호출에는 API Key를 비롯한 인증정보를 포함하여 서버의 인증을 거쳐야 합니다. 인증에 대한 상세한 내용은 Authentication 을 확인하세요.

인증을 위한 API Key 및 API Secret 코드는 문자메시지 > 환경설정 > API Key 관리 메뉴에서 발급 및 관리가 가능합니다. API Key 관리 문서를 참고하세요.

아래는 각 Resource의 역할을 테이블로 정리하였습니다. 상세한 설명을 보시려면 해당 Resource를 클릭하여 주세요.

요청에 대한 응답의 상세는 Response 를 확인하세요.

REST API 관련 질의 응답 및 정보 공유는 개발자포럼을 이용해주세요.

Change Log

그룹메시지

대용량의 메시지를 안전하고 빠르게 전송하도록 그룹메시지를 위한 API를 제공합니다. 아래의 API 호출 흐름으로 대량의 그룹메시지를 보낼 수 있습니다.

new_group  ->  add_messages  ->  send

new_group 호출로 메시지를 담을 그룹을 생성하고 리턴된 그룹아이디를 키로 add_messages 호출로 메시지를 접수하고 send 호출로 접수된 메시지를 서버단에 전송을 수행합니다. 이로 인해 한번 접수된 메시지는 유실 없이 안정적으로 발송이 보장됩니다.

GET new_group

메시지를 담을 그룹을 생성하여 그룹아이디를 리턴합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/new_group

Parameters

Response

JSON 포맷으로 리턴 됩니다.

Example Request

curl -XGET 'https://api.coolsms.co.kr/sms/2/new_group?api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125'

Example Response

{
  "group_id":"565ba3d7d216a"
}

GET group_list

생성된 그룹 목록을 리턴합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/group_list

Parameters

Response

JSON 포맷으로 리턴 됩니다.

Example Request

curl -XGET 'https://api.coolsms.co.kr/sms/2/group_list?api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125'

Example Response

[
    "565ba3d7d216a",
    "565ba3dea161b"
]

POST delete_groups

그룹을 삭제합니다. 담겨 있는 메시지도 함께 삭제됩니다.

Resource URL

https://api.coolsms.co.kr/sms/2/delete_groups

Parameters

Response

JSON 포맷으로 리턴 됩니다.

Example Request

curl -XPOST 'https://api.coolsms.co.kr/sms/2/delete_groups' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125&group_ids=565ba3d7d216a'

Example Response

{
  "success_count": 3,
  "error_count": 2,
  "error_list": [
    4: "62",
    5: "54"
  ]
}

GET groups/{group_id}

그룹 정보를 리턴합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/groups/{group_id}

Parameters

Response

JSON 포맷으로 리턴 됩니다.

Example Request

curl -XGET 'https://api.coolsms.co.kr/sms/2/groups/{group_id}' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125&group_id=565ba3d7d216a'

Example Response

{
  "group_id":"565ba3d7d216a",
  "message_count":970
}

POST groups/{group_id}/add_messages

그룹에 발송할 문자메시지를 추가합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/groups/{group_id}/add_messages

Parameters

제한 사항

to 필드의 전화번호 수는 최대 1,000개이며 넘을 경우 오류를 발생 (RecipientsTooMany)

한번의 Request의 총 데이터 크기는 2MB를 넘을 수 없습니다 (HTTP ERROR 413 발생)

발송형태별 제한사항

이동통신사 내부적으로 완성형한글로 변환되므로 영어 1바이트, 한글 2바이트로 취급됩니다.

Response

JSON 포맷으로 리턴 됩니다.

Example Request

curl -XPOST https://api.coolsms.co.kr/sms/2/groups/GID565bA3D7D216A/add_messages -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125&to=01012345678&from=029302266&text=Hello'

Example Response

{
  "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 조회로 실제 전송된 결과를 확인하실 수 있습니다.

POST groups/{group_id}/add_messages.json

그룹에 발송할 문자메시지를 JSON 형식으로 접수합니다. 대량의 문자를 각각 다른 내용과 타입으로 보내고 싶을 때 용이 합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/groups/{group_id}/add_messages.json

Parameters

JSON Fields

messages 포맷

[ ] 안에 { } 가 여러 개 들어 갈 수 있는 구조로 되어있으며 각각의 { } 안에는 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바이트로 취급됩니다.

JSON 포맷으로 리턴 됩니다.Response

Example Request

curl -XPOST https://api.coolsms.co.kr/sms/2/groups/565ba3d7d216a/add_messages -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125&messages=JSONArray

Example Response

[
  {
    "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 조회로 실제 전송된 결과를 확인하실 수 있습니다.

GET groups/{group_id}/message_list

문자메시지 목록을 리턴합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/groups/{group_id}/message_list

Parameters

Response

JSON 포맷으로 리턴 됩니다.

Example Request

curl -XGET 'https://api.coolsms.co.kr/sms/2/groups/{group_id}/message_list' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125'

Example Response

{
  "total_count":2,
  "offset":0,
  "limit":20,
  "list":[
     "565ba4e7d316b",
     "565ab383dabcd"
  ]
}

POST groups/{group_id}/delete_messages

그룹에 추가된 메시지를 삭제합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/groups/{group_id}/delete_messages

Parameters

Response

JSON 포맷으로 리턴 됩니다.

Example Request

curl -XPOST 'https://api.coolsms.co.kr/sms/2/groups/{group_id}/delete_messages' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125&message_ids=MID565BA6D7E325C,MID565433E7D233A,MID565643A66AB21'

Example Response

서버는 json 포맷으로 삭제된 갯수를 리턴합니다.

{
  "success_count": 1,
  "error_count": 2,
  "error_list": [
    0: "1021",
    2: "1021"
  ]
}

POST groups/{group_id}/send

그룹메시지를 전송 요청합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/groups/{group_id}/send

Parameters

Response

JSON 포맷으로 리턴 됩니다.

Example Request

curl -XPOST 'https://api.coolsms.co.kr/sms/2/groups/{group_id}/send' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125'

Example Response

{
  "group_id": "565ba3d7d216a"
}

이미지

이미지를 서버에 안전하게 미리 업로드하여 문자발송 때 사용할 수 있어 더욱 안정적인 발송을 보장합니다.

POST upload_image

MMS 발송에 필요한 이미지 파일을 업로드 합니다.

MMS 발송 때 미리 업로드 된 이미지 파일을 사용하므로 발송과정에서 발생하는 오류률 현저히 줄어듭니다.

이미지 보관 기간은 7일입니다.

Resource URL

https://api.coolsms.co.kr/sms/2/upload_image

Parameters

Response

JSON 포맷으로 리턴 됩니다. 리턴되는 image_id를 MMS 발송 시 {group_id}/add_messages 파라메터로 입력하셔야 합니다.

Example Request

curl -XPOST 'https://api.coolsms.co.kr/sms/2/upload_image' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125' -F 'image=@/path/to/my/file'

Example Response

{
  "image_id": IMG565BA2D9E4239"
}

GET image_list

서버에 업로드 되어 있는 이미지 목록을 리턴합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/image_list

Parameters

Response

JSON 포맷으로 리턴 됩니다.

Example Request

curl -XGET 'https://api.coolsms.co.kr/sms/2/image_list' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125'

Example Response

{
  "total_count":3,
  "offset":0,
  "limit":20,
  "list":[
    "IMG565BA6D7D327C",
    "IMG565BA7ABD338B",
    "IMG565BB9D7D21C7"
  ]
}

GET images/{image_id}

업로드된 이미지 정보를 리턴합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/images/{image_id}

Parameters

Response

해당 이미지의 정보가 JSON 포맷으로 리턴 됩니다.

Example Request

curl -XGET 'https://api.coolsms.co.kr/sms/2/images/{image_id}' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125'

Example Response

{
  "image_id":"566fb2266316f",
  "file_name","566fb2266316f.jpg",
  "original_name":"nurigo-200x100.jpg",
  "file_size":"4990",
  "width":"200",
  "height":"100"
}

POST delete_images

이미지 파일을 삭제합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/delete_images

Parameters

Response

JSON 포맷으로 리턴 됩니다.

Example Request

curl -XPOST 'https://api.coolsms.co.kr/sms/2/delete_images' -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125&image_ids=IMG565BA2D9E4239,IMG565AB2E4A5134,IMG565BB3A4B4342'

Example Response

{
  "success_count": 1,
  "error_count": 2,
  "error_list": [
    0: "1023",
    2: "1024"
  ]
}

POST send

문자메시지를 전송 요청합니다. 전송 요청에 대한 Response는 휴대전화까지 전송된 결과가 아닙니다.

Resource URL

https://api.coolsms.co.kr/sms/2/send

Parameters

Mandatory가 Ο 인 필드는 반드시 입력하여야 합니다.

srk 는 앱아이디를 말하는 것으로 https://www.coolsms.co.kr/me/apps 을 참고하세요.

한번의 Request에 extension을 포함하여 총 받는사람(to) 수는 1000개 까지가 제한이며 1000개가 넘을 경우 오류를 발생시킵니다. (RecipientsTooMany)

한번의 Request의 총 크기는 2MB를 넘을 수 없습니다. (HTTP ERROR 413 발생)

발송형태에 따른 제한사항

이동통신사 내부적으로 완성형한글로 변환되므로 영어 1바이트, 한글 2바이트로 취급됩니다.

Response

result_code 가 00 이면 정상적인 접수이며 이 외의 코드는 http://www.coolsms.co.kr/Legacy_Result_Codes 을 참고하세요. 여기서 리턴되는 Response의 내용은 서버에게 전송을 요청한 것에 대한 정보이지 실제 휴대전화로 전송한 것에 대한 정보가 아닙니다. 예를 들어 요청 건수 중 success_count가 10개라면 서버의 DB에 안전하게 INSERT된 건이 10개라는 의미이며, 나중 sent 리소스를 통해 조회시 이통사를 통해 실제 전송성공된 건수는 8개이고 올바르지 못한 수신번호로 2개로 실패라는 결과가 나올 수 있습니다.

메시지그룹ID(group_id)는 Request된 메시지들의대표하는 아이디값으로 메시지상태 및 예약취소할 때 키값으로 사용될 수 있습니다. 10건의 문자메시지를 발송할 경우 그 10건의 문자메시지를 대표하는 group_id 가 리턴되며 sent 리소스를 통해서 10건에 대한 전송상태를 조회할 수 있습니다.

Example Request

curl -XPOST https://api.coolsms.co.kr/sms/2/send -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125&to=01012345678,01023456789,01034567890&from=029302266&text=Hello'

Example Response

서버는 json 포맷으로 접수결과를 리턴합니다.

{
  "group_id": "20120217103829612403761364",
  "success_count": 2,
  "error_count": 0,
  "result_code": "00",
  "result_message": "Success"
}

GET sent

발송된 문자메시지의 목록을 가져옵니다.

Resource URL

https://api.coolsms.co.kr/sms/2/sent

Parameters

검색 옵션이 없는 경우 가장 최신의 발송건부터 20일 전까지 내림차순으로 페이지 단위의 목록을 리턴합니다.

Response

JSON 포맷으로 리턴 됩니다.

Example Request

curl -XGET https://api.coolsms.co.kr/sms/2/sent -d 'api_key=NCS52A57F48C3D32&signature=202b4d499fbd71813c170a415f84097a&timestamp=1456364125&salt=abc&offset=0&limit=20'

Example Response

Response Format은 json을 사용합니다.

{
  "total_count":"169",
  "list_count":4,
  "page":1,
  "data":[
    {
      "type":"SMS",
      "accepted_time":"2014-01-07 18:14:54",
      "recipient_number":"01000000000",
      "group_id":"G52CBC596955F0",
      "message_id":"M52CBC59695B31",
      "status":"2",
      "result_code":"58",
      "result_message":"\uc804\uc1a1\uacbd\ub85c \uc5c6\uc74c",
      "sent_time":"L",
      "text":"Test Message",
      "carrier":"SKT",
      "scheduled_time":"201401071814"
    },
    {
      "type":"SMS",
      "accepted_time":"2014-01-07 18:14:41",
      "recipient_number":"01000000000",
      "group_id":"G52CBC5897645A",
      "message_id":"M52CBC58976A64",
      "status":"2",
      "result_code":"58",
      "result_message":"\uc804\uc1a1\uacbd\ub85c \uc5c6\uc74c",
      "sent_time":"201401071814",
      "text":"message\nhere",
      "carrier":"KTF",
      "scheduled_time":"201401071814"
    },
    {
      "type":"SMS",
      "accepted_time":"2014-01-07 18:11:23",
      "recipient_number":"01000000000",
      "group_id":"G52CBC4C35B3A8",
      "message_id":"M52CBC4C35BA70",
      "status":"2",
      "result_code":"58",
      "result_message":"\uc804\uc1a1\uacbd\ub85c \uc5c6\uc74c",
      "sent_time":"201401071811",
      "text":"message\nhere",
      "carrier":"LGT",
      "scheduled_time":"201401071814"
    },
    {
      "type":"SMS",
      "accepted_time":"2014-01-06 12:42:32",
      "recipient_number":"01012345678",
      "group_id":"G52CA262EC447D",
      "message_id":"M52CA262EC49D8",
      "status":"2",
      "result_code":"00",
      "result_message":"\uc815\uc0c1",
      "sent_time":"201401061257",
      "text":"\ud14c\uc2a4\ud305hi there~",
      "carrier":"KTF",
      "scheduled_time":"201401071814"
    }
  ]
}

status

result_code 는 http://www.coolsms.co.kr/Legacy_Result_Codes 페이지를 참고 하세요.

POST cancel

예약된 문자메시지를 취소합니다. 예약되지 않았거나, 예약되었으나 이미 발송된 문자메시지는 취소 할 수 없습니다.

Resource URL

https://api.coolsms.co.kr/sms/2/cancel

Parameters

message_id 혹은 group_id 중 하나는 반드시 입력하세요.

Response

JSON 포맷으로 리턴 됩니다.

GET balance

잔액을 확인합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/balance

Parameters

Response

Response Format은 json을 사용합니다.

{
  "cash": "23900",
  "point": "890"
}

GET status

전송채널의 상태를 조회합니다.

Resource URL

https://api.coolsms.co.kr/sms/2/status

Parameters

Response

JSON 포맷으로 리턴 됩니다.

모든 항목의 값은 초단위(seconds)값입니다. sms_average와 mms_average는 각각 SMS채널과 MMS채널의 문자가 접수된 때부터 실제 수신되기까지 걸린 시간으로 계산된 평균값으로 리포트가 오지않은 대기중인 메시지를 합산한 값이므로 다소 높게 나와도 정상입니다. sk, kt, lg 의 경우 수신시각이 분단위로만 제공되어서 약간의 차이가 날 수 있습니다.

Response Example

[
  {
    "registdate": "2014-02-25 10:34:01",
    "sms_average": "23",
    "sms_sk_average": "9",
    "sms_kt_average": "10",
    "sms_lg_average": "11",
    "mms_average": "52",
    "mms_sk_average": "20",
    "mms_kt_average": "25",
    "mms_lg_average": "36"
  }
]

메시지상태코드

숫자 4자리로 구성된 메시지의 상태를 나타내는 코드입니다. 코드 첫번째 자리 숫자의 의미는 아래와 같습니다.

Message API 호출시에는 앞에 두자리와 뒤 두자리가 구분되어 리턴됩니다.

예) 1010 -> status = '1', result_code = '10'

코드 목록

PreviousSMS API Version 1NextC

Last updated