본문으로 건너뛰기

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 트리거 캠페인 생성 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": {
          "변수명": "값"
        }
      }
    }
  ]
}

필드 설명​

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

응답​

성공 시:

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

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

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

필드 설명​

필드타입설명
recipients_countnumber요청에 포함된 전체 수신자 수
sent_countnumber발송이 시도된 수신자 수
errors_countnumber발송 실패한 수신자 수

제한 사항​

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

발송 불가 조건​

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

상태 코드​

코드설명
200 OK요청이 정상적으로 수락되어 SQS에 등록됨
400 Bad Request필수 필드 누락, 잘못된 값 전달 시
400 Bad Request인증 실패 (secret key 오류, errorCode: UnAuthorized)
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로 하루에 여러 번 발송 시 빈도 제한 정책이 적용될 수 있습니다.



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