메시지 발송 / 예약

API 캠페인을 기반으로 다수의 수신자에게 메시지를 발송하는 API 입니다.

기본 정보

Base URL

https://api-v2.effic.biz/

주의 사항

워크스페이스 마다 10 req/s 로 rate limit 이 제한되어 있습니다.
최대 30초간 캠페인 변경 사항이 반영되지 않을 수 있습니다. 예시:
- 캠페인을 비활성 후에도 요청이 성공할 수 있습니다. 이는 API 서버가 일시적으로 이전 상태의 캠페인을 참조하기 때문입니다. 그러나 실제 메시지를 발송하는 시스템에서는 항상 최신 상태의 캠페인 정보를 기준으로 검증 하므로, 비활성화된 캠페인의 경우 발송은 최종적으로 이루어지지 않습니다.

요청

URL: POST api-campaign/message
Content-Type: application/json

Header

항목

필수 여부

설명

Authorization

Yes

Basic 인증 방식으로 API 키를 포함

[에픽 워크스페이스 API 키 가이드]

Body

{
  "campaignId": "3f267b36-c3bb-4d04-bf91-9288b98f2021",
  "recipients": [
    {
      "receiverNumber": "01012345678",
      "variables": {
        "name": "김에픽",
        "coupon": "HALF_COUPON"
      }
    },
    {
      "receiverNumber": "01098765432",
      "variables": {
        "name": "박에픽",
        "coupon": "HALF_COUPON"
      }
    }
  ],
  "reservationTime": "2015-05-10 10:03"
}

필드명

타입

필수

설명

campaignId

string (UUID)

Yes

API캠페인의 ID

recipients

array

Yes

수신자 정보 목록 (1~300명까지)

receiverNumber

string

Yes

수신자 전화번호

variables

object

변수데이터를 위한 키-값 쌍

reservationTime

string

예약 시간 (yyyy-MM-dd HH:mm)

주의사항

수신자 목록 전체 JSON 크기는 50KB 이하로 제한됩니다.
reservationTime
- 현재 시간으로부터 최소 10분 후부터 최대 10일 이내로 설정 가능합니다.
- yyyy-MM-dd HH:mm 형식으로 요청 해야합니다
receiverNumber 필드는 메시지 전송을 위해 다음과 같은 유효성 검사를 거칩니다:
- 번호가 null이거나 정의되지 않은 경우 유효하지 않습니다.
- 010 또는 10으로 시작하고 8자리 숫자가 뒤따라야 합니다.
- +82 또는 82로 시작하고 10자리 숫자가 뒤따라야 합니다.
- 유효한 경우, 010XXXXXXXX 형식으로 정규화됩니다.
- 해외 번호는 국제 표준에 따라 유효성이 검사됩니다.

응답

{
  "requestId": "8d267b36-afad-3d04-bc91-3488b983421",
  "msgResults": [
    {
      "receiverNumber": "01012345678",
      "success": true,
      "traceId": "exec:3f267b36-c3bb-4d04-bf91-9288b98f203:seq:0"
    },
    {
      "receiverNumber": "010123443434355",
      "success": false,
      "reason": "유효하지 않은 전화번호 형식"
    }
  ],
  "successCount": 1,
  "failureCount": 1
}

응답 필드 설명

필드명

타입

필수 여부

설명

requestId

string (UUID)

Yes

요청 추적 ID

msgResults

array

Yes

수신자별 발송 결과

successCount

number

Yes

성공한 수신자 수

failureCount

number

Yes

실패한 수신자 수

msgResults.receiverNumber

string

수신자 번호

msgResults.success

boolean

Yes

요청 결과 성공 여부

msgResults.reason

string

실패 사유

msgResults.traceId

string

메시지 전송 과정을 추적하기 위한 고유 식별자

오류 응답

모든 오류 응답은 아래 형식을 따릅니다:

{
  "statusCode": "422",
  "message": "수신자는 최소 1명 이상이어야 합니다.",
}

오류 코드 목록

코드

설명

422

필드 누락, UUID 형식 오류, 수신자 수 초과 등

404

존재하지 않는 캠페인 ID

400

캠페인 비활성화, 발신 정보 미설정, 야간 발송 불가 등

401

인증 실패

500

서버 내부 처리 중 오류 발생

429

rate limit 초과

PreviousAPI 캠페인 (API 발송)Next메시지 예약 취소

Last updated 3 months ago