발송 결과 조회 API

API는 캠페인 유형, 캠페인 ID, 날짜 범위를 기준으로 메시지를 조회하는 기능을 제공합니다. 조회 가능한 메시지 유형으로는 문자 메시지, 알림톡, 친구톡이 있습니다.

기본 정보

---

API URL

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

데이터 조회 제한 사항

• 캠페인 실행 후 최소 30분 이후에 조회 결과를 확인할 수 있습니다.

• 발송 후처리(대체 발송, 문자 수신 결과 추적)로 인해 최대 3일까지 발송 결과가 변경될 수 있으며, 매일 오전 2시에 데이터가 갱신됩니다.

• 발송 결과는 최대 90일 이전까지 조회할 수 있습니다.

• 조회에 대한 API rate limit 은 2 req/s 로 제한 됩니다.

요청

---

요청 예시

GET /message?type=auto&campaignId=12345&startDate=20250101&endDate=20250131
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Header

항목	필수 여부	설명
Authorization	Yes	Basic 인증 방식으로 API 키를 포함
token	No	다음 페이지 조회를 위한 토큰

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

• 첫 번째 요청에는 token을 포함하지 않으며, 응답에서 nextToken 값을 받아 다음 페이지를 조회할 때 사용합니다.

• token 값이 유효하지 않으면 BadRequestException이 발생합니다.

• token은 단순한 페이징을 위한 값이 아니라, 캠페인 실행 기준으로 데이터를 구분하는 역할을 합니다.

  1. 첫 번째 요청에는 token 없이 API를 호출합니다.

  2. 응답에 nextToken 값이 포함될 경우, 이후 요청에서 token을 사용하여 추가 데이터를 조회해야 합니다.

  3. 하나의 캠페인 실행 기준으로 10,000개 이상의 메시지가 존재하면 token이 나뉘어 제공됩니다.

     • 즉, token은 실행된 캠페인 단위별로 데이터를 구분하며, 해당 실행에서 메시지가 많을 경우 추가적으로 분할된 데이터 조회를 위해 필요합니다.

  4. token이 더 이상 반환되지 않으면, 모든 데이터를 조회한 것입니다.

Parameter

파라미터	타입	필수 여부	설명
type	string	No	캠페인 유형 (auto 또는 onetime)
campaignId	string	No	캠페인의 고유 ID
startDate	string	Yes	조회 시작 날짜 (YYYY-MM-DD 형식)
endDate	string	Yes	조회 종료 날짜 (YYYY-MM-DD 형식)

• startDate 는 90일 이전까지 설정 가능합니다

• type 과 campaignId 는 동시에 설정되어야 합니다.

응답

---

Body

{
  "data": [
    { 
      "id": "1245",
      "status": "success",
      "type": "alimtalk",
      "callerNumber": "02-1234-1234",
      "registeredAt": "2025-01-01T10:00:00Z",
      "receiverNumber": "010-1234-5678",
      "receivedAt": "2025-01-01T10:07:00Z",
      "subject" : "제목입니다!",
      "content": "내용입니다!",
      "campaignName": "알림톡 자동화 켐페인",
      "campaignId" : "2",
      "channelName": "effic",
      "channelId": "@effic",
      "templateCode": "SIGNUP"
    }
  ],
  "nextToken": "bdfc5bde-4532-4cc1-84fe-064660ed44be"
}

• 응답 데이터는 세 가지 유형의 메시지(문자 메시지, 알림톡, 친구톡)와 nextToken 으로 구성 됩니다.

• 응답 데이터가 많을 경우, 한 번에 전송되는 데이터를 제한하기 위해 nextToken 이 포함됩니다.

• nextToken 이 있는 경우, 해당 값을 사용하여 다음 페이지 데이터를 요청할 수 있습니다.

• nextToken 이 null 이면 더 이상 조회할 데이터가 없습니다.

문자 메시지(textMessage)

필드명	타입	필수 여부	설명
id	string	Yes	메시지의 고유 ID
status	string	Yes	메시지 상태
textMessageType	string	Yes	문자 유형 (sms , lms, mms)
intentType	string	Yes	메지지 정보 유형 (ad : 광고성, info : 정보성)
callerNumber	string	Yes	발신 번호
registeredAt	string	Yes	발송 준비 시간
receiverNumber	string	No	수신 번호
receivedAt	string	No	수신 시간
subject	string	No	메시지 제목
content	string	Yes	메시지 내용
reason	string	No	실패 사유 (해당 시)
reasonDetail	string	No	상세 실패 사유
telecom	string	No	통신사 정보 (SKT , KT , LG)
campaignId	string	Yes	캠페인의 고유 ID
campaignName	string	Yes	캠페인 이름
type	string	Yes	메지지 유형 (text_message)

