캠페인 트리거

curl --request POST \
  --url https://api.notifly.tech/projects/{projectId}/campaigns/{campaignId}/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "recipients": [
    {
      "type": "phone-number",
      "phoneNumber": "010-1234-5678"
    }
  ]
}
'

{
  "code": 200,
  "success": true,
  "error": null
}

POST

projects

{projectId}

campaigns

{campaignId}

send

curl --request POST \
  --url https://api.notifly.tech/projects/{projectId}/campaigns/{campaignId}/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "recipients": [
    {
      "type": "phone-number",
      "phoneNumber": "010-1234-5678"
    }
  ]
}
'

{
  "code": 200,
  "success": true,
  "error": null
}

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

푸시 알림
웹 푸시 알림
카카오 알림톡
카카오 친구톡
카카오 브랜드 메시지
문자 메시지
이메일
라인

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

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

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

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

푸시 알림: 동일한 디바이스 토큰일 경우, 하나의 디바이스 토큰에만 메시지를 발송합니다.
웹 푸시 알림: 동일한 디바이스 토큰일 경우, 하나의 디바이스 토큰에만 메시지를 발송합니다.
카카오 알림톡: 동일한 전화번호일 경우, 하나의 전화번호에만 메시지를 발송합니다.
카카오 친구톡: 동일한 전화번호일 경우, 하나의 전화번호에만 메시지를 발송합니다.
카카오 브랜드 메시지: 동일한 전화번호일 경우, 하나의 전화번호에만 메시지를 발송합니다.
문자 메시지: 동일한 전화번호일 경우, 하나의 전화번호에만 메시지를 발송합니다.
이메일: 동일한 이메일 주소일 경우, 하나의 이메일 주소에만 메시지를 발송합니다.
라인: 동일한 라인 유저 ID일 경우, 하나의 라인 유저 ID에만 메시지를 발송합니다.

400 Bad Request - invalid recipients 상세수신자 검증 실패 시, 400 응답에 errorDetails가 포함됩니다.

{
  "code": 400,
  "success": false,
  "error": "Bad request: invalid recipients",
  "errorDetails": {
    "reasonCode": "INVALID_RECIPIENTS",
    "channel": "kakao-friendtalk",
    "invalidRecipientCount": 2,
    "invalidRecipients": [
      {
        "index": 0,
        "type": "user-id",
        "userId": "user_001",
        "reasonCode": "MISSING_PHONE_NUMBER",
        "source": { "pointer": "/recipients/0/userId" }
      },
      {
        "index": 12,
        "type": "user-id",
        "userId": "user_013",
        "reasonCode": "MISSING_PHONE_NUMBER",
        "source": { "pointer": "/recipients/12/userId" }
      }
    ]
  }
}

errorDetails 필드 설명:

필드	타입	설명
`reasonCode`	string	항상 `INVALID_RECIPIENTS`
`channel`	string	캠페인 채널 (`text-message`, `kakao-alimtalk`, `kakao-friendtalk`, `kakao-brand-message`, `email`)
`invalidRecipientCount`	number	유효하지 않은 수신자 수
`invalidRecipients`	array	유효하지 않은 수신자 목록
`invalidRecipients[].index`	number	요청 `recipients` 배열에서의 인덱스 (0-based)
`invalidRecipients[].type`	string	항상 `user-id`
`invalidRecipients[].userId`	string	요청에서 전달한 `userId` 값
`invalidRecipients[].reasonCode`	string	`MISSING_PHONE_NUMBER` 또는 `MISSING_EMAIL`
`invalidRecipients[].source.pointer`	string	JSON Pointer 형식의 요청 필드 위치

채널별 검증 규칙:

