본문으로 건너뛰기

HTTP API

주의

Notifly HTTP API의 전체 요청량 제한은 초당 5,000회입니다. 안정적인 서비스 이용을 위해 클라이언트별 초당 요청량을 50-100건 이내로 유지해 주시기 바랍니다. 요청량 초과 시 4xx 응답 코드가 반환될 수 있습니다. 이를 방지하기 위해 지수 백오프 방식의 재시도 로직 구현이나 요청량 조절을 권장드립니다.

API 필드 변경 사항

2024-04-05 부터, projectID는 projectId로, userID는 userId로 변경되었습니다. (호환성을 위해 이전 필드명도 계속 사용 가능합니다.)

1. Authentication Endpoint​

이 endpoint 를 통해 인증 토큰을 받아올 수 있습니다. 인증 토큰은 notifly 서버 API 활용에 필수적입니다. 발급받은 인증 토큰의 유효기간은 1시간입니다. 과도한 API 호출을 방지하기 위해 1시간 이내의 재호출은 기존에 발급 받으신 토큰을 재활용 하시는 것을 권장해드립니다.

Endpoint​

POST https://api.notifly.tech/authenticate

Specifications​

Request Headers​

ParameterValueDescription
Content-Typeapplication/jsonRequest body 의 MIME Type

Request Body​

ParameterTypeRequiredDescription
accessKeyStringYesNotifly의 설정 페이지에서 확인하실 수 있습니다. 프로젝트 별로 하나의 Access Key가 생성됩니다. 문의 사항은 contact@notifly.tech 으로 이메일 부탁드립니다.
secretKeyStringYesNotifly의 설정 페이지에서 확인하실 수 있습니다. 프로젝트 별로 하나의 Secret Key가 생성됩니다. 문의 사항은 contact@notifly.tech 으로 이메일 부탁드립니다.

Response Headers​

ParameterValue
Status code200 OK
Content-Typeapplication/json

Response Body​

{
  "data": "{auth-key}",
  "error": null
}

Sample Request​

POST https://api.notifly.tech/authenticate
Content-Type: application/json

{
  "accessKey": "{access_key}",
  "secretKey": "{secret-key}"
}

2. Track Event Endpoint​

이 endpoint 를 통해 notifly 엔진에 이벤트 데이터를 보낼 수 있습니다. Notifly 엔진은 수신한 이벤트 데이터를 모으고 분석해 캠페인 진행 시 메시지 발송 타이밍, 사용자 세그먼트 설정 등에 활용할 수 있게 준비합니다.

Endpoint​

POST https://api.notifly.tech/track-event

Specifications​

Request Headers​

ParameterValueDescription
Content-Typeapplication/jsonRequest body 의 MIME Type
Authorization{auth-key}Authentication endpoint 를 통해 수령한 인증 토큰

Request Body​

ParameterTypeRequiredDescription
projectIdStringYesNotifly 팀에서 제공드리는 project ID 입니다. 문의 사항은 contact@notifly.tech 으로 이메일 부탁드립니다.
userIdStringYes서비스 유저 ID
eventNameStringYes이벤트명
eventParamsObjectNo이벤트 파라미터 값들
segmentationEventParamKeysListNo정교한 캠페인 집행을 위해 특정 파라미터들을 notifly 엔진에서 특수하게 처리합니다. 문의 사항은 contact@notifly.tech 으로 이메일 부탁드립니다.
  • 한번에 여러 이벤트를 로깅 할 수도 있습니다. 같은 형식의 Object들을 Array 형태로 호출 해주시면 됩니다.
    • 1회 호출당 최대 500개의 이벤트 까지만 로깅 가능합니다.

Response Headers​

ParameterValue
Status code200 OK
Content-Typeapplication/json

Response Body​

{
  "data": "some-success-response-from-notifly-engine",
  "error": null
}

Sample Request​

POST https://api.notifly.tech/track-event
Content-Type: application/json
Authorization: {auth-key}

[
  {
    "projectId": "project-id",
    "userId": "user-id",
    "eventName": "event-name",
    "eventParams": {},
    "segmentationEventParamKeys": []
  }
]

3. Set User Properties Endpoint​

