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를 통해 직접 트리거하여 지정된 수신자에게 발송합니다.
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, emailtype: "phone-number" 또는 type: "email"로 직접 지정한 수신자는 validation 대상이 아닙니다.인증
POST /authenticate로 발급받은 인증 토큰을 Bearer 형식으로 전달합니다.
본문
application/json