Class KakaoFriendtalkFreestyleClient

카카오 친구톡 자유형 클라이언트

카카오 친구톡 자유형 메시지 발송 기능을 제공합니다. 8가지 유형의 메시지(텍스트형, 이미지형, 와이드 이미지형, 와이드 아이템 리스트형, 프리미엄 동영상형, 커머스형, 캐러셀 피드형, 캐러셀 커머스형)를 발송할 수 있습니다.

Example

const kakaoFreestyleClient = new KakaoFriendtalkFreestyleClient({
  accessKeyId: 'your-access-key',
  secretAccessKey: 'your-secret-key'
});

// 친구톡 자유형 텍스트 메시지 발송
const sendFriendtalkFreestyleTextMessageResponse = await kakaoFreestyleClient.sendFriendtalkFreestyleTextMessage("my-client-1", {
  senderKey: "SENDER_KEY_123",
  chatBubbleType: "TEXT",
  content: "안녕하세요! 자유형 텍스트 메시지입니다.",
  recipientList: [{ recipientNo: "01012345678" }]
});

Index

Constructors

constructor

new KakaoFriendtalkFreestyleClient(
credentials: AwesomeMessageCredentials,
): KakaoFriendtalkFreestyleClient
카카오 친구톡 자유형 클라이언트 생성자
Parameters
- credentials: AwesomeMessageCredentials
  API 인증 크레덴셜
Returns KakaoFriendtalkFreestyleClient
Example
```
const client = new KakaoFriendtalkFreestyleClient({
  accessKeyId: 'your-access-key',
  secretAccessKey: 'your-secret-key'
});
```
Overrides BaseClient.constructor

Methods

`Protected`createSendHeaders

createSendHeaders(options?: SendOptions): Record<string, string>
SendOptions에서 HTTP 헤더를 생성합니다
Parameters
- Optionaloptions: SendOptions
  발송 옵션
Returns Record<string, string>
생성된 헤더 객체

Inherited from BaseClient.createSendHeaders

`Protected`get

get<T>(path: string, headers?: Record<string, string>): Promise<T>
GET 요청
Type Parameters
- T
Parameters
- path: string
  API 경로
- Optionalheaders: Record<string, string>
  추가 헤더
Returns Promise<T>
응답 데이터

Inherited from BaseClient.get

`Protected`post

post<T>(
    path: string,
    body?: unknown,
    headers?: Record<string, string>,
): Promise<T>
POST 요청
Type Parameters
- T
Parameters
- path: string
  API 경로
- Optionalbody: unknown
  요청 본문
- Optionalheaders: Record<string, string>
  추가 헤더
Returns Promise<T>
응답 데이터

Inherited from BaseClient.post

`Protected`postFormData

postFormData<T>(
    path: string,
    formData: FormData,
    headers?: Record<string, string>,
): Promise<T>
FormData를 사용한 POST 요청 (multipart/form-data)
Type Parameters
- T
Parameters
- path: string
  API 경로
- formData: FormData
  undici의 FormData 객체
- Optionalheaders: Record<string, string>
  추가 헤더
Returns Promise<T>
응답 데이터

Inherited from BaseClient.postFormData

`Protected`put

put<T>(
    path: string,
    body?: unknown,
    headers?: Record<string, string>,
): Promise<T>
PUT 요청
Type Parameters
- T
Parameters
- path: string
  API 경로
- Optionalbody: unknown
  요청 본문
- Optionalheaders: Record<string, string>
  추가 헤더
Returns Promise<T>
응답 데이터

Inherited from BaseClient.put

`Protected`delete

delete<T>(path: string, headers?: Record<string, string>): Promise<T>
DELETE 요청
Type Parameters
- T
Parameters
- path: string
  API 경로
- Optionalheaders: Record<string, string>
  추가 헤더
Returns Promise<T>
응답 데이터

Inherited from BaseClient.delete

`Protected`deleteWithBody

deleteWithBody<T>(
    path: string,
    body?: unknown,
    headers?: Record<string, string>,
): Promise<T>
DELETE 요청 (body 포함)
Type Parameters
- T
Parameters
- path: string
  API 경로