이 endpoint 를 통해 notifly 엔진에 사용자 속성들을 등록할 수 있습니다. 등록된 속성값들은 캠페인 진행 시 사용자 세그먼트 설정에 활용하여 보다 효율적인 마케팅이 가능합니다.

Endpoint​

POST https://api.notifly.tech/set-user-properties

Specifications​

Request Headers​

ParameterValueDescription
Content-Typeapplication/jsonRequest body 의 MIME Type
Authorization{auth-key}Authentication endpoint 를 통해 수령한 인증 토큰

Request Body​

ParameterTypeRequiredDescription
projectIdStringYesNotifly 팀에서 제공드리는 project ID 입니다. 문의 사항은 contact@notifly.tech 으로 이메일 부탁드립니다.
userIdStringYes유저 ID
userPropertiesObjectYes업데이트 할 사용자 속성값들
  • 한번에 여러 사용자의 정보를 업데이트 할 수도 있습니다. 같은 형식의 Object들을 Array 형태로 호출 해주시면 됩니다.
    • 1회 호출당 최대 1,000명의 사용자 까지만 업데이트 가능합니다.
특수 유저 속성값

이메일과 전화번호 정보는 userProperties에 반드시 $email, $phone_number를 키값으로 정의해주어야 정상 등록됩니다. 아래 Example를 참고해주세요.

Response Headers​

ParameterValue
Status code200 OK
Content-Typeapplication/json

Response Body​

{
  "data": "업데이트 된 row count",
  "error": null
}

Sample Request​

POST https://api.notifly.tech/set-user-properties
Content-Type: application/json
Authorization: {auth-key}

[
  {
    "projectId": "project-id",
    "userProperties": {
      "$email": "user1@example.com",
      "$phone_number": "010-5555-5555"
    },
    "userId": "user-id-1"
  },
  {
    "projectId": "{project-id}",
    "userProperties": {
      "$email": "user2@example.com",
      "$phone_number": "010-7777-7777"
    },
    "userId": "user-id-2"
  }
]

4. Delete Users Endpoint​

이 endpoint 를 통해 notifly에 등록된 사용자들을 삭제할 수 있습니다.

Endpoint​

DELETE https://api.notifly.tech/users

Specifications​

Request Headers​

ParameterValueDescription
Content-Typeapplication/jsonRequest body 의 MIME Type
Authorization{auth-key}Authentication endpoint 를 통해 수령한 인증 토큰

Request Body​

ParameterTypeRequiredDescription
projectIdStringYesNotifly 팀에서 제공드리는 project ID 입니다. 문의 사항은 contact@notifly.tech 으로 이메일 부탁드립니다.
userIdStringNo삭제할 유저 ID
userPropertiesObjectNo삭제할 유저의 사용자 속성
- $emailStringNo삭제할 유저의 이메일 주소
- $phone_numberStringNo삭제할 유저의 전화번호
  • 한번에 여러 사용자의 정보를 삭제 할 수도 있습니다. 같은 형식의 Object들을 Array 형태로 호출 해주시면 됩니다.
    • 1회 호출당 최대 1,000명의 사용자 까지만 삭제 가능합니다.
    • 유저 ID, 이메일, 전화번호를 기준으로 삭제할 수 있습니다.
    • 전화번호는 정확히 일치해야 합니다. (010-1234-1234 != 01012341234)

Response Headers​

ParameterValue
Status code200 OK
Content-Typeapplication/json

Response Body​

{
  "data": "삭제된 row count",
  "error": null
}

Sample Request​

DELETE https://api.notifly.tech/users
Content-Type: application/json
Authorization: {auth-key}

{
  "projectId": "{project-id}",
  "userId": "{user-id}"
}

5. Campaign Triggering Endpoint​

이 endpoint 를 통해 캠페인을 트리거링할 수 있습니다. 등록된 유저 및 디바이스의 속성 뿐만 아니라 API Request Body의 파라미터까지 모두 사용하여 메시지를 개인화할 수 있습니다.

주의 사항​

  • HTTP API를 이용한 캠페인 발송의 경우, 캠페인의 발송 시간 유형이 API 기반 발송으로 설정되어있는 경우에만 사용 가능합니다.

Endpoint​

POST https://api.notifly.tech/campaign/{projectId}/{campaignId}/send

Specifications​

Request Headers​

