본문으로 건너뛰기

HTTP API

주의

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

API 필드 변경 사항

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

1. Authentication​

이 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 를 통해 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 를 통해 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 를 통해 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 를 통해 캠페인을 트리거링할 수 있습니다. 등록된 유저 및 디바이스의 속성 뿐만 아니라 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. Campaign Statistics Retrieval​

이 endpoint를 통해 캠페인의 발송 현황을 조회하실 수 있습니다.

Endpoint​

GET https://api.notifly.tech/projects/{projectId}/campaigns/{campaignId}/stats

Specifications​

Request Headers​

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

Path Parameters​

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

Query Parameters​

ParameterTypeRequiredDescription
startStringYes조회 시작일자 (yyyy-MM-ddTHH:mm:ss.sssZ 형식, UTC 기준)
endStringYes조회 종료일자 (yyyy-MM-ddTHH:mm:ss.sssZ 형식, UTC 기준)

Response​

Status CodeContent-TypeDescriptionExample Response
200 OKapplication/json캠페인 통계를 정상적으로 조회한 경우{ "data": { "lastCollectedAt": "2024-10-29 04:00:00", "stats": [...] }, "error": null }
400 Bad Requestapplication/json잘못된 요청 파라미터가 있는 경우{ "data": null, "error": "Invalid project ID" }
401 Unauthorizedapplication/json인증 토큰이 유효하지 않거나 누락된 경우{ "data": null, "error": "Unauthorized: Invalid Authorization Token" }
500 Internal Server Errorapplication/json서버 오류가 발생한 경우. 지속적인 500 오류는 Notifly 팀에 문의{ "data": null, "error": "Internal Server Error: some-error-message" }

Response Body​

{
  "data": {
    "lastCollectedAt": "2024-10-29 04:00:00",
    "stats": [
      {
        "metricName": "send_success",
        "metricType": "standard",
        "totalCount": 550,
        "dailyCounts": [
          {
            "date": "2024-10-28",
            "count": 250,
            "dimensionCounts": [
              {
                "dimensionKey": "region",
                "dimensionValue": "us-east",
                "count": 100
              },
              {
                "dimensionKey": "region",
                "dimensionValue": "us-west",
                "count": 150
              }
            ]
          },
          {
            "date": "2024-10-29",
            "count": 300,
            "dimensionCounts": [
              {
                "dimensionKey": "region",
                "dimensionValue": "us-east",
                "count": 200
              },
              {
                "dimensionKey": "region",
                "dimensionValue": "us-west",
                "count": 100
              }
            ]
          }
        ]
      }
    ]
  },
  "error": null
}
FieldTypeDescription
lastCollectedAtString최종 집계 시간. KST 기준 날짜와 시간(yyyy-MM-dd HH:mm:ss 형식)으로 반환됩니다.
statsArray캠페인 발송 현황 데이터 배열
- metricNameString집계된 메트릭의 이름 (예: send_success, send_failure, push_click 등).
메트릭 이름에 대한 설명은 Standard Metric 종류를 참조하세요.
- metricTypeString메트릭의 타입 (standard 또는 conversion)
- totalCountNumber지정된 기간 동안 해당 메트릭이 누적된 총 횟수
- dailyCountsArray일별로 집계된 메트릭 데이터
   - dateString집계 날짜 (yyyy-MM-dd 형식, KST 기준)
   - countNumber해당 날짜에 발생한 메트릭 횟수
   - dimensionCountsArray대시보드 구성 - 사용자 속성을 입력한 경우 속성별로 집계된 메트릭 데이터
     - dimensionKeyString사용자 속성 키
     - dimensionValueString사용자 속성 값
     - countNumber해당 속성 값에 대한 메트릭 횟수

Standard Metric 종류​