- Optionalbody: unknown
  요청 본문
- Optionalheaders: Record<string, string>
  추가 헤더
Returns Promise<T>
응답 데이터

Inherited from BaseClient.deleteWithBody

sendFriendtalkFreestyleTextMessage

sendFriendtalkFreestyleTextMessage(
    externalId: string,
    request: SendFriendtalkFreestyleTextMessageRequest,
    options?: SendOptions,
): Promise<SendFriendtalkMessageResponse>

친구톡 자유형 텍스트 메시지를 발송합니다.

텍스트형 친구톡 메시지를 자유롭게 작성하여 발송합니다.

Parameters

externalId: string
클라이언트 연동 ID
request: SendFriendtalkFreestyleTextMessageRequest
메시지 발송 요청 데이터
Optionaloptions: SendOptions
발송 옵션 (멱등성 키)

Returns Promise<SendFriendtalkMessageResponse>

발송 결과 정보

Throws

InvalidParameterException 요청 데이터가 유효하지 않은 경우

Throws

InvalidSenderKeyException 카카오 친구톡 발신 키가 유효하지 않은 경우

Throws

AccessDeniedException API 호출 권한이 없는 경우

Throws

InternalServerErrorException 서버 오류가 발생한 경우

Example

// 기본 사용
const result = await kakaoClient.sendFriendtalkFreestyleTextMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  content: "안녕하세요! 자유형 텍스트 메시지입니다.",
  recipientList: [{ recipientNo: "01012345678" }]
});

// 버튼과 멱등성 키를 함께 사용
const result = await kakaoClient.sendFriendtalkFreestyleTextMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  content: "안녕하세요! 자유형 텍스트 메시지입니다.",
  buttons: [
    {
      name: "웹사이트 방문",
      type: "WL",
      linkMo: "https://example.com"
    }
  ],
  recipientList: [{ recipientNo: "01012345678" }]
}, {
  idempotencyKey: "unique-key-123"
});
// 응답: { requestId: "202507071756377Qd0nqWbty0", sendResults: [
//   { recipientSeq: 1, recipientNo: "01012345678", resultCode: 0, resultMessage: "SUCCESS" }
// ] }

sendFriendtalkFreestyleImageMessage

sendFriendtalkFreestyleImageMessage(
    externalId: string,
    request: SendFriendtalkFreestyleImageMessageRequest,
    options?: SendOptions,
): Promise<SendFriendtalkMessageResponse>
친구톡 자유형 이미지 메시지를 발송합니다.

이미지형 친구톡 메시지를 자유롭게 작성하여 발송합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- request: SendFriendtalkFreestyleImageMessageRequest
  메시지 발송 요청 데이터
- Optionaloptions: SendOptions
Returns Promise<SendFriendtalkMessageResponse>
발송 결과 정보
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

Throws
InvalidSenderKeyException 카카오 친구톡 발신 키가 유효하지 않은 경우

Throws
AccessDeniedException API 호출 권한이 없는 경우

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.sendFriendtalkFreestyleImageMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  content: "안녕하세요! 자유형 이미지 메시지입니다.",
  image: {
    imageUrl: "https://example.com/image.jpg"
  },
  buttons: [
    {
      name: "상품 보기",
      type: "WL",
      linkMo: "https://example.com/product"
    }
  ],
  recipientList: [{ recipientNo: "01012345678" }]
});
// 응답: { requestId: "202507071756377Qd0nqWbty0", sendResults: [
//   { recipientSeq: 1, recipientNo: "01012345678", resultCode: 0, resultMessage: "SUCCESS" }
// ] }
```

sendFriendtalkFreestyleWideImageMessage

sendFriendtalkFreestyleWideImageMessage(
    externalId: string,
    request: SendFriendtalkFreestyleWideImageMessageRequest,
    options?: SendOptions,
): Promise<SendFriendtalkMessageResponse>
친구톡 자유형 와이드 이미지 메시지를 발송합니다.

와이드 이미지형 친구톡 메시지를 자유롭게 작성하여 발송합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- request: SendFriendtalkFreestyleWideImageMessageRequest
  메시지 발송 요청 데이터
- Optionaloptions: SendOptions
Returns Promise<SendFriendtalkMessageResponse>
발송 결과 정보
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

Throws
InvalidSenderKeyException 카카오 친구톡 발신 키가 유효하지 않은 경우

Throws
AccessDeniedException API 호출 권한이 없는 경우

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.sendFriendtalkFreestyleWideImageMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  content: "와이드 이미지",
  image: {
    imageUrl: "https://example.com/wide-image.jpg"
  },
  buttons: [
    {
      name: "자세히",
      type: "WL",
      linkMo: "https://example.com/details"
    }
  ],
  recipientList: [{ recipientNo: "01012345678" }]
});
// 응답: { requestId: "202507071756377Qd0nqWbty0", sendResults: [
//   { recipientSeq: 1, recipientNo: "01012345678", resultCode: 0, resultMessage: "SUCCESS" }
// ] }
```