ParameterValueDescription
Content-Typeapplication/jsonRequest body 의 MIME Type
Authorization{auth-key}Authentication endpoint 를 통해 수령한 인증 토큰

Path Parameters​

ParameterTypeRequiredDescription
projectIdStringYesNotifly의 설정 페이지에서 확인하실 수 있습니다.
campaignIdStringYes캠페인 리스트의 캠페인 목록을 클릭하여 상세보기 팝업 상단에서 확인하실 수 있습니다.

Request Body​

ParameterTypeRequiredDescription
recipientsListYes수신자 목록(최대 1000명)
- typeStringNo수신자의 유형입니다. (기본값: user-id). 현재 user-id, phone-number, email 만 지원합니다.
- userIdStringNo메시지를 발송할 유저의 ID 입니다. type이 user-id인 경우 필수입니다.
- phoneNumberStringNo메시지를 발송할 유저의 전화번호 입니다. type이 phone-number인 경우 필수입니다.
- emailStringNo메시지를 발송할 유저의 이메일 주소 입니다. type이 email인 경우 필수입니다.
- eventParamsObjectNo이벤트 파라미터를 포함하는 객체 입니다. 해당 파라미터로 메시지를 개인화시킬 수 있습니다.
API 기반 발송 지원 채널

현재 API 기반 발송은 다음 채널에 대해 지원됩니다.

  • 푸시 알림
  • 웹 푸시 알림
  • 카카오 알림톡
  • 문자 메시지
  • 이메일
수신자 유형 지원 범위와 메시지 개인화

설정된 캠페인의 발송 채널마다 지원되는 수신자 유형이 다를 수 있습니다. 만약 캠페인의 발송 채널이 지원하지 않는 수신자 유형을 사용하면, API 응답으로 400 Bad Request가 반환됩니다.

  • 푸시 알림: user-id 유형의 수신자만 지원됩니다.
  • 웹 푸시 알림: user-id 유형의 수신자만 지원됩니다.
  • 카카오 알림톡: user-id 및 phone-number 유형의 수신자를 지원합니다.
  • 문자 메시지: user-id 및 phone-number 유형의 수신자를 지원합니다.
  • 이메일: user-id, email 유형의 수신자만 지원됩니다.

수신자 유형이 user-id가 아닌 경우, Notifly 서버는 유저 데이터베이스에서 해당 유저에 대한 정보를 받아오지 않고, 요청 payload에 명시되어있는 정보로만 발송을 시도합니다. 따라서, 수신자 유형이 user-id가 아닌 경우 유저 기반 메시지 개인화 기능을 사용하실 수 없습니다. 예를 들어, 이 경우 캠페인의 메시지 내용에 {{ user["name"] }} 님 안녕하세요 라는 구문이 들어있다면, 개인화는 실패하고 님 안녕하세요 라는 메시지가 발송됩니다.

이벤트 패러미터는 모든 유형에 대해 사용 가능합니다. 더 자세한 API 기반 발송 캠페인 예시는 이 곳을 참고해주세요.

중복 제거

API 기반 발송은 중복 발송을 방지하기 위해 수신자의 중복 여부를 체크합니다. 동일한 수신자가 여러 번 포함되어 있는 경우, 중복된 수신자는 한 번만 발송됩니다. 다음은 채널 별 중복 제거 규칙입니다.

  • 푸시 알림: 동일한 디바이스 토큰일 경우, 하나의 디바이스 토큰에만 메시지를 발송합니다.
  • 웹 푸시 알림: 동일한 디바이스 토큰일 경우, 하나의 디바이스 토큰에만 메시지를 발송합니다.
  • 카카오 알림톡: 동일한 전화번호일 경우, 하나의 전화번호에만 메시지를 발송합니다.
  • 문자 메시지: 동일한 전화번호일 경우, 하나의 전화번호에만 메시지를 발송합니다.
  • 이메일: 동일한 이메일 주소일 경우, 하나의 이메일 주소에만 메시지를 발송합니다.

Response​