Metric NameDescription
send_success발송 성공
send_failure발송 실패
rendering_failure개인화 메시지 렌더링 실패
pending발송 시도(집계 중)
push_delivered푸시알림 수신
push_click푸시알림 클릭
failover_text_message_send_success대체 문자 메시지 발송 성공
failover_text_message_send_failure대체 문자 메시지 발송 실패
email_send이메일 발송
email_delivery이메일 도달
email_open이메일 오픈
email_click이메일 클릭
email_bounce이메일 반송
email_complaint이메일 수신 거부
email_rendering_failure이메일 렌더링 실패
in_app_message_show앱 팝업 노출
in_web_message_show웹 팝업 노출
main_button_click팝업 메인버튼 클릭
close_button_click팝업 닫기 버튼 클릭
hide_in_app_message_button_click인앱 팝업 다시(특정 기간) 보지 않기 버튼 클릭
cancelled취소 이벤트로 인한 발송 취소
skipped__noisy_filter중복 발송으로 인한 발송 취소
skipped__fatigue_management피로도 관리로 인한 발송 취소
skipped__forbidden_timing_filter금지된 발송 시간으로 인한 발송 취소
skipped__excluded_user_filter발신 제외 유저로 인한 발송 취소
skipped__aborted_message메시지 Abort로 인한 발송 취소(Connected Contents)
skipped__global_frequency_limit_filter발송량 제한 조건으로 인한 발송 취소

Sample Request​

GET https://api.notifly.tech/projects/{projectId}/campaigns/{campaignId}/stats?start=2024-10-27T15:00:00.000Z&end=2024-10-29T14:59:59.999Z
Content-Type: application/json
Authorization: {auth-key}

7. Send Text Message​

이 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본문 내용
sendNoStringNo여러 발신 번호가 등록되어 있을 경우 발송할 번호
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"
    }
  ]
}

8. Manage Text Message 080 Block Service​

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

8.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
Authorization{auth-key}Authentication 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}

8.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
Authorization{auth-key}Authentication 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"]
}

8.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
Authorization{auth-key}Authentication 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}

9.Send Kakao Alimtalk Message​

이 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의 설정 페이지에서 확인하실 수 있습니다.
templateIdStringYes등록한 발송 템플릿 ID (알림톡 템플릿 리스트에서 확인 가능)
channelIdStringNo발송할 카카오 채널 ID
resendSendNoStringNo대체 발송 발신 번호 (Notifly 문자 자체 발송 이 설정된 번호)
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"
      }
    }
  ]
}

10. Manage Kakao Alimtalk Template​

10.1 템플릿 리스트 조회​

Endpoint

GET https://api.notifly.tech/projects/{projectId}/messages/kakao-alimtalk/templates

Specifications​

Path Parameters​
ParameterTypeRequiredDescription
projectIdStringYesNotifly의 설정 페이지에서 확인하실 수 있습니다.
Request Headers​
ParameterValueDescription
Content-Typeapplication/jsonRequest body의 MIME Type
Authorization{auth-key}Authentication endpoint를 통해 수령한 인증 토큰
Query Parameters​
ParameterTypeRequiredDescription
channelIdStringNo알림톡 채널 ID. 등록된 채널이 여러개일 경우 사용됩니다. 넘기지 않을 경우 먼저 등록된 채널로 지정 됩니다.
templateCodeStringNo템플릿 코드
templateNameStringNo템플릿 이름
templateStatusStringNo템플릿 상태 코드
pageNumIntegerNo페이지 번호(Default: 1)
pageSizeIntegerNo조회 건수(Default: 15, Max: 1000)
Template Status Code​
CodeDescription
TSC01요청
TSC02검수 중
TSC03승인
TSC04반려

Sample Request​

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

Response​

{
  "resultCode": 0,
  "resultMessage": "Success",d
  "templateListResponse": {
    "templates": [
      {
        "plusFriendId": "String",
        "senderKey": "String",
        "plusFriendType": "String",
        "templateCode": "String",
        "kakaoTemplateCode": "String",
        "templateName": "String",
        "templateMessageType": "String",
        "templateEmphasizeType": "String",
        "templateContent": "String",
        "templateExtra": "String",
        "templateAd": "String",
        "templateTitle": "String",
        "templateSubtitle": "String",
        "templateHeader": "String",
        "templateItem": {
          "list": [
            {
              "title": "String",
              "description": "String"
            }
          ],
          "summary": {
            "title": "String",
            "description": "String"
          }
        },
        "templateItemHighlight": {
          "title": "String",
          "description": "String",
          "imageUrl": "String"
        },
        "templateRepresentLink": {
          "linkMo": "String",
          "linkPc": "String",
          "schemeIos": "String",
          "schemeAndroid": "String"
        },
        "templateImageName": "String",
        "templateImageUrl": "String",
        "buttons": [
          {
            "ordering": 1,
            "type": "String",
            "name": "String",
            "linkMo": "String",
            "linkPc": "String",
            "schemeIos": "String",
            "schemeAndroid": "String",
            "bizFormId": 1,
            "pluginId": "String"
          }
        ],
        "quickReplies": [
          {
            "ordering": 1,
            "type": "String",
            "name": "String",
            "linkMo": "String",
            "linkPc": "String",
            "schemeIos": "String",
            "schemeAndroid": "String",
            "bizFormId": 1
          }
        ],
        "comments": [
          {
            "id": 1,
            "content": "String",
            "userName": "String",
            "createdAt": "String",
            "attachment": [
              {
                "originalFileName": "String",
                "filePath": "String"
              }
            ],
            "status": "String"
          }
        ],
        "status": "String",
        "statusName": "String",
        "securityFlag": true,
        "categoryCode": "String",
        "createDate": "String",
        "updateDate": "String"
      }
    ],
    "totalCount": 100
  }
}