채널	필수 필드	reasonCode
`text-message`	`phone_number`	`MISSING_PHONE_NUMBER`
`kakao-alimtalk`	`phone_number`	`MISSING_PHONE_NUMBER`
`kakao-friendtalk`	`phone_number`	`MISSING_PHONE_NUMBER`
`kakao-brand-message`	`phone_number`	`MISSING_PHONE_NUMBER`
`email`	`email`	`MISSING_EMAIL`
`push-notification` / `web-push-notification`	검증 없음	-

핵심 동작:

code, success, error는 항상 포함되며, errorDetails는 수신자 검증 실패 시에만 선택적으로 추가됩니다.
잘못된 파라미터, 비활성 캠페인 등 다른 400 에러에서는 errorDetails가 포함되지 않습니다.
user-id 타입 수신자가 Notifly DB에 존재하지만 해당 채널의 필수 연락처(전화번호 또는 이메일)가 누락된 경우 invalid로 판정됩니다.
DB에 존재하지 않는 userId는 invalid로 취급하지 않고 무시됩니다.
partialSend가 false이거나 미지정인 경우, 1명이라도 invalid 수신자가 있으면 전체 요청이 실패(400)하며, 메시지는 발송되지 않습니다.
클라이언트는 errorDetails.invalidRecipients를 참조하여 문제 수신자를 제거한 뒤 재요청할 수 있습니다.

부분 발송 (partialSend)partialSend를 true로 설정하면, 일부 수신자의 전화번호 또는 이메일이 누락되어 있어도 유효한 수신자에게만 발송을 진행합니다.

partialSend: false (기본값): 1명이라도 invalid 수신자가 있으면 전체 요청이 400 에러로 실패하며, 아무에게도 발송되지 않습니다.
partialSend: true: 유효한 수신자에게만 발송을 진행하고, 응답에 invalid 수신자 목록을 포함합니다. 전체 수신자가 invalid인 경우에도 200 응답이 반환됩니다.

partialSend: true 응답 예시 (일부 invalid):

{
  "code": 200,
  "success": true,
  "error": null,
  "errorDetails": {
    "reasonCode": "INVALID_RECIPIENTS",
    "channel": "kakao-alimtalk",
    "invalidRecipientCount": 2,
    "invalidRecipients": [
      {
        "index": 1,
        "type": "user-id",
        "userId": "user_002",
        "reasonCode": "MISSING_PHONE_NUMBER",
        "source": { "pointer": "/recipients/1/userId" }
      },
      {
        "index": 3,
        "type": "user-id",
        "userId": "user_004",
        "reasonCode": "MISSING_PHONE_NUMBER",
        "source": { "pointer": "/recipients/3/userId" }
      }
    ]
  }
}

지원 채널: kakao-alimtalk, kakao-friendtalk, kakao-brand-message, text-message, email

type: "phone-number" 또는 type: "email"로 직접 지정한 수신자는 validation 대상이 아닙니다.

인증

Authorization

string

header

필수

POST /authenticate로 발급받은 인증 토큰을 Bearer 형식으로 전달합니다.

경로 매개변수

projectId

string

필수

프로젝트 ID

campaignId

string

필수

캠페인 ID (콘솔에서 확인)

본문

application/json

recipients

object[]

필수

수신자 목록 (최대 1,000명)

Show child attributes

partialSend

boolean

기본값:false

true로 설정 시, 일부 수신자의 전화번호/이메일이 없어도 유효한 수신자에게만 발송을 진행하고 invalid 수신자 목록을 응답에 포함합니다. false이거나 미지정 시 기존 동작(invalid 수신자가 있으면 전체 실패) 유지.

응답

캠페인이 성공적으로 트리거되었습니다. partialSend가 true이고 일부 수신자가 invalid인 경우, errorDetails가 포함됩니다.

code

integer

success

boolean

error

string | null

errorDetails

object

partialSend: true인 경우, 일부 수신자가 invalid이면 포함됩니다.

Show child attributes

시작하기

인증

이벤트 & 유저

캠페인

메시징

메시징 관리

카탈로그

내보내기 & 분석

인증

경로 매개변수

본문

응답