Status CodeContent-TypeDescriptionExample Response
200 OKapplication/json캠페인이 정상적으로 트리거 되었습니다.{"code": 200, "success":true,"error":null}
400 Bad Requestapplication/json잘못된 요청입니다.{"code": 400, "success":false,"error":"Bad request: some-error-message"}
401 Unauthorizedapplication/json토큰이 만료되었거나, 인증 정보가 유효하지 않습니다.{"code": 401, "success":false,"error":"Unauthorized: Invalid token"}
405 Method Not Allowedapplication/json지원되지 않는 HTTP Method 입니다.{"code": 405, "success":false,"error":"Method not allowed: some-error-message"}
413 Payload Too Largeapplication/json요청 payload가 너무 큽니다.{"code": 413, "success":false,"error":"Payload too large: some-error-message"}
500 Internal Server Errorapplication/json노티플라이 서버 오류입니다. 지속적으로 500 에러가 발생한다면, 노티플라이 팀에 문의해주세요.{"code": 500, "success":false,"error":"some-error-message"}
501 Not Implementedapplication/json아직 지원되지 않는 기능입니다.{"code": 501, "success":false,"error":"Not implemented: some-error-message"}

Sample Request​

POST https://api.notifly.tech/campaign/{projectId}/{campaignId}/send
Content-Type: application/json
Authorization: {auth-key}

{
  "recipients": [
    {
      "userId": "alice",
      "eventParams": {
        "messageTitle": "Hello Alice!",
        "messageBody": "How are you?"
      }
    },
    {
      "userId": "bob",
      "eventParams": {
        "messageTitle": "Hello Bob!",
        "messageBody": "How are you?"
      }
    }
  ]
}

6. Send Text Message Endpoint​

이 endpoint 를 통해 문자 메시지(SMS, LMS, MMS)를 보낼 수 있습니다.

주의 사항​

  • HTTP REST API를 이용한 문자 발송은 Notifly 문자 자체 발송 설정이 되어있을 경우에만 가능합니다.
  • 발신 번호는 자체 발송 설정에 입력된 번호가 사용 됩니다.
  • 아직 API를 이용한 발송 결과에 대한 통계는 UI로 제공 되지 않습니다. 정보가 필요하실 경우 contact@notifly.tech 으로 이메일 부탁드립니다.

Endpoint​

POST https://api.notifly.tech/messages/text-message

Specifications​

Request Headers​

ParameterValueDescription
Content-Typeapplication/jsonRequest body 의 MIME Type
Authorization{auth-key}Authentication endpoint 를 통해 수령한 인증 토큰

Request Body​

ParameterTypeRequiredDescription
projectIdStringYesNotifly의 설정 페이지에서 확인하실 수 있습니다.
typeStringYes메시지 유형 (sms, lms 또는 mms)
titleStringNo본문 제목(lms, mms에만 사용)
bodyStringYes본문 내용
recipientListListYes수신자 목록(최대 1000명)
- recipientNoStringYes수신 번호

Response​

Status CodeContent-TypeExample Response
200 OKapplication/json{"success":true}
400 Bad Requestapplication/json{"error":"some-error-message"}
405 Method Not Allowedapplication/json{"error":"Method not allowed"}
413 Payload Too Largeapplication/json{"error":"Payload Too Large"}
500 Internal Server Errorapplication/json{"error":"Internal Server Error"}

Sample Request​

POST https://api.notifly.tech/messages/text-message
Content-Type: application/json
Authorization: {auth-key}

{
  "projectId": "project-id",
  "type": "sms",
  "body": "Message Body",
  "recipientList": [
    {
      "recipientNo": "01012345678"
    },
    {
      "recipientNo": "01045671234"
    }
  ]
}

7.Send Kakao Alimtalk Message Endpoint​

이 endpoint 를 통해 카카오 알림톡 메시지를 발송할 수 있습니다. 알림톡 템플릿 코드와 수신자 리스트를 사용하여 메시지를 전송합니다.

주의 사항​

  • HTTP REST API를 이용한 카카오 알림톡 발송은 Notifly 카카오톡 자체 발송 설정이 되어있을 경우에만 가능합니다.
  • 아직 API를 이용한 발송 결과에 대한 통계는 UI로 제공 되지 않습니다. 정보가 필요하실 경우 contact@notifly.tech 으로 이메일 부탁드립니다.

Endpoint​

POST https://api.notifly.tech/messages/kakao-alimtalk

Specifications​

Request Headers​

