@awesome-message/sdk
Version:
Awesome Message SDK for admin, messaging, and notification services
1,946 lines (1,932 loc) • 134 kB
TypeScript
import { FormData } from 'undici';
/**
* 클라이언트 생성 요청 데이터
*
* 새로운 클라이언트를 생성할 때 사용되는 요청 데이터입니다.
*
* @group Admin Interfaces
*
* @example
* ```typescript
* const request: CreateClientRequest = {
* externalId: "my-service-v1",
* name: "My Service Client"
* };
* ```
*/
interface CreateClientRequest {
/** 연동 ID (최대 40자) */
externalId: string;
/** 클라이언트 이름 (최대 40자) */
name: string;
}
/**
* 클라이언트 삭제 요청 데이터
*
* 클라이언트를 삭제할 때 사용되는 요청 데이터입니다.
*
* @group Admin Interfaces
*
* @example
* ```typescript
* const request: DeleteClientRequest = {
* externalId: "my-service-v1"
* };
* ```
*/
interface DeleteClientRequest {
/** 삭제할 클라이언트의 연동 ID */
externalId: string;
}
/**
* 카카오 채널 등록 요청 데이터
*
* 새로운 카카오 채널을 등록할 때 사용되는 요청 데이터입니다.
*
* @group Kakao Interfaces
*/
interface CreateKakaoChannelRequest {
/** 플러스친구 ID (최대 30자) */
plusFriendId: string;
/** 연락처 번호 (최대 15자) */
phoneNo: string;
/** 카테고리 코드 (11자) */
categoryCode: string;
}
/**
* 카카오 채널 토큰 인증 요청 데이터
*
* 카카오톡 앱에서 받은 인증 토큰을 사용하여 채널을 인증할 때 사용되는 요청 데이터입니다.
*
* @group Kakao Interfaces
*/
interface AuthenticateKakaoChannelTokenRequest {
/** 플러스친구 ID */
plusFriendId: string;
/** 인증 토큰 (카카오톡 앱에서 받은 인증 토큰) */
token: number;
}
/**
* 카카오 채널 리스트 조회 요청 파라미터
*
* 카카오 채널 목록을 조회할 때 사용되는 필터 조건들입니다.
*
* @group Kakao Interfaces
*/
interface ListKakaoChannelsRequest {
/** 플러스친구 ID (선택적 필터) */
plusFriendId?: string;
/** 발신 키 (선택적 필터) */
senderKey?: string;
/** 플러스친구 상태 코드 (YSC02: 등록 대기 중, YSC03: 정상 등록) */
status?: string;
/** 페이지 번호 (선택적 필터) */
pageNum?: number;
/** 페이지 크기 (선택적 필터) */
pageSize?: number;
}
/**
* 카카오 채널 삭제 요청 데이터
*
* 카카오 채널을 삭제할 때 사용되는 요청 데이터입니다.
*
* @group Kakao Interfaces
*/
interface DeleteKakaoChannelRequest {
/** 삭제할 카카오 채널의 발신 키 */
senderKey: string;
}
/**
* 메시지 요청 상태
*
* @description
* - COMPLETED: 성공
* - FAILED: 실패
*
*/
type FriendtalkMessageStatus = "COMPLETED" | "FAILED";
/**
* 발송 결과
*
* @description
* - MRC01: 성공
* - MRC02: 실패
*
*/
type FriendtalkResultCode = "MRC01" | "MRC02";
/**
* 친구톡 자유형 수신자 정보
*
* 자유형 친구톡 메시지를 발송할 수신자 정보입니다.
*
* @group Kakao Interfaces
*/
interface FriendtalkFreestyleRecipient {
/** 수신 번호 */
recipientNo: string;
}
/**
* 친구톡 템플릿형 메시지 수신자 타겟팅 타입
*
* @description
* - M: 마케팅 수신 동의 유저
* - N: 친구가 아닌 마케팅 수신 동의 유저에만
* - I: 채널 친구인 유저에만
*/
type FriendtalkTemplateTargetingType = "M" | "N" | "I";
type FriendtalkTemplateResendParameter = {
/** 발송 실패 시, 문자 대체 발송 여부
* 콘솔에서 대체 발송 설정 시, 기본으로 대체 발송됩니다.
*/
isResend?: boolean;
/**
* 대체 발송 타입(SMS,LMS)
* 값이 없을 경우, 템플릿 본문 길이에 따라 타입이 구분됩니다.
*/
resendType?: string;
/**
* LMS 대체 발송 제목
* 값이 없을 경우, 플러스친구 ID로 대체 발송됩니다.
*/
resendTitle?: string;
/**
* 대체 발송 내용
* (값이 없을 경우, [메시지 본문]으로 대체 발송됩니다.)
*/
resendContent?: string;
/**
* 대체 발송 발신 번호
* (SMS 서비스에 등록된 발신 번호가 아닐 경우, 대체 발송에 실패할 수 있습니다.)
*/
resendSendNo?: string;
};
/**
* 친구톡 템플릿형 메시지 수신자 정보
*
* 템플릿형 친구톡 메시지를 발송할 수신자 정보입니다.
*
* @group Kakao Interfaces
*/
interface FriendtalkTemplateRecipient {
/** 수신 번호 */
recipientNo: string;
/** 메시지 대상의 타입
* - M: 마케팅 수신 동의 유저
* - N: 친구가 아닌 마케팅 수신 동의 유저에만
* - I: 채널 친구인 유저에만
*/
targeting: FriendtalkTemplateTargetingType;
/** 템플릿 파라미터 (템플릿에 치환할 변수 포함 시, 필수) */
templateParameter?: Record<string, any>;
/** 대체 발송 정보 */
resendParameter?: FriendtalkTemplateResendParameter;
}
/**
* 친구톡 이미지 정보 (발송용과 템플릿용 공용)
* - IMAGE 타입: 일반 이미지로 업로드된 이미지 URL 사용
* - WIDE 타입: 와이드 이미지로 업로드된 이미지 URL 사용
* - COMMERCE 타입: 일반 이미지로 업로드된 이미지 URL 사용
*
* @group Kakao Interfaces
*/
interface FriendtalkImage {
/** 이미지 URL (타입별로 업로드 방식이 다름)
* - 템플릿에서 치환자 사용 불가능
*/
imageUrl: string;
/** 이미지 클릭시 이동할 URL, 1000자 제한 (미설정시 카카오톡 내 이미지 뷰어 사용)
* - 템플릿에서 치환자 사용 불가능
*/
imageLink?: string | null;
}
/**
* 친구톡 쿠폰 정보 (발송용과 템플릿용 공용)
*
* @group Kakao Interfaces
*/
interface FriendtalkCoupon {
/** 쿠폰 제목
* 5가지 형식으로 제한됨:
* - "${숫자}원 할인 쿠폰" 숫자는 1 이상 99,999,999 이하
* - "${숫자}% 할인 쿠폰" 숫자는 1 이상 100 이하
* - "배송비 할인 쿠폰"
* - "${7자 이내} 무료 쿠폰"
* - "${7자 이내} UP 쿠폰"
*/
title: string;
/** 쿠폰 상세 설명
* - WIDE, WIDE_ITEM_LIST, PREMIUM_VIDEO 타입일 경우 최대 18자, 줄바꿈: 불가
* - 이외의 타입일 경우 최대 12자, 줄바꿈: 불가
*/
description: string;
/** 모바일 웹 링크, 1,000자 제한 */
linkMo?: string | null;
/** PC 웹 링크, 1,000자 제한 */
linkPc?: string | null;
/** 안드로이드 앱 링크, 1,000자 제한 */
schemeAndroid?: string | null;
/** IOS 앱 링크, 1,000자 제한 */
schemeIos?: string | null;
}
/**
* 친구톡 와이드 아이템 리스트 아이템
*
* @group Kakao Interfaces
*/
interface FriendtalkWideItem {
/** 아이템 제목
* - 1번째 아이템은 최대 25자 제한 (줄바꿈: 최대 1개, 1번째 아이템의 경우 title이 필수 값이 아님)
* - 2~4번째 아이템 최대 30자 제한 (줄바꿈: 최대 1개)
*/
title?: string | null;
/** 아이템 이미지 URL
* - 1번째 아이템에는 첫번째 와이드 아이템리스트 이미지로 업로드된 이미지 URL 사용
* - 2~4번째 아이템은 일반 와이드 아이템리스트 이미지로 업로드된 이미지 URL 사용
* - 템플릿에서 치환자 사용 불가능
*/
imageUrl: string;
/** 모바일 웹 링크, 1,000자 제한 */
linkMo: string;
/** PC 웹 링크, 1,000자 제한 */
linkPc?: string | null;
/** 안드로이드 앱 링크, 1,000자 제한 */
schemeAndroid?: string | null;
/** IOS 앱 링크, 1,000자 제한 */
schemeIos?: string | null;
}
/**
* 친구톡 와이드 아이템 리스트
*
* @group Kakao Interfaces
*/
interface FriendtalkWideItemList {
/** 와이드 리스트 (최소: 3, 최대 4) */
list: FriendtalkWideItem[];
}
/**
* 친구톡 커머스 정보 (발송용과 템플릿용 공용)
*
* @group Kakao Interfaces
*/
interface FriendtalkCommerce {
/** 상품 제목 (최대 30자, 줄바꿈: 불가) */
title: string;
/** 정상 가격 (0 ~ 99,999,999)
* - 템플릿에서 치환자 사용자 지정 불가능, 값을 비워두면 고정 치환자 #{정상가격}으로 저장됨
*/
regularPrice: number;
/** 할인가격 (0 ~ 99,999,999)
* - 템플릿에서 치환자 사용자 지정 불가능, 값을 비워두면 고정 치환자 #{할인가격}으로 저장됨
*/
discountPrice?: number | null;
/** 할인율 (0 ~ 100), 할인가격 존재시 할인율, 정액할인가격 중 하나는 필수
* - 템플릿에서 치환자 사용자 지정 불가능, 값을 비워두면 고정 치환자 #{할인율}으로 저장됨
*/
discountRate?: number | null;
/** 정액할인가격 (0 ~ 999,999), 할인가격 존재시 할인율, 정액할인가격 중 하나는 필수
* - 템플릿에서 치환자 사용자 지정 불가능, 값을 비워두면 고정 치환자 #{정액할인가격}으로 저장됨
*/
discountFixed?: number | null;
}
/**
* 친구톡 동영상 정보 (발송용과 템플릿용 공용)
*
* @group Kakao Interfaces
*/
interface FriendtalkVideo {
/** 카카오TV 동영상 URL (카카오TV에 업로드된 동영상 주소만 사용 가능), 최대 500자 제한
* - 템플릿에서 치환자 사용 불가능
*/
videoUrl: string;
/** 동영상 썸네일용 이미지 URL, 일반 이미지로 업로드된 url만 사용 가능 (없는 경우 카카오TV 동영상 기본 썸네일 사용), 최대 500자 제한
* - 템플릿에서 치환자 사용 불가능
*/
thumbnailUrl?: string | null;
}
/**
* 친구톡 더보기 버튼 정보 (발송용과 템플릿용 공용)
*
* @group Kakao Interfaces
*/
interface FriendtalkTail {
/** 모바일 웹 링크, 1,000자 제한
* - 템플릿에서 치환자 사용 불가능
*/
linkMo: string;
/** PC 웹 링크, 1,000자 제한
* - 템플릿에서 치환자 사용 불가능
*/
linkPc?: string | null;
/** 안드로이드 앱 링크, 1,000자 제한
* - 템플릿에서 치환자 사용 불가능
*/
schemeAndroid?: string | null;
/** IOS 앱 링크, 1,000자 제한
* - 템플릿에서 치환자 사용 불가능
*/
schemeIos?: string | null;
}
/**
* 친구톡 캐러셀 인트로 (head)
*
* @group Kakao Interfaces
*/
interface FriendtalkCarouselHead {
/** 캐러셀 인트로 헤더 (최대 20자) */
header: string;
/** 캐러셀 인트로 내용 (최대 50자) */
content: string;
/** 캐러셀 인트로 이미지 주소 (캐러셀 커머스형 이미지로 업로드된 이미지 사용, 사용되는 이미지는 캐러셀의 이미지와 비율이 동일해야 함)
* - 템플릿에서 치환자 사용 불가능
*/
imageUrl: string | null;
/** 모바일 웹 링크 (linkMo, linkPc, schemeAndroid, schemeIos 중 하나라도 사용하려는 경우 linkMo은 필수값), 1,000자 제한 */
linkMo?: string | null;
/** PC 웹 링크, 1,000자 제한 */
linkPc?: string | null;
/** 안드로이드 앱 링크, 1,000자 제한 */
schemeAndroid?: string | null;
/** IOS 앱 링크, 1,000자 제한 */
schemeIos?: string | null;
}
/**
* 친구톡 자유형 캐러셀 피드 아이템
*
* @group Kakao Interfaces
*/
interface FriendtalkFreestyleCarouselFeedItem {
/** 캐러셀 아이템 제목 (최대 20자), 캐러셀 피드형에서만 사용 가능 */
header: string;
/** 캐러셀 아이템 메시지 (최대 180자), 캐러셀 피드형에서만 사용 가능 */
message: string;
/** 이미지 URL (캐러셀 피드형 이미지로 업로드된 이미지만 사용 가능) */
imageUrl: string;
/** 이미지 링크, 1000자 제한 */
imageLink: string;
/** 캐러셀 리스트 버튼 목록 최소 1개, 최대 2개 */
buttons: FriendtalkFreestyleButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
}
/**
* 친구톡 자유형 캐러셀 피드 리스트
*
* @group Kakao Interfaces
*/
interface FriendtalkFreestyleCarouselFeedList {
/** 캐러셀 리스트 (최소 2개, 최대 6개) */
list: FriendtalkFreestyleCarouselFeedItem[];
/** 더보기 버튼 정보 */
tail?: FriendtalkTail;
}
/**
* 친구톡 자유형 캐러셀 커머스 아이템
*/
interface FriendtalkFreestyleCarouselCommerceItem {
/** 부가 정보 (최대 34자), 캐러셀 커머스형에서만 사용 가능 */
additionalContent: string;
/** 이미지 URL (캐러셀 커머스형 이미지로 업로드된 이미지 사용) */
imageUrl: string;
/** 이미지 링크, 1000자 제한 */
imageLink: string;
/** 커머스 (CAROUSEL_COMMERCE 타입에서만 사용 가능) */
commerce: FriendtalkCommerce;
/** 캐러셀 리스트 버튼 목록 최소 1개, 최대 2개 */
buttons: FriendtalkFreestyleButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
}
/**
* 친구톡 템플릿용 캐러셀 피드 아이템
*
* @group Kakao Interfaces
*/
interface FriendtalkTemplateCarouselFeedItem {
/** 캐러셀 아이템 제목 (최대 20자), 캐러셀 피드형에서만 사용 가능 */
header: string;
/** 캐러셀 아이템 메시지 (최대 180자), 캐러셀 피드형에서만 사용 가능 */
message: string;
/** 이미지 URL (캐러셀 피드형 이미지로 업로드된 이미지만 사용 가능), 치환자 사용 불가능 */
imageUrl: string;
/** 이미지 링크, 1000자 제한, 치환자 사용 불가능 */
imageLink: string;
/** 캐러셀 리스트 버튼 목록 최소 1개, 최대 2개 */
buttons: FriendtalkTemplateButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
}
/**
* 친구톡 템플릿용 캐러셀 피드
*
* @group Kakao Interfaces
*/
interface FriendtalkTemplateCarouselFeedList {
/** 캐러셀 리스트 (최소 2개, 최대 6개) */
list: FriendtalkTemplateCarouselFeedItem[];
/** 더보기 버튼 정보 */
tail?: FriendtalkTail | null;
}
/**
* 친구톡 자유형 캐러셀 커머스 정보
*
* @group Kakao Interfaces
*/
interface FriendtalkFreestyleCarouselCommerce {
/** 캐러셀 인트로 */
head?: FriendtalkCarouselHead | null;
/** 캐러셀 리스트 (head가 존재할 경우 최소 1개, 최대 5개 / 그 외에는 최소 2개, 최대 6개) */
list: FriendtalkFreestyleCarouselCommerceItem[];
/** 더보기 버튼 정보 */
tail?: FriendtalkTail | null;
}
/**
* 친구톡 템플릿용 캐러셀 커머스 아이템
*
* @group Kakao Interfaces
*/
interface FriendtalkTemplateCarouselCommerceItem {
/** 부가 정보 (최대 34자), 캐러셀 커머스형에서만 사용 가능 */
additionalContent: string;
/** 이미지 URL (캐러셀 커머스형 이미지로 업로드된 이미지 사용), 치환자 사용 불가능 */
imageUrl: string;
/** 이미지 링크, 1000자 제한, 치환자 사용 불가능 */
imageLink: string;
/** 커머스 (CAROUSEL_COMMERCE 타입에서만 사용 가능) */
commerce: FriendtalkCommerce;
/** 캐러셀 리스트 버튼 목록 최소 1개, 최대 2개 */
buttons: FriendtalkTemplateButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
}
/**
* 친구톡 템플릿용 캐러셀 커머스
*
* @group Kakao Interfaces
*/
interface FriendtalkTemplateCarouselCommerce {
/** 캐러셀 인트로 */
head?: FriendtalkCarouselHead;
/** 캐러셀 리스트 (head가 존재할 경우 최소 1개, 최대 5개 / 그 외에는 최소 2개, 최대 6개) */
list: FriendtalkTemplateCarouselCommerceItem[];
/** 더보기 버튼 정보 */
tail?: FriendtalkTail;
}
/**
* 친구톡 템플릿 버튼 타입 (템플릿용)
* @description WL: 웹 링크, AL: 앱 링크, BK: 봇 키워드, MD: 메시지 전달, AC: 채널 추가, BT: 챗봇 전환, BF: 비즈니스 폼
*/
type FriendtalkTemplateButtonType = "WL" | "AL" | "BK" | "MD" | "AC" | "BT";
/**
* 친구톡 템플릿 버튼 정보
*
* @group Kakao Interfaces
*/
interface FriendtalkTemplateButton {
/** 버튼 제목 (TEXT, IMAGE 타입일 경우 최대 14자, 이외의 타입일 경우 최대 8자)
* - 템플릿에서 치환자 사용 불가능
*/
name: string;
/** 버튼 타입 (WL: 웹 링크, AL: 앱 링크, BK: 봇 키워드, MD: 메시지 전달, AC: 채널 추가, BC: 상담톡 전환, BT: 챗봇 전환, BF: 비즈니스 폼 )
* - 템플릿에서는 BC 타입 이용 불가
* - BT 타입
* - 템플릿에서는 BF 타입 이용 불가
* - AC 타입은 TEXT, IMAGE의 경우 첫번째 버튼으로, 그 외 메시지 타입의 경우 마지막 버튼으로 등록해야함
*/
type: FriendtalkTemplateButtonType;
/** 모바일 웹 링크 (WL 타입일 경우 필수 필드), 1,000자 제한 */
linkMo?: string | null;
/** PC 웹 링크 (WL 타입일 경우 선택 필드), 1,000자 제한 */
linkPc?: string | null;
/** 안드로이드 앱 링크 (AL 타입일 경우 필수 필드), 1,000자 제한 */
schemeAndroid?: string | null;
/** IOS 앱 링크 (AL 타입일 경우 필수 필드), 1,000자 제한 */
schemeIos?: string | null;
/** BF 타입 버튼일 경우 비즈폼 키 */
bizFormKey?: string | null;
}
/**
* 친구톡 발송 버튼 타입
* @description WL: 웹 링크, AL: 앱 링크, BK: 봇 키워드, MD: 메시지 전달, BC: 상담톡 전환, BT: 챗봇 전환, BF: 비즈니스 폼
*/
type FriendtalkFreestyleButtonType = "WL" | "AL" | "BK" | "MD" | "BC" | "BT" | "BF";
/**
* 친구톡 발송 버튼 정보
*
* @group Kakao Interfaces
*/
interface FriendtalkFreestyleButton extends Omit<FriendtalkTemplateButton, "type"> {
/** BC / BT 타입 버튼일 경우 전달할 메타 정보 */
chatExtra?: string | null;
/** BT 타입 버튼일 경우 연결할 봇 이벤트명 */
chatEvent?: string | null;
/** 발송 버튼 타입 */
type: FriendtalkFreestyleButtonType;
}
/**
* 친구톡 발송목록조회 쿼리 파라미터
* 1번 조건(requestId) 또는 2번 조건(startRequestDate + endRequestDate) 중 하나 필수
*
* @group Kakao Interfaces
*/
interface ListFriendtalkMessagesRequest {
/** 요청 ID */
requestId?: string;
/** 발송 요청 날짜 시작 값 */
startRequestDate?: Date;
/** 발송 요청 날짜 끝 값 */
endRequestDate?: Date;
/** 발신 키 */
senderKey?: string;
/** 템플릿 코드 */
templateCode?: string;
/** 수신 번호 */
recipientNo?: string;
/** 요청 상태 (COMPLETED: 성공, FAILED: 실패) */
messageStatus?: FriendtalkMessageStatus;
/** 발송 결과 (MRC01: 성공 MRC02: 실패) */
resultCode?: FriendtalkResultCode;
/** 페이지 번호 (Default: 1) */
pageNum?: number;
/** 조회 건수 (Default: 15, Max: 1000) */
pageSize?: number;
}
/**
* 친구톡 자유형 텍스트 메시지 발송 요청
*
* @group Kakao Interfaces
*/
interface SendFriendtalkFreestyleTextMessageRequest {
/** 발신 키(40자), 그룹 발신키 사용 불가 */
senderKey: string;
/** 메시지 푸시 알람 발송 여부 (기본값: true) */
pushAlarm?: boolean;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 메시지 내용 (TEXT 타입일 경우 최대 1,000자, 줄바꿈: 최대 33개, URL 형식 입력 가능) */
content: string;
/** 버튼 목록 (TEXT, IMAGE 타입일 경우 쿠폰 적용시 최대 4개, 그 외 최대 5개) */
buttons?: FriendtalkFreestyleButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
/** 수신자 목록(최대 1,000명) */
recipientList: FriendtalkFreestyleRecipient[];
/** 등록자(콘솔에서 발송 시 사용자 UUID로 저장) */
createUser?: string;
/** 통계 ID(발신 검색 조건에는 포함되지 않습니다, 최대 8자) */
statsId?: string;
}
/**
* 친구톡 자유형 이미지 메시지 발송 요청
*
* @group Kakao Interfaces
*/
interface SendFriendtalkFreestyleImageMessageRequest {
/** 발신 키(40자), 그룹 발신키 사용 불가 */
senderKey: string;
/** 메시지 푸시 알람 발송 여부 (기본값: true) */
pushAlarm?: boolean;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 메시지 내용 (IMAGE 타입일 경우 최대 400자, 줄바꿈: 최대 29개, URL 형식 입력 가능) */
content: string;
/** 이미지 요소 (IMAGE, WIDE, COMMERCE 타입일 경우 필수 필드) */
image: FriendtalkImage;
/** 버튼 목록 (TEXT, IMAGE 타입일 경우 쿠폰 적용시 최대 4개, 그 외 최대 5개) */
buttons?: FriendtalkFreestyleButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
/** 수신자 목록(최대 1,000명) */
recipientList: FriendtalkFreestyleRecipient[];
/** 등록자(콘솔에서 발송 시 사용자 UUID로 저장) */
createUser?: string;
/** 통계 ID(발신 검색 조건에는 포함되지 않습니다, 최대 8자) */
statsId?: string;
}
/**
* 친구톡 자유형 와이드 이미지 메시지 발송 요청
*
* @group Kakao Interfaces
*/
interface SendFriendtalkFreestyleWideImageMessageRequest {
/** 발신 키(40자), 그룹 발신키 사용 불가 */
senderKey: string;
/** 메시지 푸시 알람 발송 여부 (기본값: true) */
pushAlarm?: boolean;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 메시지 내용 (WIDE 타입일 경우 최대 76자, 줄바꿈: 최대 1개) */
content: string;
/** 이미지 요소 (IMAGE, WIDE, COMMERCE 타입일 경우 필수 필드) */
image: FriendtalkImage;
/** 버튼 목록 (WIDE, WIDE_ITEM_LIST 타입일 경우 최대 2개) */
buttons?: FriendtalkFreestyleButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
/** 수신자 목록(최대 1,000명) */
recipientList: FriendtalkFreestyleRecipient[];
/** 등록자(콘솔에서 발송 시 사용자 UUID로 저장) */
createUser?: string;
/** 통계 ID(발신 검색 조건에는 포함되지 않습니다, 최대 8자) */
statsId?: string;
}
/**
* 친구톡 자유형 와이드 아이템 리스트 메시지 발송 요청
*
* @group Kakao Interfaces
*/
interface SendFriendtalkFreestyleWideItemListMessageRequest {
/** 발신 키(40자), 그룹 발신키 사용 불가 */
senderKey: string;
/** 메시지 푸시 알람 발송 여부 (기본값: true) */
pushAlarm?: boolean;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 헤더 (WIDE_ITEM_LIST 타입일 경우 필수 필드이고 최대 20자, 줄바꿈: 불가) */
header: string;
/** 와이드 리스트 요소 (WIDE_ITEM_LIST 타입에서만 사용 가능) */
item: FriendtalkWideItemList;
/** 버튼 목록 (WIDE, WIDE_ITEM_LIST 타입일 경우 최대 2개) */
buttons?: FriendtalkFreestyleButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
/** 수신자 목록(최대 1,000명) */
recipientList: FriendtalkFreestyleRecipient[];
/** 등록자(콘솔에서 발송 시 사용자 UUID로 저장) */
createUser?: string;
/** 통계 ID(발신 검색 조건에는 포함되지 않습니다, 최대 8자) */
statsId?: string;
}
/**
* 친구톡 자유형 프리미엄 동영상 메시지 발송 요청
*
* @group Kakao Interfaces
*/
interface SendFriendtalkFreestylePremiumVideoMessageRequest {
/** 발신 키(40자), 그룹 발신키 사용 불가 */
senderKey: string;
/** 메시지 푸시 알람 발송 여부 (기본값: true) */
pushAlarm?: boolean;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 메시지 내용 (PREMIUM_VIDEO 타입일 경우 해당 필드를 옵셔널하게 사용할 수 있음, 최대 76자, 줄바꿈: 최대 1개) */
content?: string;
/** 헤더 (PREMIUM_VIDEO 타입일 경우 선택 필드이고 최대 20자, 줄바꿈: 불가) */
header?: string;
/** 동영상 요소 (PREMIUM_VIDEO 타입만 사용 가능) */
video: FriendtalkVideo;
/** 버튼 목록 (PREMIUM_VIDEO 타입일 경우 최대 1개) */
buttons?: FriendtalkFreestyleButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
/** 수신자 목록(최대 1,000명) */
recipientList: FriendtalkFreestyleRecipient[];
/** 등록자(콘솔에서 발송 시 사용자 UUID로 저장) */
createUser?: string;
/** 통계 ID(발신 검색 조건에는 포함되지 않습니다, 최대 8자) */
statsId?: string;
}
/**
* 친구톡 자유형 커머스 메시지 발송 요청
*
* @group Kakao Interfaces
*/
interface SendFriendtalkFreestyleCommerceMessageRequest {
/** 발신 키(40자), 그룹 발신키 사용 불가 */
senderKey: string;
/** 메시지 푸시 알람 발송 여부 (기본값: true) */
pushAlarm?: boolean;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 부가 정보 (최대 34자, 줄바꿈: 최대 1개), 커머스형에서만 사용 가능 */
additionalContent?: string;
/** 이미지 요소 (IMAGE, WIDE, COMMERCE 타입일 경우 필수 필드) */
image: FriendtalkImage;
/** 커머스 (COMMERCE 타입에서만 사용 가능) */
commerce: FriendtalkCommerce;
/** 버튼 목록 (COMMERCE 타입일 경우 최소 1개 최대 2개) */
buttons: FriendtalkFreestyleButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
/** 수신자 목록(최대 1,000명) */
recipientList: FriendtalkFreestyleRecipient[];
/** 등록자(콘솔에서 발송 시 사용자 UUID로 저장) */
createUser?: string;
/** 통계 ID(발신 검색 조건에는 포함되지 않습니다, 최대 8자) */
statsId?: string;
}
/**
* 친구톡 자유형 캐러셀 피드 메시지 발송 요청
*
* @group Kakao Interfaces
*/
interface SendFriendtalkFreestyleCarouselFeedMessageRequest {
/** 발신 키(40자), 그룹 발신키 사용 불가 */
senderKey: string;
/** 메시지 푸시 알람 발송 여부 (기본값: true) */
pushAlarm?: boolean;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 캐러셀 */
carousel: FriendtalkFreestyleCarouselFeedList;
/** 수신자 목록(최대 1,000명) */
recipientList: FriendtalkFreestyleRecipient[];
/** 등록자(콘솔에서 발송 시 사용자 UUID로 저장) */
createUser?: string;
/** 통계 ID(발신 검색 조건에는 포함되지 않습니다, 최대 8자) */
statsId?: string;
}
/**
* 친구톡 자유형 캐러셀 커머스 메시지 발송 요청
*
* @group Kakao Interfaces
*/
interface SendFriendtalkFreestyleCarouselCommerceMessageRequest {
/** 발신 키(40자), 그룹 발신키 사용 불가 */
senderKey: string;
/** 메시지 푸시 알람 발송 여부 (기본값: true) */
pushAlarm?: boolean;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 캐러셀 */
carousel: FriendtalkFreestyleCarouselCommerce;
/** 수신자 목록(최대 1,000명) */
recipientList: FriendtalkFreestyleRecipient[];
/** 등록자(콘솔에서 발송 시 사용자 UUID로 저장) */
createUser?: string;
/** 통계 ID(발신 검색 조건에는 포함되지 않습니다, 최대 8자) */
statsId?: string;
}
/**
* 친구톡 템플릿 메시지 발송 요청
*
* @group Kakao Interfaces
*/
interface SendFriendtalkTemplateMessageRequest {
/** 발신 키(40자), 그룹 발신키 사용 불가 */
senderKey: string;
/** 사용하려는 템플릿 코드 */
templateCode: string;
/** 메시지 푸시 알람 발송 여부 (기본값: true) */
pushAlarm?: boolean;
/** 080 무료수신거부 전화번호 (둘다 미입력시 발신프로필에 등록된 무료수신거부 정보로 발송됨) */
unsubscribeNo?: string;
/** 080 무료수신거부 인증번호 (둘다 미입력시 발신프로필에 등록된 무료수신거부 정보로 발송됨)
* unsubscribe_phone_number 없이 unsubscribe_auth_number만 입력 불가
* ex) 1234
*/
unsubscribeAuthNo?: string;
/** 수신자 목록(최대 1,000명) */
recipientList: FriendtalkTemplateRecipient[];
/** 등록자(콘솔에서 발송 시 사용자 UUID로 저장) */
createUser?: string;
/** 통계 ID(발신 검색 조건에는 포함되지 않습니다, 최대 8자) */
statsId?: string;
}
/**
* 친구톡 템플릿 리스트 조회 요청
*
* @group Kakao Interfaces
*/
interface ListFriendtalkTemplatesRequest {
/** 템플릿 코드 */
templateCode?: string;
/** 템플릿 이름 */
templateName?: string;
/** 템플릿 상태 코드 */
status?: string;
/** 페이지 번호(Default: 1) */
pageNum?: number;
/** 조회 건수(Default: 15, Max: 1000) */
pageSize?: number;
}
/**
* 친구톡 텍스트형 템플릿 등록 요청
*
* @group Kakao Interfaces
*/
interface CreateFriendtalkTextTemplateRequest {
/** 템플릿 명 (최대 200자) */
templateName: string;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 메시지 내용 (TEXT 타입일 경우 최대 1,000자, 줄바꿈: 최대 33개, URL 형식 입력 가능) */
content: string;
/** 버튼 목록 (TEXT 타입일 경우 쿠폰 적용시 최대 4개, 그 외 최대 5개) */
buttons?: FriendtalkTemplateButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
}
/**
* 친구톡 텍스트형 템플릿 수정 요청
*
* @group Kakao Interfaces
*/
interface UpdateFriendtalkTextTemplateRequest extends CreateFriendtalkTextTemplateRequest {
}
/**
* 친구톡 이미지형 템플릿 등록 요청
*
* @group Kakao Interfaces
*/
interface CreateFriendtalkImageTemplateRequest {
/** 템플릿 명 (최대 200자) */
templateName: string;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 메시지 내용 (IMAGE 타입일 경우 최대 400자, 줄바꿈: 최대 29개, URL 형식 입력 가능) */
content: string;
/** 이미지 요소 (IMAGE 타입일 경우 필수 필드) */
image: FriendtalkImage;
/** 버튼 목록 (TEXT, IMAGE 타입일 경우 쿠폰 적용시 최대 4개, 그 외 최대 5개) */
buttons?: FriendtalkTemplateButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
}
/**
* 친구톡 이미지형 템플릿 수정 요청
*
* @group Kakao Interfaces
*/
interface UpdateFriendtalkImageTemplateRequest extends CreateFriendtalkImageTemplateRequest {
}
/**
* 친구톡 와이드 이미지형 템플릿 등록 요청
*
* @group Kakao Interfaces
*/
interface CreateFriendtalkWideImageTemplateRequest {
/** 템플릿 명 (최대 200자) */
templateName: string;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 메시지 내용 (WIDE 타입일 경우 최대 76자, 줄바꿈: 최대 1개) */
content: string;
/** 이미지 요소 (WIDE 타입일 경우 필수 필드, 와이드 이미지로 업로드된 이미지 URL 사용) */
image: FriendtalkImage;
/** 버튼 목록 (WIDE 타입일 경우 최대 2개) */
buttons?: FriendtalkTemplateButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
}
/**
* 친구톡 와이드 이미지형 템플릿 수정 요청
*
* @group Kakao Interfaces
*/
interface UpdateFriendtalkWideImageTemplateRequest extends CreateFriendtalkWideImageTemplateRequest {
}
/**
* 친구톡 와이드 아이템 리스트형 템플릿 등록 요청
*
* @group Kakao Interfaces
*/
interface CreateFriendtalkWideItemListTemplateRequest {
/** 템플릿 명 (최대 200자) */
templateName: string;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 헤더 (WIDE_ITEM_LIST 타입일 경우 필수 필드이고 최대 20자, 줄바꿈: 불가) */
header: string;
/** 와이드 리스트 요소 (WIDE_ITEM_LIST 타입에서만 사용 가능) */
item: FriendtalkWideItemList;
/** 버튼 목록 (WIDE_ITEM_LIST 타입일 경우 최대 2개, name 최대 8자) */
buttons?: FriendtalkTemplateButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
}
/**
* 친구톡 와이드 아이템 리스트형 템플릿 수정 요청
*
* @group Kakao Interfaces
*/
interface UpdateFriendtalkWideItemListTemplateRequest extends CreateFriendtalkWideItemListTemplateRequest {
}
/**
* 친구톡 프리미엄 동영상형 템플릿 등록 요청
*
* @group Kakao Interfaces
*/
interface CreateFriendtalkPremiumVideoTemplateRequest {
/** 템플릿 명 (최대 200자) */
templateName: string;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 메시지 내용 (PREMIUM_VIDEO 타입일 경우 해당 필드를 옵셔널하게 사용할 수 있음, 최대 76자, 줄바꿈: 최대 1개) */
content?: string;
/** 헤더 (PREMIUM_VIDEO 타입일 경우 선택 필드이고 최대 20자, 줄바꿈: 불가) */
header?: string;
/** 동영상 요소 (PREMIUM_VIDEO 타입만 사용 가능) */
video: FriendtalkVideo;
/** 버튼 목록 (PREMIUM_VIDEO 타입일 경우 최대 1개, name 최대 8자) */
buttons?: FriendtalkTemplateButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
}
/**
* 친구톡 프리미엄 동영상형 템플릿 수정 요청
*
* @group Kakao Interfaces
*/
interface UpdateFriendtalkPremiumVideoTemplateRequest extends CreateFriendtalkPremiumVideoTemplateRequest {
}
/**
* 친구톡 커머스형 템플릿 등록 요청
*
* @group Kakao Interfaces
*/
interface CreateFriendtalkCommerceTemplateRequest {
/** 템플릿 명 (최대 200자) */
templateName: string;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 부가 정보 (최대 34자, 줄바꿈: 최대 1개), 커머스형에서만 사용 가능 */
additionalContent?: string;
/** 이미지 요소 (COMMERCE 타입일 경우 필수 필드, 일반 이미지로 업로드된 이미지 URL 사용) */
image: FriendtalkImage;
/** 커머스 (COMMERCE 타입에서만 사용 가능) */
commerce: FriendtalkCommerce;
/** 버튼 목록 (COMMERCE 타입일 경우 최소 1개 최대 2개, name 최대 8자) */
buttons: FriendtalkTemplateButton[];
/** 쿠폰 요소 */
coupon?: FriendtalkCoupon;
}
/**
* 친구톡 커머스형 템플릿 수정 요청
*
* @group Kakao Interfaces
*/
interface UpdateFriendtalkCommerceTemplateRequest extends CreateFriendtalkCommerceTemplateRequest {
}
/**
* 친구톡 캐러셀 피드형 템플릿 등록 요청
*
* @group Kakao Interfaces
*/
interface CreateFriendtalkCarouselFeedTemplateRequest {
/** 템플릿 명 (최대 200자) */
templateName: string;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 캐러셀 */
carousel: FriendtalkTemplateCarouselFeedList;
}
/**
* 친구톡 캐러셀 피드형 템플릿 수정 요청
*
* @group Kakao Interfaces
*/
interface UpdateFriendtalkCarouselFeedTemplateRequest extends CreateFriendtalkCarouselFeedTemplateRequest {
}
/**
* 친구톡 캐러셀 커머스형 템플릿 등록 요청
*
* @group Kakao Interfaces
*/
interface CreateFriendtalkCarouselCommerceTemplateRequest {
/** 템플릿 명 (최대 200자) */
templateName: string;
/** 연령 확인 필요 여부 (기본값: false) */
adult?: boolean;
/** 캐러셀 */
carousel: FriendtalkTemplateCarouselCommerce;
}
/**
* 친구톡 캐러셀 커머스형 템플릿 수정 요청
*
* @group Kakao Interfaces
*/
interface UpdateFriendtalkCarouselCommerceTemplateRequest extends CreateFriendtalkCarouselCommerceTemplateRequest {
}
/**
* 친구톡 이미지 타입
* @description IMAGE : 일반 이미지, WIDE_IMAGE : 와이드 이미지, MAIN_WIDE_ITEMLIST_IMAGE : 메인 와이드 아이템 리스트 이미지, NORMAL_WIDE_ITEMLIST_IMAGE : 일반 와이드 아이템 리스트 이미지, CAROUSEL_FEED_IMAGE : 캐러셀 피드 이미지, CAROUSEL_COMMERCE_IMAGE : 캐러셀 커머스 이미지
*/
type FriendtalkImageType = "IMAGE" | "WIDE_IMAGE" | "MAIN_WIDE_ITEMLIST_IMAGE" | "NORMAL_WIDE_ITEMLIST_IMAGE" | "CAROUSEL_FEED_IMAGE" | "CAROUSEL_COMMERCE_IMAGE";
/**
* 친구톡 이미지 업로드 요청
*
* @group Kakao Interfaces
*/
interface UploadFriendtalkImageRequest {
/** 이미지 파일 */
imageFile: Buffer;
/** 친구톡 업로드 이미지 타입 */
friendtalkImageType: FriendtalkImageType;
/** 파일명 */
filename?: string;
}
/**
* 친구톡 이미지 조회 요청
*
* @group Kakao Interfaces
*/
interface ListFriendtalkUploadedImagesRequest {
/** 이미지 타입 목록 */
imageTypes: FriendtalkImageType[];
/** 페이지 번호 (기본값: 1) */
pageNum?: string;
/** 조회 건수 (기본값: 15) */
pageSize?: string;
}
/**
* 클라이언트 생성 응답 데이터
*
* 클라이언트 생성 API 호출 시 반환되는 응답 데이터입니다.
*
* @group Admin Interfaces
*/
interface CreateClientResponse {
/** 생성된 클라이언트의 연동 ID */
externalId: string;
/** 생성된 클라이언트의 이름 */
name: string;
}
/**
* 클라이언트 삭제 응답 데이터
*
* 클라이언트 삭제 API 호출 시 반환되는 응답 데이터입니다.
*
* @group Admin Interfaces
*/
interface DeleteClientResponse {
/** 삭제된 클라이언트의 연동 ID */
externalId: string;
}
/**
* 클라이언트 정보
*
* 클라이언트 정보를 나타내는 데이터입니다.
*
* @group Admin Interfaces
*/
interface Client {
/** 클라이언트 이름 */
name: string;
/** 클라이언트 연동 ID */
externalId: string;
/** 클라이언트 생성 일시 */
createdAt: Date;
}
/**
* 카카오 채널 카테고리 정보
*
* 카카오 채널 등록 시 선택할 수 있는 카테고리의 계층 구조를 나타냅니다.
*
* @group Kakao Interfaces
*/
interface KakaoChannelCategory {
/** 상위 카테고리 코드 */
parentCode: string;
/** 카테고리 깊이 */
depth: number;
/** 카테고리 코드 */
code: string;
/** 카테고리 이름 */
name: string;
/** 하위 카테고리 목록 */
subCategories: {
/** 상위 카테고리 코드 */
parentCode: string;
/** 카테고리 깊이 */
depth: number;
/** 카테고리 코드 */
code: string;
/** 카테고리 이름 */
name: string;
/** 3차 하위 카테고리 목록 */
subCategories: {
/** 상위 카테고리 코드 */
parentCode: string;
/** 카테고리 깊이 */
depth: number;
/** 카테고리 코드 */
code: string;
/** 카테고리 이름 */
name: string;
}[];
}[];
}
/**
* 알림톡 설정 정보
*
* @group Kakao Interfaces
*/
interface KakaoChannelAlimtalkInfo {
/** 대체 발송으로 설정할 SMS 서비스 앱키 */
resendAppKey: string;
/** 대체 발송 설정(재발송) 여부 */
isResend: string;
/** 재발송 시, tc-sms 발신 번호 */
resendSendNo: string;
/** 알림톡 일별 최대 발송 건수 (값이 0일 경우 건수 제한 없음) */
dailyMaxCount: number;
/** 알림톡 일별 발송 건수 (값이 0일 경우 건수 제한 없음) */
sentCount: number;
}
/**
* 친구톡 설정 정보
*
* @group Kakao Interfaces
*/
interface KakaoChannelFriendtalkInfo {
/** 대체 발송으로 설정할 SMS 서비스 앱키 */
resendAppKey: string;
/** 대체 발송 설정(재발송) 여부 */
isResend: string;
/** 재발송 시, tc-sms 발신 번호 */
resendSendNo: string;
/** 재발송 시, tc-sms 080 수신 거부 번호 */
resendUnsubscribeNo: string;
/** 친구톡 일별 최대 발송 건수 (값이 0일 경우 건수 제한 없음) */
dailyMaxCount: number;
/** 친구톡 일별 발송 건수 (값이 0일 경우 건수 제한 없음) */
sentCount: number;
}
/**
* 카카오 채널 정보
*
* @group Kakao Interfaces
*/
interface KakaoChannelInfo {
/** 플러스친구 ID */
plusFriendId: string;
/** 발신 키 */
senderKey: string;
/** 카테고리 코드 */
categoryCode: string;
/** 무료수신거부 전화번호 */
unsubscribePhoneNumber: string | null;
/** 무료수신거부 인증번호 */
unsubscribeAuthNumber: string | null;
/** 플러스친구 상태 코드 (YSC02: 등록 대기 중, YSC03: 정상 등록) */
status: string;
/** 플러스친구 상태명 */
statusName: string;
/** 카카오 플러스친구 상태 코드 (A: 정상, S: 차단) - status가 YSC02일 경우, kakaoStatus null 값을 가집니다. */
kakaoStatus: string | null;
/** 카카오 플러스친구 상태명(정상, 차단) - status가 YSC02일 경우, kakaoStatusName null 값을 가집니다. */
kakaoStatusName: string | null;
/** 카카오 플러스친구 프로필 상태 코드 (A: 활성화, B:차단, C: 비활성화, D:삭제 E:삭제 처리 중) - status가 YSC02일 경우, kakaoProfileStatus null 값을 가집니다. */
kakaoProfileStatus: string | null;
/** 카카오 플러스친구 프로필 상태명(활성화, 비활성화, 차단, 삭제 처리 중, 삭제) - status가 YSC02일 경우, kakaoProfileStatusName null 값을 가집니다. */
kakaoProfileStatusName: string | null;
/** 카카오톡 채널 스팸 상태명(영구제한, 경고제한, 정상) - 발신 프로필 상태가 정상적이지 않을 경우 null 값을 가질 수 있습니다. */
profileSpamLevel: string | null;
/** 카카오톡 메시지 스팸 상태명(활동제한, 경고제한, 정상) - 발신 프로필 상태가 정상적이지 않을 경우 null 값을 가질 수 있습니다. */
profileMessageSpamLevel: string | null;
/** 알림톡 설정 정보 */
alimtalk: KakaoChannelAlimtalkInfo;
/** 친구톡 설정 정보 */
friendtalk: KakaoChannelFriendtalkInfo;
/** 발신프로필 휴면 여부 */
dormant: boolean;
/** 발신프로필 차단 여부 */
block: boolean;
/** 등록 일자 */
createDate: Date;
/** 최초 사용자 제한 여부 */
initialUserRestriction: boolean;
}
/**
* 카카오 채널 리스트 조회 응답
*
* @group Kakao Interfaces
*/
interface ListKakaoChannelsResponse {
/** 채널 목록 */
senders: KakaoChannelInfo[];
/** 전체 건수 */
totalCount: number;
}
/**
* 카카오 채널 등록 응답 데이터
*
* 카카오 채널 등록 성공 시 반환되는 응답 데이터입니다.
*
* @group Kakao Interfaces
*/
interface CreateKakaoChannelResponse {
/** 플러스친구 ID */
plusFriendId: string;
}
/**
* 카카오 채널 삭제 응답 데이터
*
* 카카오 채널 삭제 성공 시 반환되는 응답 데이터입니다.
*
* @group Kakao Interfaces
*/
interface DeleteKakaoChannelResponse {
/** 발신 키 */
senderKey: string;
}
/**
* 카카오 채널 토큰 인증 응답 데이터
*
* 카카오 채널 토큰 인증 성공 시 반환되는 응답 데이터입니다.
*
* @group Kakao Interfaces
*/
interface AuthenticateKakaoChannelTokenResponse {
/** 플러스친구 ID */
plusFriendId: string;
/** 발신 키 */
senderKey: string;
/** 카테고리 코드 */
categoryCode: string;
/** 플러스친구 상태 코드 (YSC02: 등록 대기 중, YSC03: 정상 등록) */
status: string;
}
/**
* 친구톡 발송 결과 (수신자별)
*
* @group Kakao Interfaces
*/
interface FriendtalkSendResult {
/** 수신자 목록의 순번 */
recipientSeq: number;
/** 수신자 전화번호 */
recipientNo: string | null;
/** 수신자별 발송 결과 코드 (성공 및 다양한 실패 코드가 존재할 수 있음) */
resultCode: number;
/** 수신자별 발송 결과 메시지 (성공 시 "success" 또는 관련 성공 메시지, 실패 시 실제 원인 상세 메시지) */
resultMessage: string;
}
/**
* 친구톡 발송 응답
*
* @group Kakao Interfaces
*/
interface SendFriendtalkMessageResponse {
/** 발송 요청 ID (각 발송 요청을 고유하게 식별하는 ID) */
requestId: string | null;
/** 수신자별 발송 결과 목록 */
sendResults: FriendtalkSendResult[];
}
/**
* 친구톡 발송목록조회 응답
*
* @group Kakao Interfaces
*/
interface ListFriendtalkMessagesResponse {
messages: FriendtalkMessage[];
totalCount: number;
}
/**
* 친구톡 발송 단건조회 응답
*
* @group Kakao Interfaces
*/
interface GetFriendtalkMessageResponse {
/** 메시지 상세 정보 (메시지 실패 시 없을 수 있음) */
message: FriendtalkMessageDetail | null;
}
/**
* 친구톡 메시지 기본 정보 (리스트 조회용)
*
* @group Kakao Interfaces
*/
interface FriendtalkMessage {
/** 요청 ID */
requestId: string;
/** 수신자 시퀀스 번호 */
recipientSeq: number;
/** 발신 프로필 ID */
plusFriendId: string;
/** 발신 키 */
senderKey: string;
/** 템플릿 코드 */
templateCode: string | null;
/** 수신 번호 */
recipientNo: string;
/** 메시지 대상의 타입 (M - 마케팅 수신 동의 유저, N - 친구가 아닌 마케팅 수신 동의에 해당, I - 친구인 유저) */
targeting: FriendtalkTemplateTargetingType;
/** 요청 일시 */
requestDate: Date;
/** 등록 일시 */
createDate: Date;
/** 수신 일시 */
receiveDate: Date | null;
/** 메시지 타입 */
chatBubbleType: string;
/** 푸시 알림 여부 */
pushAlarm: boolean;
/** 요청 상태 (COMPLETED: 성공, FAILED: 실패) (message 객체 존재 시 Not Null) */
messageStatus: FriendtalkMessageStatus;
/** 채널 친구 여부 (message 객체 존재 시 Not Null) */
isAddedChannel: boolean;
/** 수신 결과 코드 */
resultCode: string | null;
/** 수신 결과 코드명 */
resultCodeName: string | null;
/** 등록자(콘솔에서 발송 시 사용자 UUID로 저장) */
createUser: string | null;
}
/**
* 친구톡 메시지 상세 정보 (단건 조회용 - 기본 정보 + 메시지 내용)
*
* @group Kakao Interfaces
*/
interface FriendtalkMessageDetail extends FriendtalkMessage {
/** 메시지 내용 */
content: string | null;
/** 성인용 메시지 여부 */
adult: boolean;
/** 헤더 */
header: string | null;
/** 부가 정보 */
additionalContent: string | null;
/** 이미지 정보 */
image: FriendtalkImage | null;
/** 버튼 목록 */
buttons: FriendtalkFreestyleButton[] | null;
/** 와이드 리스트 요소 */
item: FriendtalkWideItemList | null;
/** 쿠폰 요소 */
coupon: FriendtalkCoupon | null;
/** 커머스 요소 */
commerce: FriendtalkCommerce | null;
/** 동영상 요소 */
video: FriendtalkVideo | null;
/** 캐러셀 */
carousel: FriendtalkFreestyleCarouselCommerce | null;
/** 템플릿 파라미터 */
templateParameter: string | null;
/** 대체 발송 상태 코드 */
resendStatusCode: string | null;
/** 대체 발송 상태 코드명 */
resendStatusName: string | null;
/** 대체 발송 결과 코드 */
resendResultCode: string | null;
/** 대체 발송 요청 ID */
resendRequestId: string | null;
}
/**
* 친구톡 템플릿 정보
*
* @group Kakao Interfaces
*/
interface FriendtalkTemplate {
/** 발신 프로필 ID */
plusFriendId: string;
/** 발신 프로필 타입 */
plusFriendType: string;
/** 템플릿 코드 */
templateCode: string;
/** 템플릿 명 */
templateName: string;
/** 메시지 타입 */
chatBubbleType: string;
/** 푸시 알림 여부 (단건 조회에서만 제공) */
pushAlarm: boolean | null;
/** 메시지 내용 */
content: string | null;
/** 헤더 */
header: string | null;
/** 설명 테이블 참고 */
additionalContent: string | null;
/** 성인용 메시지 여부 */
adult: boolean;
/** 이미지 정보 */
image: FriendtalkImage | null;
/** 버튼 목록 */
buttons: FriendtalkTemplateButton[] | null;
/** 와이드 리스트 요소 */
item: FriendtalkWideItemList | null;
/** 쿠폰 요소 */
coupon: FriendtalkCoupon | null;
/** 커머스 요소 */
commerce: FriendtalkCommerce | null;
/** 동영상 요소 */
video: FriendtalkVideo | null;
/** 캐러셀 */
carousel: FriendtalkTemplateCarouselFeedList | null;
/** 템플릿 상태(A: 등록, S: 차단) */
status: string;
/** 등록 일시 */
createDate: Date;
/** 수정 일시 */
updateDate: Date | null;
}
/**
* 친구톡 템플릿 리스트 응답
*
* @group Kakao Interfaces
*/
interface ListFriendtalkTemplatesResponse {
/** 템플릿 리스트 */
templates: FriendtalkTemplate[];
/** 총 개수 */
totalCount: number;
}
/**
* 친구톡 템플릿 단건 조회 응답
*
* @group Kakao Interfaces
*/
interface GetFriendtalkTemplateResponse {
/** 템플릿 정보 */
template: FriendtalkTemplate;
}
/**
* 친구톡 템플릿 생성 응답
*
* @group Kakao Interfaces
*/
interface CreateFriendtalkTemplateResponse {
/** 생성된 템플릿 코드 */
templateCode: string;
}
/**
* 친구톡 템플릿 수정 응답
*
* @group Kakao Interfaces
*/
interface UpdateFriendtalkTemplateResponse extends CreateFriendtalkTemplateResponse {
}
/**
* 친구톡 템플릿 삭제 응답
*
* @group Kakao Interfaces
*/
interface DeleteFriendtalkTemplateResponse {
templateCode: string;
}
/**
* 친구톡 이미지 업로드 응답
*
* @group Kakao Interfaces
*/
interface UploadFriendtalkImageResponse {
/** 이미지 정보 */
image: FriendtalkUploadedImage;
}
/**
* 친구톡 이미지 목록 조회 응답
*
* @group Kakao Interfaces
*/
interface ListFriendtalkUploadedImagesResponse {
/** 이미지 목록 */
images: FriendtalkUploadedImage[];
/** 총 이미지 개수 */
totalCount: number;
}
/**
* 친구톡 이미지 정보
*
* @group Kakao Interfaces
*/
interface FriendtalkUploadedImage {
/** 이미지 시퀀스 */
imageSeq: number;
/** 이미지 URL */
imageUrl: string;
/** 이미지명 */
imageName: string;
}
/**
* 기본 예외 클래스
* @internal
*/
declare class BaseException extends Error {
constructor(message: string);
}
/**
* 유효성 검사 Exception
* @description SDK 기능 호출 시, 파라미터 유효성 검사 실패 시 throw 돼요. SDK 문서에 설명되어 있는 규칙대로 파라미터를 입력해주세요.
* @group Common Exceptions
*/
declare class InvalidParameterException extends BaseException {
constructor(message?: string);
}
/**
* 카카오 채널 토큰 유효성 검사 Exception
* @description 카카오 채널 토큰 유효성 검사 실패 시 throw 돼요.
* @group Common Exceptions
*/
declare class InvalidChannelTokenException extends BaseException {
constructor(message?: string);
}
/**
* 카카오 발신 키 유효성 검사 Exception
* @description 카카오 발신 키 유효성 검사 실패 시 throw 돼요.
* @group Common Exceptions
*/
declare class InvalidSenderKeyException extends BaseException {
constructor(message?: string);
}
/**
* 리소스를 찾을 수 없음 Exception
* @description 요청한 리소스를 찾을 수 없을 때 throw 돼요.
* @group Common Exceptions
*/
declare class NotFoundException extends BaseException {
constructor(message?: string);
}
/**
* 경로를 찾을 수 없음 Exception
* @description 요청한 경로를 찾을 수 없을 때 throw 돼요.
* @internal
*/
declare class RouteNotFoundException extends BaseException {
constructor(message?: string);
}
/**
* 잘못된 첨부파일 Exception
* @description 첨부파일이 유효하지 않을 때 throw
* @internal
*/
declare class InvalidAttachmentException extends BaseException {
constructor(message?: string);
}
/**
* 접근 권한 없음 Exception
* @description 접근 권한이 없을 때 throw 돼요.
* @group Common Exceptions
*/
declare class AccessDeniedException extends BaseException {
constructor(message?: string);
}
/**
* 서버 오류 Exception
* @description 서버에서 예기치 못한 오류가 발생했을 때 throw 돼요. 시스템 관리자에게 문의해주세요.
* @group Common Exceptions
*/
declare class InternalServerErrorException extends BaseException {
constructor(message?: string);
}
/**
* API 크레덴셜 타입
* @group Common Interfaces
* @public
*/
interface AwesomeMessageCredentials {
/** 액세스 키 ID */
accessKeyId: string;
/** 시크릿 액세스 키 */
secretAccessKey: string;
}
/**
* 메시지 발송 옵션
* @group Common Interfaces
* @public
*/
interface SendOptions {
/** 멱등성 키 - 동일한 요청의 중복 처리를 방지합니다 */
idempotencyKey?: string;
}
/**
* HTTP 요청 옵션
* @internal
*/
interface RequestOptions {
method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
body?: unknown;
headers?: Record<string, string>;
formData?: FormData;
}
/**
* 베이스 클라이언트 클래스
*
* 모든 SDK 클라이언트의 공통 기능을 제공합니다.
* HTTP 요청 처리, 인증, 서명 생성 등의 기본 기능을 포함합니다.
*
* @internal
*/
declare class BaseClient {
/** API 인증 크레덴셜 */
protected credentials: AwesomeMessageCredentials;
/** 서비스 API 경로 */
private servicePath;
/** 베이스 URL */
private baseURL;
/** 기본 헤더 */
private defaultHeaders;
/**
* BaseClient 생성자
*
* @param credentials - API 인증 크레덴셜
* @param servicePath - 서비스 API 경로 (/admin, /kakao, /sms 등)
*
* @example
* ```typescript
* const client = new BaseClient(
* { accessKeyId: 'key', secretAccessKey: 'secret' },
* '/admin'
* );
* ```
*/
constructor(credentials: AwesomeMessageCredentials, servicePath: "/admin" | "/kakao" | "/sms" | "/push" | "/email" | "/rcs");
/**
* SendOptions에서 HTTP 헤더를 생성합니다
* @param options - 발송 옵션
* @returns 생성된 헤더 객체
*/
protected createSendHeaders(options?: SendOptions): Record<string, string>;
/**
* HTTP 요청 실행
* @param path - API 경로
* @param options - 요청 옵션
* @returns 응답 데이터
*/
protected makeRequest<T>(path: string, options: RequestOptions): Promise<T>;
/**
* GET 요청
* @param path - API 경로
* @param headers - 추가 헤더
* @returns 응답 데이터
*/
protected get<T>(path: string, headers?: Record<string, string>): Promise<T>;
/**
* POST 요청
* @param path - API 경로
* @param body - 요청 본문
* @param headers - 추가 헤더
* @returns 응답 데이터
*/
protected post<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
/**
* FormData를 사용한 POST 요청 (multipart/form-data)
* @param path - API 경로
* @param formData - undici의 FormData 객체
* @param headers - 추가 헤더
* @returns 응답 데이터
*/
protected postFormData<T>(path: string, formData: FormData, headers?: Record<string, string>): Promise<T>;
/**
* PUT 요청
* @param path - API 경로
* @param body - 요청 본문
* @param headers - 추가 헤더
* @returns 응답 데이터
*/
protected put<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
/**
* DELETE 요청
* @param path - API 경로
* @param headers - 추가 헤더
* @returns 응답 데이터
*/
protected delete<T>(path: string, headers?: Record<string, string>): Promise<T>;
/**
* API Exception인지 확인
* @param error 확인할 에러 객체
* @returns API Exception 여부
*/
private isApiException;
/**
* API 에러를 shared exception으로 변환
* @param statusCode HTTP 상태 코드
* @param data 응답 데이터
* @returns 적절한 shared exception
*/
private handleApiError;
/**
* HMAC-SHA256 서명 헤더 생성
*/
private generateSignatureHeaders;
}
/**
* 관리자 클라이언트
*
* 조직 및 사용자 관리 API 기능을 제공합니다.
* 클라이언트 생성, 관리 등의 관리자 기능을 포함합니다.
*
* @group Admin Classes
*
* @example
* ```typescript
* const adminClient = new AdminClient({
* accessKeyId: 'your-access-key',
* secretAccessKey: 'your-secret-key'
* });
*
* const newClient = await adminClient.createClient({
* externalId: 'my-client-1',
* name: 'My Service Client'
* });
* ```
*
* @public
*/
declare class AdminClient extends BaseClient {
/**
* 관리자 클라이언트 생성자
*
* @param credentials - API 인증 크레덴셜
*
* @example
* ```typescript
* const adminClient = new AdminClient({
* accessKeyId: 'your-access-key',
* secretAccessKey: 'your-secret-key'
* });
* ```
*/
constructor(credentials: AwesomeMessageCredentials);
/**
* 새로운 클라이언트를 생성합니다.
*
* 조직 내에서 새로운 클라이언트를 생성하여 API 접근 권한을 부여합니다.
*
* @param request - 클라이언트 생성 요청 데이터
* @returns 생성된 클라이언트 정보
*
* @throws {@link InvalidParameterException} 요청 데이터가 유효하지 않은 경우
* @throws {@link AccessDeniedException} API 호출 권한이 없는 경우
* @throws {@link InternalServerErrorException} 서버 오류가 발생한 경우
*
* @example
* ```typescript
* const createClientResponse = await adminClient.createClient({
* externalId: "my-client-1",
* name: "My Service Client"
* });
* // createClientResponse: { externalId: "my-client-1", name: "My Service Client" }
* ```
*/
createClient(request: CreateClientRequest): Promise<CreateClientResponse>;
/**
* 조직의 모든 클라이언트 목록을 조회합니다.
*
* 현재 조직에 속한 모든 클라이언트의 목록을 반환합니다.
*
* @returns 클라이언트 목록
*
* @throws {@link AccessDeniedException} API 호출 권한이 없는 경우
* @throws {@link InternalServerErrorException} 서버 오류가 발생한 경우
*
* @example
* ```typescript
* const clients = await adminClient.listClients();
* // clients: [
* // { name: "My Service Client", externalId: "my-client-1", createdAt: "2025-01-01T00:00:00Z" },
* // { name: "Another Client", externalId: "another-service", createdAt: "2025-01-02T00:00:00Z" }
* // ]
* ```
*/
listClients(): Promise<Client[]>;
/**
* 클라이언트를 삭제합니다.
*
* 지정된 연동 ID를 가진 클라이언트를 삭제합니다.
* 삭제된 클라이언트는 더 이상 API에 접근할 수 없습니다.
*
* @param request - 클라이언트 삭제 요청 데이터
* @returns 삭제된 클라이언트 정보
*
* @throws {@link InvalidParameterException} 요청 데이터가 유효하지 않은 경우
* @throws {@link AccessDeniedException} API 호출 권한이 없는 경우
* @throws {@link InternalServerErrorException} 서버 오류가 발생한 경우
*
* @example
* ```typescript
* const deleteClientResponse = await adminClient.deleteClient({
* externalId: "my-client-1"
* });
* // deleteClientResponse: { externalId: "my-client-1" }
* ```
*/
deleteClient(request: DeleteClientRequest): Promise<DeleteClientResponse>;
}
/**
* 카카오 비즈니스 채널 클라이언트
*
* 카카오 비즈니스 채널 관리 API 기능을 제공합니다.
* 친구톡/알림톡 발송을 위한 채널 등록, 인증, 조회, 삭제 등의 기능을 포함합니다.
*
* @group Kakao Classes
*
* @example
* ```typescript
* const kakaoChannelClient = new KakaoChannelClient({
* accessKeyId: 'your-access-key',
* secretAccessKey: 'your-secret-key'
* });
*
* // 채널 카테고리 조회
* const categories = await kakaoChannelClient.getChannelCategories({
* externalId: "my-client-1"
* });
* ```
*
* @public
*/
declare class KakaoChannelClient extends BaseClient {
/**
* 카카오 비즈니스 채널 클라이언트 생성자
*
* @param credentials - API 인증 크레덴셜
*
* @example
* ```typescript
* const kakaoChannelClient = new KakaoChannelClient({
* accessKeyId: 'your-access-key',
* secretAccessKey: 'your-secret-key'
* });
* ```
*/
constructor(credentials: AwesomeMessageCredentials);
/**
* 카카오 채널 카테고리 목록을 조회합니다.
*
* 카카오 채널 등록 시 선택할 수 있는 카테고리 목록을 반환합니다.
*
* @param externalId - 클라이언트 연동 ID
* @returns 카테고리 목록
*
* @throws {@link InvalidParameterException} 요청 데이터가 유효하지 않은 경우
* @throws {@link AccessDeniedException} API 호출 권한이 없는 경우
* @throws {@link InternalServerErrorException} 서버 오류가 발생한 경우
*
* @example
* ```typescript
* const getChannelCategoriesResponse = await kakaoChannelClient.getChannelCategories("my-client-1");
* // getChannelCategoriesResponse: [{ parentCode: "001", depth: 1, code: "001001", name: "쇼핑/유통", subCategories: [...] }]
* ```
*/
getChannelCategories(externalId: string): Promise<KakaoChannelCategory[]>;
/**
* 새로운 카카오 채널을 등록합니다.
*
* 플러스친구 ID와 카테고리 정보를 사용하여 새로운 카카오 채널을 등록합니다.
*
* @param externalId - 클라이언트 연동 ID
* @param request - 채널 등록 요청 데이터
* @returns 등록된 채널 정보
*
* @throws {@link InvalidParameterException} 요청 데이터가 유효하지 않은 경우
* @throws {@link AccessDeniedException} API 호출 권한이 없는 경우
* @throws {@link InternalServerErrorException} 서버 오류가 발생한 경우
*
* @example
* ```typescript
* const createChannelResponse = await kakaoChannelClient.createChannel("my-client-1", {
* plusFriendId: "@mycompany",
* phoneNo: "01500000000",
* categoryCode: "01800010001"
* });
* // createChannelResponse: { plusFriendId: "@mycompany" }
* ```
*/
createChannel(externalId: string, request: CreateKakaoChannelRequest): Promise<CreateKakaoChannelResponse>;
/**
* 카카오 채널 토큰을 인증합니다.
*
* 카카오톡 앱에서 받은 인증 토큰을 사용하여 채널을 인증합니다.
*
* @param externalId - 클라이언트 연동 ID
* @param request - 토큰 인증 요청 데이터
* @returns 인증된 채널 정보
*
* @throws {@link InvalidParameterException} 요청 데이터가 유효하지 않은 경우
* @throws {@link InvalidChannelTokenException} 카카오 채널 토큰이 유효하지 않은 경우
* @throws {@link AccessDeniedException} API 호출 권한이 없는 경우
* @throws {@link InternalServerErrorException} 서버 오류가 발생한 경우
*
* @example
* ```typescript
* const authenticateChannelTokenResponse = await kakaoChannelClient.authenticateChannelToken("my-client-1", {
* plusFriendId: "@mycompany",
* token: 123456
* });
* // authenticateChannelTokenResponse: { plusFriendId: "@mycompany", senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881", status: "YSC03" }
* ```
*/
authenticateChannelToken(externalId: string, request: AuthenticateKakaoChannelTokenRequest): Promise<AuthenticateKakaoChannelTokenResponse>;
/**
* 등록된 카카오 채널 목록을 조회합니다.
*
* 클라이언트에 등록된 카카오 채널들의 목록을 조회합니다.
* 필터 조건을 사용하여 원하는 채널만 조회할 수 있습니다.
*
* @param externalId - 클라이언트 연동 ID
* @param request - 채널 목록 조회 요청 파라미터 (선택적)
* @returns 채널 목록과 전체 건수
*
* @throws {@link InvalidParameterException} 요청 데이터가 유효하지 않은 경우
* @throws {@link AccessDeniedException} API 호출 권한이 없는 경우
* @throws {@link InternalServerErrorException} 서버 오류가 발생한 경우
*
* @example
* ```typescript
* const listChannelsResponse = await kakaoChannelClient.listChannels("my-client-1", {
* status: "YSC03",
* pageNum: 1,
* pageSize: 10
* });
* // listChannelsResponse: { senders: [{ plusFriendId: "@mycompany", senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881", status: "YSC03" }], totalCount: 5 }
* ```
*/
listChannels(externalId: string, request?: ListKakaoChannelsRequest): Promise<ListKakaoChannelsResponse>;
/**
* 특정 카카오 채널의 상세 정보를 조회합니다.
*
* 발신 키를 사용하여 특정 카카오 채널의 상세 정보를 조회합니다.
*
* @param externalId - 클라이언트 연동 ID
* @param senderKey - 조회할 채널의 발신 키
* @returns 채널 상세 정보
*
* @throws {@link InvalidParameterException} 요청 데이터가 유효하지