10.2 템플릿 등록​

Endpoint

POST https://api.notifly.tech/projects/{projectId}/messages/kakao-alimtalk/templates

Specifications​

Path Parameters​
ParameterTypeRequiredDescription
projectIdStringYesNotifly의 설정 페이지에서 확인하실 수 있습니다.
Request Headers​
ParameterValueDescription
Content-Typeapplication/jsonRequest body의 MIME Type
Authorization{auth-key}Authentication endpoint를 통해 수령한 인증 토큰
Request Body​
{
  "channelId": "String",
  "templateName": "String",
  "templateContent": "String",
  "templateMessageType": "String",
  "templateEmphasizeType": "String",
  "templateExtra": "String",
  "templateTitle": "String",
  "templateSubtitle": "String",
  "templateHeader": "String",
  "templateItem": {
    "list": [
      {
        "title": "String",
        "description": "String"
      }
    ],
    "summary": {
      "title": "String",
      "description": "String"
    }
  },
  "templateItemHighlight": {
    "title": "String",
    "description": "String",
    "imageUrl": "String"
  },
  "templateRepresentLink": {
    "linkMo": "String",
    "linkPc": "String",
    "schemeIos": "String",
    "schemeAndroid": "String"
  },
  "templateImageName": "String",
  "templateImageUrl": "String",
  "securityFlag": "Boolean",
  "categoryCode": "String",
  "buttons": [
    {
      "ordering": "Integer",
      "type": "String",
      "name": "String",
      "linkMo": "String",
      "linkPc": "String",
      "schemeIos": "String",
      "schemeAndroid": "String",
      "bizFormId": "Integer",
      "pluginId": "String"
    }
  ],
  "quickReplies": [
    {
      "ordering": "Integer",
      "type": "String",
      "name": "String",
      "linkMo": "String",
      "linkPc": "String",
      "schemeIos": "String",
      "schemeAndroid": "String",
      "bizFormId": "Integer"
    }
  ]
}
필드 설명​
ParameterTypeRequiredDescription
channelIdStringNo알림톡 채널 ID. 등록된 채널이 여러개일 경우 사용됩니다. 넘기지 않을 경우 먼저 등록된 채널로 지정 됩니다.
templateCodeStringYes템플릿 코드 (최대 20자), Unique한 코드를 직접 생성해서 보내주세요. 콭솔에서는 9자의 랜덤한 문자열을 생성해서 사용 하고 있습니다.
templateNameStringYes템플릿명 (최대 150자)
templateContentStringYes템플릿 본문 (최대 1000자)
templateMessageTypeStringNo템플릿 메시지 유형 (BA: 기본형, EX: 부가 정보형, AD: 채널 추가형, MI: 복합형, 기본값: BA)
templateEmphasizeTypeStringNo템플릿 강조 표시 타입 (NONE: 기본, TEXT: 강조 표시, IMAGE: 이미지형, ITEM_LIST: 아이템리스트형, 기본값: NONE)
templateExtraStringNo템플릿 부가 정보 (템플릿 메시지 유형이 EX 또는 MI일 경우 필수)
templateTitleStringNo템플릿 제목 (최대 50자, Android: 2줄, 23자 이상 말줄임 처리, iOS: 2줄, 27자 이상 말줄임 처리)
templateSubtitleStringNo템플릿 보조 문구 (최대 50자, Android: 18자 이상 말줄임 처리, iOS: 21자 이상 말줄임 처리)
templateHeaderStringNo템플릿 헤더 (최대 16자)
templateItemObjectNo아이템 정보
templateItem.listList of ObjectsNo아이템 리스트 (최소 2개, 최대 10개)
templateItem.list.titleStringYes아이템 타이틀 (최대 6자)
templateItem.list.descriptionStringYes아이템 디스크립션 (최대 23자)
templateItem.summaryObjectYes아이템 요약 정보
templateItem.summary.titleStringYes요약 타이틀 (최대 6자)
templateItem.summary.descriptionStringYes요약 디스크립션 (변수 및 화폐 단위, 숫자, 쉼표, 마침표만 사용 가능, 최대 14자)
templateItemHighlightObjectNo아이템 하이라이트
templateItemHighlight.titleStringYes하이라이트 타이틀 (최대 30자, 섬네일 이미지가 있을 경우 21자)
templateItemHighlight.descriptionStringYes하이라이트 디스크립션 (최대 19자, 섬네일 이미지가 있을 경우 13자)
templateItemHighlight.imageUrlStringYes섬네일 이미지 URL
templateRepresentLinkObjectYes대표 링크
templateRepresentLink.linkMoStringYes모바일 웹 링크 (최대 500자)
templateRepresentLink.linkPcStringNoPC 웹 링크 (최대 500자)
templateRepresentLink.schemeIosStringNoiOS 앱 링크 (최대 500자)
templateRepresentLink.schemeAndroidStringNo안드로이드 앱 링크 (최대 500자)
templateImageNameStringNo이미지명 (업로드한 파일명)
templateImageUrlStringNo이미지 URL
securityFlagBooleanNo보안 템플릿 여부 (OTP 등 보안 메시지일 경우 설정, 기본값: false)
categoryCodeStringNo템플릿 카테고리 코드 (템플릿 카테고리 조회 API 참고, 기본값: 999999)
buttonsList of ObjectsNo버튼 리스트 (최대 5개)
buttons.orderingIntegerYes버튼 순서 (1~5)
buttons.typeStringYes버튼 타입 (WL: 웹 링크, AL: 앱 링크, DS: 배송 조회, BK: 봇 키워드, MD: 메시지 전달, BC: 상담톡 전환, BT: 봇 전환, AC: 채널 추가, BF: 비즈니스폼, P1: 이미지 보안 전송 플러그인 ID, P2: 개인정보이용 플러그인 ID, P3: 원클릭 결제 플러그인 ID)
buttons.nameStringYes버튼 이름 (최대 14자)
buttons.linkMoString조건부모바일 웹 링크 (WL 타입일 경우 필수, 최대 500자)
buttons.linkPcStringNoPC 웹 링크 (WL 타입일 경우 선택, 최대 500자)
buttons.schemeIosString조건부iOS 앱 링크 (AL 타입일 경우 필수, 최대 500자)
buttons.schemeAndroidString조건부안드로이드 앱 링크 (AL 타입일 경우 필수, 최대 500자)
buttons.bizFormIdInteger조건부비즈니스폼 ID (BF 타입일 경우 필수)
buttons.pluginIdStringNo플러그인 ID (최대 24자)
quickRepliesList of ObjectsNo바로연결 리스트 (최대 5개)
quickReplies.orderingIntegerYes바로연결 순서 (필수)
quickReplies.typeStringYes바로연결 타입 (WL: 웹 링크, AL: 앱 링크, BK: 봇 키워드, BC: 상담톡 전환, BT: 봇 전환, BF: 비즈니스폼)
quickReplies.nameStringYes바로연결 이름 (최대 14자)
quickReplies.linkMoString조건부모바일 웹 링크 (WL 타입일 경우 필수, 최대 500자)
quickReplies.linkPcStringNoPC 웹 링크 (WL 타입일 경우 선택, 최대 500자)
quickReplies.schemeIosString조건부iOS 앱 링크 (AL 타입일 경우 필수, 최대 500자)
quickReplies.schemeAndroidString조건부안드로이드 앱 링크 (AL 타입일 경우 필수, 최대 500자)
quickReplies.bizFormIdInteger조건부비즈니스폼 ID (BF 타입일 경우 필수)
주의 사항​
  • 템플릿 메시지 유형이 EX 또는 MI일 경우, templateExtra 필드를 반드시 포함해야 합니다.
  • 템플릿 강조 표시 타입이 TEXT일 경우, templateTitle과 templateSubtitle 필드를 필수로 포함해야 합니다.
  • 템플릿 강조 표시 타입이 IMAGE일 경우, templateImageName과 templateImageUrl 필드를 필수로 포함해야 합니다.
  • 템플릿 아이템 리스트는 최소 2개에서 최대 10개까지 포함할 수 있습니다.
  • 버튼 타입에 따라 필수 필드가 다릅니다. 예를 들어, WL 타입의 버튼은 linkMo가 필수이며, AL 타입의 버튼은 schemeIos 및 schemeAndroid가 필수입니다.
  • 빠른 연결(Quick Replies) 역시 버튼과 유사하게 타입에 따라 필수 필드가 다릅니다.