ParameterValueDescription
Content-Typeapplication/jsonRequest body 의 MIME Type
Authorization{auth-key}Authentication endpoint 를 통해 수령한 인증 토큰

Request Body​

ParameterTypeRequiredDescription
projectIdStringYesNotifly의 설정 페이지에서 확인하실 수 있습니다.
channelIdStringNo발송할 카카오 채널 ID
templateIdStringYes등록한 발송 템플릿 ID (알림톡 템플릿 리스트에서 확인 가능)
senderGroupingKeyStringNo발신 그룹핑 키(최대 100자)
recipientListListYes수신자 목록(최대 1000명)
- recipientNoStringYes수신 번호 (최대 15자)
- templateParameterObjectNo템플릿 파라미터, 치환할 변수가 포함된 경우 필수
- resendParameterResendParameterNo대체 발송 정보

ResendParameter​

ParameterTypeRequiredDescription
isResendBooleanNo발송 실패 시, 문자 대체 발송 여부. 기본값은 false.
resendTypeStringNo대체 발송 타입(SMS, LMS). 템플릿 본문 길이에 따라 타입이 구분됩니다.
resendTitleStringNoLMS 대체 발송 제목. 기본값은 플러스친구 ID입니다.
resendContentStringNo대체 발송 내용. 기본값은 메시지 본문과 웹링크 버튼명 - 웹링크 Mobile 링크입니다.

Response​

Status CodeContent-TypeExample Response
200 OKapplication/json{"success":true}
400 Bad Requestapplication/json{"error":"some-error-message"}
405 Method Not Allowedapplication/json{"error":"Method not allowed"}
413 Payload Too Largeapplication/json{"error":"Payload Too Large"}
500 Internal Server Errorapplication/json{"error":"Internal Server Error"}

Sample Request​

POST https://api.notifly.tech/messages/kakao-alimtalk
Content-Type: application/json
Authorization: {auth-key}

{
  "projectId": "project-id",
  "templateId": "template-id",
  "recipientList": [
    {
      "recipientNo": "01012345678",
      "templateParameter": {
        "user_name": "Notifly User"
      }
    },
    {
      "recipientNo": "01056781234",
      "templateParameter": {
        "user_name": "Notifly Customer"
      }
    }
  ]
}

8. Send Kakao Friendtalk Message Endpoint​

이 endpoint 를 통해 카카오 친구톡 메시지를 발송할 수 있습니다. 프렌드톡 메시지는 수신자 목록, 광고 여부, 메시지 유형 등을 설정하여 전송합니다.

주의 사항​

  • HTTP REST API를 이용한 카카오 친구톡 발송은 Notifly 카카오톡 자체 발송 설정이 되어있을 경우에만 가능합니다.
  • 아직 API를 이용한 발송 결과에 대한 통계는 UI로 제공 되지 않습니다. 정보가 필요하실 경우 contact@notifly.tech 으로 이메일 부탁드립니다.

Endpoint​

POST https://api.notifly.tech/messages/kakao-friendtalk

Specifications​

Request Headers​

ParameterValueDescription
Content-Typeapplication/jsonRequest body 의 MIME Type
Authorization{auth-key}Authentication endpoint 를 통해 수령한 인증 토큰

Request Body​

ParameterTypeRequiredDescription
projectIdStringYesNotifly의 설정 페이지에서 확인하실 수 있습니다.
channelIdStringNo여러 카카오 채널이 등록되어 있을 경우 발송 할 채널 ID.
messageTypeStringYes메시지 타입. (현재 text타입만 지원합니다.)
isAdBooleanNo광고 여부
recipientListListYes수신자 목록(최대 1000명)
- recipientNoStringYes수신 번호
- content.textStringYes본문 내용

Response​

Status CodeContent-TypeExample Response
200 OKapplication/json{"success":true}
400 Bad Requestapplication/json{"error":"some-error-message"}
405 Method Not Allowedapplication/json{"error":"Method not allowed"}
413 Payload Too Largeapplication/json{"error":"Payload Too Large"}
500 Internal Server Errorapplication/json{"error":"Internal Server Error"}

Sample Request​

POST https://api.notifly.tech/messages/kakao-friendtalk
Content-Type: application/json
Authorization: {auth-key}