sendFriendtalkFreestyleWideItemListMessage

sendFriendtalkFreestyleWideItemListMessage(
    externalId: string,
    request: SendFriendtalkFreestyleWideItemListMessageRequest,
    options?: SendOptions,
): Promise<SendFriendtalkMessageResponse>
친구톡 자유형 와이드 아이템 리스트 메시지를 발송합니다.

와이드 아이템 리스트형 친구톡 메시지를 자유롭게 작성하여 발송합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- request: SendFriendtalkFreestyleWideItemListMessageRequest
  메시지 발송 요청 데이터
- Optionaloptions: SendOptions
Returns Promise<SendFriendtalkMessageResponse>
발송 결과 정보
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

Throws
InvalidSenderKeyException 카카오 친구톡 발신 키가 유효하지 않은 경우

Throws
AccessDeniedException API 호출 권한이 없는 경우

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.sendFriendtalkFreestyleWideItemListMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  header: "추천 상품",
  item: {
    list: [
      {
        imageUrl: "https://example.com/item1.jpg",
        linkMo: "https://example.com/item1"
      },
      {
        imageUrl: "https://example.com/item2.jpg",
        linkMo: "https://example.com/item2"
      }
    ]
  },
  buttons: [
    {
      name: "전체보기",
      type: "WL",
      linkMo: "https://example.com/all"
    }
  ],
  recipientList: [{ recipientNo: "01012345678" }]
});
// 응답: { requestId: "202507071756377Qd0nqWbty0", sendResults: [
//   { recipientSeq: 1, recipientNo: "01012345678", resultCode: 0, resultMessage: "SUCCESS" }
// ] }
```

sendFriendtalkFreestylePremiumVideoMessage

sendFriendtalkFreestylePremiumVideoMessage(
    externalId: string,
    request: SendFriendtalkFreestylePremiumVideoMessageRequest,
    options?: SendOptions,
): Promise<SendFriendtalkMessageResponse>
친구톡 자유형 프리미엄 동영상 메시지를 발송합니다.

프리미엄 동영상형 친구톡 메시지를 자유롭게 작성하여 발송합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- request: SendFriendtalkFreestylePremiumVideoMessageRequest
  메시지 발송 요청 데이터
- Optionaloptions: SendOptions
Returns Promise<SendFriendtalkMessageResponse>
발송 결과 정보
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

Throws
InvalidSenderKeyException 카카오 친구톡 발신 키가 유효하지 않은 경우

Throws
AccessDeniedException API 호출 권한이 없는 경우

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.sendFriendtalkFreestylePremiumVideoMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  header: "동영상 콘텐츠",
  content: "새로운 영상을 확인해보세요",
  video: {
    videoUrl: "https://tv.kakao.com/v/123456"
  },
  buttons: [
    {
      name: "시청하기",
      type: "WL",
      linkMo: "https://tv.kakao.com/v/123456"
    }
  ],
  recipientList: [{ recipientNo: "01012345678" }]
});
// 응답: { requestId: "202507071756377Qd0nqWbty0", sendResults: [
//   { recipientSeq: 1, recipientNo: "01012345678", resultCode: 0, resultMessage: "SUCCESS" }
// ] }
```

sendFriendtalkFreestyleCommerceMessage