Response Headers​
ParameterValue
Status code200 OK
Status code400 Bad Request
Status code500 Internal Server Error
Response Body​
{
  "resultCode": 0,
  "resultMessage": "Success"
}
필드 설명​
FieldTypeDescription
resultCodeInteger결과 코드
resultMessageString결과 메시지

Sample Request​

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

{
  "channelId": "channel-id",
  "templateCode": "template-code",
  "templateName": "template-name",
  "templateContent": "This is a template content.",
  "templateMessageType": "BA",
  "templateEmphasizeType": "NONE",
  "templateTitle": "Template Title",
  "templateSubtitle": "Template Subtitle",
  "templateItem": {
    "list": [
      {
        "title": "Item 1",
        "description": "Description 1"
      },
      {
        "title": "Item 2",
        "description": "Description 2"
      }
    ],
    "summary": {
      "title": "Summary Title",
      "description": "Summary Description"
    }
  },
  "templateRepresentLink": {
    "linkMo": "http://example.com",
    "linkPc": "http://example.com",
    "schemeIos": "app://example",
    "schemeAndroid": "app://example"
  },
  "categoryCode": "999999",
  "buttons": [
    {
      "ordering": 1,
      "type": "WL",
      "name": "Visit Site",
      "linkMo": "http://example.com",
      "linkPc": "http://example.com"
    }
  ],
  "quickReplies": [
    {
      "ordering": 1,
      "type": "WL",
      "name": "Help",
      "linkMo": "http://example.com/help",
      "linkPc": "http://example.com/help"
    }
  ]
}