{
  "projectId": "project-id",
  "messageType": "text",
  "isAd": false,
  "recipientList": [
    {
      "recipientNo": "01012345678",
      "content": {
        "text": "test"
      }
    }
  ]
}

9. 080 Block Service Endpoint​

이 섹션에서는 080 수신 거부 서비스와 관련된 API를 설명합니다.

9.1 Find Recipients​

Endpoint​

GET https://api.notifly.tech/projects/{projectId}/messages/text-message/blockservice/recipients

Specifications​

Request Headers​
ParameterValueDescription
Content-Typeapplication/jsonRequest body의 MIME Type
AuthorizationauthTokenAuthentication endpoint 를 통해 수령한 인증 토큰
Path Parameters​
ParameterTypeRequiredDescription
projectIdStringYes프로젝트 ID
Query Parameters​
ParameterTypeRequiredDescription
unsubscribeNoStringYes080 수신 거부 번호 (최대 25자)
recipientNoStringNo수신 거부 대상자 번호 (최대 25자)
startRequestDateStringNo수신 거부 요청 시작값(yyyy-MM-dd HH:mm:ss)
endRequestDateStringNo수신 거부 요청 종료값(yyyy-MM-dd HH:mm:ss)
pageNumIntegerNo페이지 번호(기본값 : 1)
pageSizeIntegerNo검색 수(기본값 : 15, 최대 1000)
Response Headers​
ParameterValue
Status code200 OK
Content-Typeapplication/json
Response Body​
{
  "pageNum": 1,
  "pageSize": 15,
  "totalCount": 1,
  "data": [
    {
      "unsubscribeNo": "0808888888",
      "recipientNo": "01000000000",
      "requestDate": "2018-05-14 17:07:29.0"
    },
    {
      "unsubscribeNo": "0808888888",
      "recipientNo": "010012341234",
      "requestDate": "2018-05-14 17:07:29.0"
    },
    ...
  ]
}

Sample Request​

GET https://api.notifly.tech/projects/{projectId}/messages/text-message/blockservice/recipients?unsubscribeNo=0800000000&pageNum=1&pageSize=15
Content-Type: application/json
Authorization: {auth-key}

9.2 Register Recipients​

Endpoint​

POST https://api.notifly.tech/projects/{projectId}/messages/text-message/blockservice/recipients

Specifications​

Request Headers​
ParameterValueDescription
Content-Typeapplication/jsonRequest body의 MIME Type
AuthorizationauthTokenAuthentication endpoint 를 통해 수령한 인증 토큰
Path Parameters​
ParameterTypeRequiredDescription
projectIdStringYes프로젝트 ID
Request Body​
ParameterTypeRequiredDescription
unsubscribeNoStringYes080 수신거부번호 (최대 25자)
recipientNoListListYes수신 거부 대상자 번호 (최대 10개)
Response Headers​
ParameterValue
Status code200 OK
Content-Typeapplication/json

Sample Request​

POST https://api.notifly.tech/projects/{projectId}/messages/text-message/blockservice/recipients
Content-Type: application/json
Authorization: {auth-key}

{
  "unsubscribeNo": "0800000000",
  "recipientNoList": ["0100000000", "0100000001"]
}

9.3 Remove Recipients​

Endpoint​

DELETE https://api.notifly.tech/projects/{projectId}/messages/text-message/blockservice/recipients/removes

Specifications​

Request Headers​
ParameterValueDescription
Content-Typeapplication/jsonRequest body의 MIME Type
AuthorizationauthTokenAuthentication endpoint 를 통해 수령한 인증 토큰
Path Parameters​
ParameterTypeRequiredDescription
projectIdStringYes프로젝트 ID
Query Parameters​
ParameterTypeRequiredDescription
unsubscribeNoStringYes080 수신 거부 번호 (최대 20자)
recipientNoListStringYes삭제할 수신 거부 번호 (콤마로 구분)
Response Headers​
ParameterValue
Status code200 OK
Content-Typeapplication/json

Sample Request​

DELETE https://api.notifly.tech/projects/{projectId}/messages/text-message/blockservice/recipients/removes?unsubscribeNo=0800000000&recipientNoList=0100000000,0100000001
Content-Type: application/json
Authorization: {auth-key}