sendFriendtalkFreestyleCommerceMessage(
    externalId: string,
    request: SendFriendtalkFreestyleCommerceMessageRequest,
    options?: SendOptions,
): Promise<SendFriendtalkMessageResponse>

친구톡 자유형 커머스 메시지를 발송합니다.

커머스형 친구톡 메시지를 자유롭게 작성하여 발송합니다.

Parameters

externalId: string
클라이언트 연동 ID
request: SendFriendtalkFreestyleCommerceMessageRequest
메시지 발송 요청 데이터
Optionaloptions: SendOptions

Returns Promise<SendFriendtalkMessageResponse>

발송 결과 정보

Throws

InvalidParameterException 요청 데이터가 유효하지 않은 경우

Throws

InvalidSenderKeyException 카카오 친구톡 발신 키가 유효하지 않은 경우

Throws

AccessDeniedException API 호출 권한이 없는 경우

Throws

InternalServerErrorException 서버 오류가 발생한 경우

Example

const result = await kakaoClient.sendFriendtalkFreestyleCommerceMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  additionalContent: "특별 할인 상품",
  image: {
    imageUrl: "https://example.com/product.jpg"
  },
  commerce: {
    title: "무선 이어폰",
    regularPrice: 100000,
    discountPrice: 80000,
    discountRate: 20
  },
  buttons: [
    {
      name: "구매하기",
      type: "WL",
      linkMo: "https://example.com/buy"
    },
    {
      name: "찜하기",
      type: "WL",
      linkMo: "https://example.com/wishlist"
    }
  ],
  recipientList: [{ recipientNo: "01012345678" }]
});
// 응답: { requestId: "202507071756377Qd0nqWbty0", sendResults: [
//   { recipientSeq: 1, recipientNo: "01012345678", resultCode: 0, resultMessage: "SUCCESS" }
// ] }

sendFriendtalkFreestyleCarouselFeedMessage

sendFriendtalkFreestyleCarouselFeedMessage(
    externalId: string,
    request: SendFriendtalkFreestyleCarouselFeedMessageRequest,
    options?: SendOptions,
): Promise<SendFriendtalkMessageResponse>

친구톡 자유형 캐러셀 피드 메시지를 발송합니다.

캐러셀 피드형 친구톡 메시지를 자유롭게 작성하여 발송합니다.

Parameters

externalId: string
클라이언트 연동 ID
request: SendFriendtalkFreestyleCarouselFeedMessageRequest
메시지 발송 요청 데이터
Optionaloptions: SendOptions

Returns Promise<SendFriendtalkMessageResponse>

발송 결과 정보

Throws

InvalidParameterException 요청 데이터가 유효하지 않은 경우

Throws

InvalidSenderKeyException 카카오 친구톡 발신 키가 유효하지 않은 경우

Throws

AccessDeniedException API 호출 권한이 없는 경우

Throws

InternalServerErrorException 서버 오류가 발생한 경우

Example

const result = await kakaoClient.sendFriendtalkFreestyleCarouselFeedMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  carousel: {
    list: [
      {
        header: "신상품",
        message: "새로 출시된 상품입니다",
        imageUrl: "https://example.com/item1.jpg",
        imageLink: "https://example.com/item1",
        buttons: [
          {
            name: "자세히",
            type: "WL",
            linkMo: "https://example.com/details1"
          }
        ]
      },
      {
        header: "베스트",
        message: "인기 상품입니다",
        imageUrl: "https://example.com/item2.jpg",
        imageLink: "https://example.com/item2",
        buttons: [
          {
            name: "구매",
            type: "WL",
            linkMo: "https://example.com/buy2"
          }
        ]
      }
    ]
  },
  recipientList: [{ recipientNo: "01012345678" }]
});
// 응답: { requestId: "202507071756377Qd0nqWbty0", sendResults: [
//   { recipientSeq: 1, recipientNo: "01012345678", resultCode: 0, resultMessage: "SUCCESS" }
// ] }

sendFriendtalkFreestyleCarouselCommerceMessage