10.3 템플릿 수정​

Endpoint

PUT https://api.notifly.tech/projects/{projectId}/messages/kakao-alimtalk/templates/{templateCode}

Specifications​

Path Parameters​
ParameterTypeRequiredDescription
projectIdStringYesNotifly의 설정 페이지에서 확인하실 수 있습니다.
templateCodeStringYes수정할 템플릿 코드
Request Headers​
ParameterValueDescription
Content-Typeapplication/jsonRequest body의 MIME Type
Authorization{auth-key}Authentication endpoint를 통해 수령한 인증 토큰
Request Body​

템플릿 등록과 동일한 형식으로 요청 본문을 구성합니다. 다만, templateCode는 URL의 Path Parameter로 전달되므로 본문에서는 제외할 수 있습니다.

{
  "channelId": "String",
  "templateName": "String",
  "templateContent": "String",
  "templateMessageType": "String",
  "templateEmphasizeType": "String",
  "templateExtra": "String",
  "templateTitle": "String",
  "templateSubtitle": "String",
  "templateHeader": "String",
  "templateItem": {
    "list": [
      {
        "title": "String",
        "description": "String"
      }
    ],
    "summary": {
      "title": "String",
      "description": "String"
    }
  },
  "templateItemHighlight": {
    "title": "String",
    "description": "String",
    "imageUrl": "String"
  },
  "templateRepresentLink": {
    "linkMo": "String",
    "linkPc": "String",
    "schemeIos": "String",
    "schemeAndroid": "String"
  },
  "templateImageName": "String",
  "templateImageUrl": "String",
  "securityFlag": true,
  "categoryCode": "String",
  "buttons": [
    {
      "ordering": 1,
      "type": "String",
      "name": "String",
      "linkMo": "String",
      "linkPc": "String",
      "schemeIos": "String",
      "schemeAndroid": "String",
      "bizFormId": "Integer",
      "pluginId": "String"
    }
  ],
  "quickReplies": [
    {
      "ordering": 1,
      "type": "String",
      "name": "String",
      "linkMo": "String",
      "linkPc": "String",
      "schemeIos": "String",
      "schemeAndroid": "String",
      "bizFormId": "Integer"
    }
  ]
}
필드 설명​

