API 트리거 캠페인 발송하기

API 트리거 캠페인을 발송하는 방법을 설명합니다. 블럭스 담당자에게 문의하여 발급받은 secret key를 사용해서 캠페인을 발송할 수 있습니다.

개요

• API 트리거 캠페인은 콘솔에서 생성한 후, 외부 시스템에서 직접 API를 호출하여 메시지를 발송할 수 있는 기능입니다.
• 실시간 혹은 특정 시점에 외부 이벤트에 의해 발송을 제어하고자 할 때 유용합니다.

전제 조건

1. 블럭스 콘솔에 로그인하여 API 트리거 캠페인을 생성해야 합니다.
2. 캠페인에는 사용자가 설정한 변수(api_trigger.변수명)를 등록할 수 있으며, 이후 API 호출 시 해당 값을 전달해야 합니다.
3. 캠페인은 반드시 "활성화" 상태여야 발송할 수 있습니다.

캠페인 생성 및 활성화

1. 콘솔의

   캠페인
   메뉴에서 새로운 캠페인을 생성합니다.

2. 캠페인 유형을 API 트리거로 선택합니다.

3. 아래와 같이 변수를 추가합니다:

   api_trigger.age
   api_trigger.name

4. 캠페인 저장 후 활성화 버튼을 클릭해야 API 호출이 가능합니다.

발송 API

엔드포인트

POST https://api.blux.ai/prod/applications/{APPLICATION_ID}/campaigns/{CAMPAIGN_ID}/trigger

인증

요청 시 Authorization 헤더에 발급받은 secret key를 포함해야 합니다:

Authorization: {SECRET_KEY}

요청 본문

{
  "recipients": [
    {
      "user_id": "string",
      "dynamic_variables": {
        "api_trigger": {
          "변수명": "값"
        }
      }
    }
  ]
}

필드 설명

필드	타입	필수	설명
recipients	Array<object>	필수	발송 대상자 목록 (최대 500명까지 지원)
↳ user_id	string	필수	수신자 고유 ID
↳ dynamic_variables	object	선택	개인화 변수. 캠페인 생성 시 메시지 내에서 정의된 api_trigger.{key} 형식과 일치해야 합니다.

응답

성공 시:

{
  "recipients_count": 1,
  "sent_count": 1,
  "errors_count": 0
}

실패 시 (예: 유효하지 않은 user_id):

{
  "recipients_count": 1,
  "sent_count": 0,
  "errors_count": 1
}

필드 설명

필드	타입	설명
recipients_count	number	요청에 포함된 전체 수신자 수
sent_count	number	발송이 시도된 수신자 수
errors_count	number	발송 실패한 수신자 수

제한 사항

• 한 요청당 최대 recipients 수: 500명
• 초당 요청 수: 제한 없음, 단 시스템 권장치로 초당 10건 이하 권장
• 내부적으로 AWS Lambda (reserved concurrency 100) 및 SQS 기반으로 처리됩니다
• 수신자 수가 많은 경우 발송 지연이 발생할 수 있습니다. 대량 발송은 사전 협의 바랍니다

발송 불가 조건

• 캠페인이 비활성 상태이거나 만료된 경우
• 잘못된 application_id 또는 campaign_id
• 수신자의 user_id가 존재하지 않거나 무효한 경우
• 수신자의 user data에 해당 매체를 발송하기 위한 정보가 없는 경우 (ex: 휴대폰 번호, 이메일 주소)

상태 코드

코드	설명
200 OK	요청이 정상적으로 수락되어 SQS에 등록됨
400 Bad Request	필수 필드 누락, 잘못된 값 전달 시
401 Unauthorized	인증 실패 (secret key 오류)
500 Internal Server Error	서버 내부 오류

테스트 예시

curl -X POST https://api.blux.ai/prod/applications/abcd1234/campaigns/efgh5678/trigger \
  -H "Authorization: xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      {
        "user_id": "blux-test",
        "dynamic_variables": {
          "api_trigger": {
            "age": "126"
          }
        }
      }
    ]
  }'

💬 200 OK를 반환하면 발송 요청은 수락되었음을 의미합니다. 발송 성공 여부는 errors_count로 확인하세요.

자주 묻는 질문 (FAQ)

Q. 발송 성공 여부는 실시간으로 알 수 있나요? A. 아니요. 요청은 SQS에 enqueue되고, 이후 백엔드 worker가 순차적으로 발송합니다.

Q. email, phone number로는 발송 못 하나요? A. 현재는 user_id 기반 발송만 지원하며, 이메일/폰 번호 직접 발송은 지원하지 않습니다.

Q. 하나의 캠페인으로 여러 번 발송해도 되나요? A. 네. 같은 캠페인 ID로 여러 번 호출 가능합니다. 단, 동일 user_id로 하루에 여러 번 발송 시 빈도 제한 정책이 적용될 수 있습니다.

---

추가 문의는 블럭스 기술지원팀에 연락주세요.