알림톡(alimtalk)

필드명	타입	필수 여부	설명
id	string	Yes	메시지의 고유 ID
status	string	Yes	메시지 상태
receiverNumber	string	No	수신 번호
registeredAt	string	Yes	발송 준비 시간
receivedAt	string	No	수신 시간
subject	string	No	메시지 제목
content	string	Yes	메시지 내용
reason	string	No	실패 사유 (해당 시)
reasonDetail	string	No	상세 실패 사유
templateCode	string	Yes	사용된 템플릿 코드
campaignId	string	Yes	캠페인의 고유 ID
campaignName	string	Yes	캠페인 이름
type	string	Yes	메시지 유형 (alimtalk)
channelName	string	Yes	카카오 채널 이름
channelId	string	Yes	카카오 채널 식별자
failover	object	No	대체 발송 정보
failoverContent	string	No	대체 발송 내용
failoverSubject	string	No	대체 발송 제목

친구톡(friendtalk)

필드명	타입	필수 여부	설명
id	string	Yes	메시지의 고유 ID
status	string	Yes	메시지 상태
friendtalkType	string	Yes	친구톡 유형 (image: 이미지형, wide: 와이드형, text: 텍스트형)
intentType	string	Yes	메지지 정보 유형 (ad : 광고성, info : 정보성)
receiverNumber	string	No	수신 번호
registeredAt	string	Yes	발송 준비 시간
receivedAt	string	No	수신 시간
content	string	Yes	메시지 내용
reason	string	No	실패 사유 (해당 시)
reasonDetail	string	No	상세 실패 사유
campaignId	string	Yes	캠페인의 고유 ID
campaignName	string	Yes	캠페인 이름
type	string	Yes	메시지 유형 (friendtalk)
channelName	string	Yes	카카오 채널 이름
channelId	string	Yes	카카오 채널 식별자
failover	object	No	대체 발송 정보
failoverContent	string	No	대체 발송 내용
failoverSubject	string	No	대체 발송 제목

대체 발송(failover)

필드명	타입	필수 여부	설명
txtMsgType	string	Yes	문자 유형 (sms, lms)
subject	string	No	메시지 제목
content	string	Yes	메시지 내용
receiverNumber	string	Yes	수신 번호
callerNumber	string	Yes	발신 번호

메시지 상태(status)

상태 코드	설명
blocked	차단됨 - 메시지가 전송되지 않음
filtered	필터링됨 - 내부 정책에 의해 발송 제한
ready	준비됨 - 전송 대기 상태
processing	전송 중 - 메시지가 발송 중인 상태
confirming	확인 중 - 메시지 발송 요청은 이미 완료됐으며, 수신 성공 여부를 확인 중인 상태
success	성공 - 메시지 정상 전송 완료
fail	실패 - 메시지 전송 실패
failover_processing	대체 발송 진행 중
failover_success	대체 발송 성공
failover_fail	대체 발송 실패

예시 코드(NodeJs)

---

import axios from "axios";

async function sleep(second) {
  return new Promise((resolve) => {
    setTimeout(resolve, second * 1000);
  });
}

async function fetchMessages(baseUrl, params, authToken) {
  let nextToken = null;
  let allData = [];

  do {
    try {
      const response = await axios.get(baseUrl, {
        headers: {
          Authorization: `Basic ${authToken}`,
          token: nextToken,
        },
        params: {
          ...params,
        },
      });

      allData = allData.concat(response.data.data);
      nextToken = response.data.nextToken || null;

      if (nextToken) {
        console.log(
          `Next token received: ${nextToken}. Sleeping for 1 sec to comply with rate limit.`
        );
        await sleep(1); // 2 req/s 제한 준수를 위해 1sec 대기
      }
    } catch (error) {
      console.error("API 요청 실패:", error.message);
      break;
    }
  } while (nextToken);

  return allData;
}

const baseUrl = "https://api-v2.effic.biz/message";
const params = {
  type: "auto",
  campaignId: "1",
  startDate: "2025-03-12",
  endDate: "2025-03-12",
};
const authToken = "TDBH343tG0GDFGHBFNBFNFDSGHDS"; // Base64 인코딩된 API 키

fetchMessages(baseUrl, params, authToken)
  .then((messages) => console.log("조회된 메시지 개수:", messages.length))
  .catch((err) => console.error(err.message));

• API 호출 시, rate limit 준수를 위해 요청 간 시간 간격을 두는 것을 권장 합니다.