템플릿 등록과 동일한 필드 설명을 참고하세요. 단, templateCode는 URL 경로에서 지정되므로 본문에서는 제외됩니다.

주의 사항​
  • 템플릿 수정 시, 템플릿 메시지 유형 및 템플릿 강조 표시 타입에 따른 필수 필드를 준수해야 합니다.
  • 템플릿 아이템 리스트, 버튼, 빠른 연결 등은 필요에 따라 포함하거나 제외할 수 있습니다.
  • 버튼 타입에 따라 필수 필드가 다르므로 주의하여 입력해야 합니다.
Response Headers​
ParameterValue
Status code200 OK
Status code400 Bad Request
Status code500 Internal Server Error
Response Body​
{
  "resultCode": 0,
  "resultMessage": "Success"
}
필드 설명​
FieldTypeDescription
resultCodeInteger결과 코드
resultMessageString결과 메시지

Sample Request​

PUT https://api.notifly.tech/projects/{projectId}/messages/kakao-alimtalk/templates/{templateCode}
Content-Type: application/json
Authorization: {auth-key}

{
  "channelId": "Channel ID",
  "templateName": "Updated Template Name",
  "templateContent": "Updated template content.",
  "templateMessageType": "EX",
  "templateEmphasizeType": "TEXT",
  "templateExtra": "Additional information.",
  "templateTitle": "Updated Title",
  "templateSubtitle": "Updated Subtitle",
  "templateItem": {
    "list": [
      {
        "title": "New Item 1",
        "description": "New Description 1"
      },
      {
        "title": "New Item 2",
        "description": "New Description 2"
      }
    ],
    "summary": {
      "title": "New Summary Title",
      "description": "New Summary Description"
    }
  },
  "templateRepresentLink": {
    "linkMo": "http://newexample.com",
    "linkPc": "http://newexample.com",
    "schemeIos": "newapp://example",
    "schemeAndroid": "newapp://example"
  },
  "categoryCode": "888888",
  "buttons": [
    {
      "ordering": 1,
      "type": "AL",
      "name": "Open App",
      "schemeIos": "app://open",
      "schemeAndroid": "app://open"
    }
  ],
  "quickReplies": [
    {
      "ordering": 1,
      "type": "WL",
      "name": "Support",
      "linkMo": "http://newexample.com/support",
      "linkPc": "http://newexample.com/support"
    }
  ]
}

10.4 템플릿 삭제​

Endpoint

DELETE https://api.notifly.tech/projects/{projectId}/messages/kakao-alimtalk/templates/{templateCode}?channelId=${channelId}

Specifications​

Path Parameters​
ParameterTypeRequiredDescription
projectIdStringYesNotifly의 설정 페이지에서 확인하실 수 있습니다.
templateCodeStringYes삭제할 템플릿 코드
Query Parameters​
ParameterTypeRequiredDescription
channelIdStringNo알림톡 채널 ID. 등록된 채널이 여러개일 경우 사용됩니다. 넘기지 않을 경우 먼저 등록된 채널로 지정 됩니다.
Request Headers​
ParameterValueDescription
Content-Typeapplication/jsonRequest body의 MIME Type
Authorization{auth-key}Authentication endpoint를 통해 수령한 인증 토큰
Response Headers​
ParameterValue
Status code200 OK
Status code400 Bad Request
Status code500 Internal Server Error
Response Body​
{
  "resultCode": 0,
  "resultMessage": "Success"
}
필드 설명​
FieldTypeDescription
resultCodeInteger결과 코드
resultMessageString결과 메시지

Sample Request​

DELETE https://api.notifly.tech/projects/{projectId}/messages/kakao-alimtalk/templates/{templateCode}
Content-Type: application/json
Authorization: {auth-key}

11. Send Kakao Friendtalk Message​

이 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"
      }
    }
  ]
}