sendFriendtalkFreestyleCarouselCommerceMessage(
    externalId: string,
    request: SendFriendtalkFreestyleCarouselCommerceMessageRequest,
    options?: SendOptions,
): Promise<SendFriendtalkMessageResponse>

친구톡 자유형 캐러셀 커머스 메시지를 발송합니다.

캐러셀 커머스형 친구톡 메시지를 자유롭게 작성하여 발송합니다.

Parameters

externalId: string
클라이언트 연동 ID
request: SendFriendtalkFreestyleCarouselCommerceMessageRequest
메시지 발송 요청 데이터
Optionaloptions: SendOptions

Returns Promise<SendFriendtalkMessageResponse>

발송 결과 정보

Throws

InvalidParameterException 요청 데이터가 유효하지 않은 경우

Throws

InvalidSenderKeyException 카카오 친구톡 발신 키가 유효하지 않은 경우

Throws

AccessDeniedException API 호출 권한이 없는 경우

Throws

InternalServerErrorException 서버 오류가 발생한 경우

Example

const result = await kakaoClient.sendFriendtalkFreestyleCarouselCommerceMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  carousel: {
    list: [
      {
        additionalContent: "신상품 특가",
        imageUrl: "https://example.com/product1.jpg",
        imageLink: "https://example.com/product1",
        commerce: {
          title: "스마트폰",
          regularPrice: 800000,
          discountPrice: 600000,
          discountRate: 25
        },
        buttons: [
          {
            name: "구매",
            type: "WL",
            linkMo: "https://example.com/buy1"
          }
        ]
      },
      {
        additionalContent: "인기상품",
        imageUrl: "https://example.com/product2.jpg",
        imageLink: "https://example.com/product2",
        commerce: {
          title: "태블릿",
          regularPrice: 500000,
          discountPrice: 400000,
          discountRate: 20
        },
        buttons: [
          {
            name: "구매",
            type: "WL",
            linkMo: "https://example.com/buy2"
          }
        ]
      }
    ]
  },
  recipientList: [{ recipientNo: "01012345678" }]
});
// 응답: { requestId: "202507071756377Qd0nqWbty0", sendResults: [
//   { recipientSeq: 1, recipientNo: "01012345678", resultCode: 0, resultMessage: "SUCCESS" }
// ] }

Properties

`Protected`credentials

credentials: AwesomeMessageCredentials

API 인증 크레덴셜

Class KakaoFriendtalkFreestyleClient

Example

Index

Constructors

Methods

Properties

Constructors

constructor

Parameters

Returns KakaoFriendtalkFreestyleClient

Example

Methods

ProtectedcreateSendHeaders

Parameters

Returns Record<string, string>

Protectedget

Type Parameters

Parameters

Returns Promise<T>

Protectedpost

Type Parameters

Parameters

Returns Promise<T>

ProtectedpostFormData

Type Parameters

Parameters

Returns Promise<T>

Protectedput

Type Parameters

Parameters

Returns Promise<T>

Protecteddelete

Type Parameters

Parameters

Returns Promise<T>

ProtecteddeleteWithBody

Type Parameters

Parameters

Returns Promise<T>

sendFriendtalkFreestyleTextMessage

Parameters

Returns Promise<SendFriendtalkMessageResponse>

Throws

Throws

Throws

Throws

Example

sendFriendtalkFreestyleImageMessage

Parameters

Returns Promise<SendFriendtalkMessageResponse>

Throws

Throws

Throws

Throws

Example

sendFriendtalkFreestyleWideImageMessage

Parameters

Returns Promise<SendFriendtalkMessageResponse>

Throws

Throws

Throws

Throws

Example

sendFriendtalkFreestyleWideItemListMessage

Parameters

Returns Promise<SendFriendtalkMessageResponse>

Throws

Throws

Throws

Throws

Example

sendFriendtalkFreestylePremiumVideoMessage

Parameters

Returns Promise<SendFriendtalkMessageResponse>

Throws

Throws

Throws

Throws

Example

sendFriendtalkFreestyleCommerceMessage

`Protected`createSendHeaders

`Protected`get

`Protected`post

`Protected`postFormData

`Protected`put

`Protected`delete

`Protected`deleteWithBody

`Protected`credentials