Class KakaoAlimtalkClient

카카오 알림톡 클라이언트

카카오 알림톡 메시지 발송 및 조회 기능을 제공합니다. 일반 메시지, 인증 메시지 발송과 메시지 조회, 결과 조회, 대량 메시지 조회를 지원합니다.

Example

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

// 알림톡 대체 발송 메시지 발송
const sendResult = await kakaoAlimtalkClient.sendAlimtalkSubstituteMessage("my-client-1", {
  senderKey: "SENDER_KEY_123",
  templateCode: "TEMPLATE_001",
  recipientList: [{ recipientNo: "01012345678" }]
});

// 알림톡 메시지 목록 조회
const listResult = await kakaoAlimtalkClient.listAlimtalkMessages("my-client-1", {
  startRequestDate: new Date("2023-01-01T00:00:00+09:00"),
  endRequestDate: new Date("2023-01-31T23:59:00+09:00")
});

Constructors

constructor

new KakaoAlimtalkClient(
credentials: AwesomeMessageCredentials,
): KakaoAlimtalkClient
카카오 알림톡 클라이언트 생성자
Parameters
- credentials: AwesomeMessageCredentials
  API 인증 크레덴셜
Returns KakaoAlimtalkClient
Example
```
const client = new KakaoAlimtalkClient({
  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

sendAlimtalkSubstituteMessage

sendAlimtalkSubstituteMessage(
    externalId: string,
    request: SendAlimtalkSubstituteMessageRequest,
    options?: SendOptions,
): Promise<SendAlimtalkMessageResponse>
알림톡 대체 발송 메시지를 발송합니다.

템플릿 코드를 사용하여 대체 발송 방식으로 알림톡 메시지를 발송합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- request: SendAlimtalkSubstituteMessageRequest
  메시지 발송 요청 데이터
- Optionaloptions: SendOptions
  발송 옵션 (멱등성 키)
Returns Promise<SendAlimtalkMessageResponse>
발송 결과 정보
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

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

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
// 기본 사용
const result = await kakaoClient.sendAlimtalkSubstituteMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  templateCode: "TEMPLATE_001",
  recipientList: [{
    recipientNo: "01012345678",
    templateParameter: { name: "홍길동", date: "2023-12-25" }
  }]
});

// 멱등성 키 사용
const result = await kakaoClient.sendAlimtalkSubstituteMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  templateCode: "TEMPLATE_001",
  recipientList: [{ recipientNo: "01012345678" }]
}, {
  idempotencyKey: "unique-key-123"
});
```

sendAlimtalkRawMessage

sendAlimtalkRawMessage(
    externalId: string,
    request: SendAlimtalkRawMessageRequest,
    options?: SendOptions,
): Promise<SendAlimtalkMessageResponse>
알림톡 전문 발송 메시지를 발송합니다.

템플릿 치환 없이 전문 그대로 발송하는 방식으로 알림톡 메시지를 발송합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- request: SendAlimtalkRawMessageRequest
  메시지 발송 요청 데이터
- Optionaloptions: SendOptions
  발송 옵션 (멱등성 키)
Returns Promise<SendAlimtalkMessageResponse>
발송 결과 정보
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

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

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.sendAlimtalkRawMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  templateCode: "TEMPLATE_001",
  recipientList: [{
    recipientNo: "01012345678",
    content: "안녕하세요, 홍길동님.\n주문하신 상품이 2023-12-25에 배송됩니다."
  }]
});
```

sendAlimtalkAuthSubstituteMessage

sendAlimtalkAuthSubstituteMessage(
    externalId: string,
    request: SendAlimtalkSubstituteMessageRequest,
    options?: SendOptions,
): Promise<SendAlimtalkMessageResponse>
알림톡 인증 대체 발송 메시지를 발송합니다.

인증 메시지 타입으로 대체 발송 방식의 알림톡을 발송합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- request: SendAlimtalkSubstituteMessageRequest
  메시지 발송 요청 데이터
- Optionaloptions: SendOptions
  발송 옵션 (멱등성 키)
Returns Promise<SendAlimtalkMessageResponse>
발송 결과 정보
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

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

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.sendAlimtalkAuthSubstituteMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  templateCode: "AUTH_TEMPLATE_001",
  recipientList: [{
    recipientNo: "01012345678",
    templateParameter: { code: "123456" }
  }]
});
```

sendAlimtalkAuthRawMessage

sendAlimtalkAuthRawMessage(
    externalId: string,
    request: SendAlimtalkRawMessageRequest,
    options?: SendOptions,
): Promise<SendAlimtalkMessageResponse>
알림톡 인증 전문 발송 메시지를 발송합니다.

인증 메시지 타입으로 전문 발송 방식의 알림톡을 발송합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- request: SendAlimtalkRawMessageRequest
  메시지 발송 요청 데이터
- Optionaloptions: SendOptions
  발송 옵션 (멱등성 키)
Returns Promise<SendAlimtalkMessageResponse>
발송 결과 정보
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

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

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.sendAlimtalkAuthRawMessage("my-client-1", {
  senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881",
  templateCode: "AUTH_TEMPLATE_001",
  recipientList: [{
    recipientNo: "01012345678",
    content: "인증번호: 123456"
  }]
});
```

listAlimtalkMessages

listAlimtalkMessages(
externalId: string,
query: ListAlimtalkMessagesRequest,
): Promise<ListAlimtalkMessagesResponse>
알림톡 메시지 목록을 조회합니다.

다양한 조건으로 알림톡 메시지 발송 내역을 조회합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- query: ListAlimtalkMessagesRequest
  조회 조건
Returns Promise<ListAlimtalkMessagesResponse>
메시지 목록 및 총 개수
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.listAlimtalkMessages("my-client-1", {
  startRequestDate: new Date("2023-01-01T00:00:00+09:00"),
  endRequestDate: new Date("2023-01-31T23:59:00+09:00"),
  pageNum: 1,
  pageSize: 20
});
// result: { messages: [{ requestId: "MSG123", recipientSeq: 1, senderKey: "SENDER_KEY", templateCode: "TEMPLATE_001", messageStatus: "COMPLETED" }], totalCount: 42 }
```

getAlimtalkMessage

getAlimtalkMessage(
    externalId: string,
    requestId: string,
    recipientSeq: number,
): Promise<GetAlimtalkMessageResponse>
알림톡 메시지 단건을 조회합니다.

요청 ID와 수신자 시퀀스 번호로 특정 메시지의 상세 정보를 조회합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- requestId: string
  요청 ID
- recipientSeq: number
  수신자 시퀀스 번호
Returns Promise<GetAlimtalkMessageResponse>
메시지 상세 정보
Throws
NotFoundException 메시지가 존재하지 않는 경우

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const message = await kakaoClient.getAlimtalkMessage("my-client-1", "MSG123456", 1);
// message: { requestId: "MSG123456", recipientSeq: 1, senderKey: "SENDER_KEY", templateCode: "TEMPLATE_001", content: "...", messageStatus: "COMPLETED" }
```

cancelAlimtalkMessage

cancelAlimtalkMessage(
    externalId: string,
    requestId: string,
    recipientSeq?: number,
): Promise<void>
알림톡 메시지 발송을 취소합니다.

발송 예약된 메시지를 취소합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- requestId: string
  요청 ID
- OptionalrecipientSeq: number
  수신자 시퀀스 번호 (선택, 미입력 시 요청 ID의 모든 발송 건 취소)
Returns Promise<void>
Throws
NotFoundException 메시지가 존재하지 않는 경우

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
// 요청 ID의 모든 발송 건 취소
await kakaoClient.cancelAlimtalkMessage("my-client-1", "MSG123456");

// 특정 수신자만 취소
await kakaoClient.cancelAlimtalkMessage("my-client-1", "MSG123456", 1);
```

listAlimtalkMessageResults

listAlimtalkMessageResults(
externalId: string,
query: ListAlimtalkMessageResultsRequest,
): Promise<ListAlimtalkMessageResultsResponse>
알림톡 메시지 결과 목록을 조회합니다.

메시지 발송 결과를 조회합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- query: ListAlimtalkMessageResultsRequest
  조회 조건
Returns Promise<ListAlimtalkMessageResultsResponse>
결과 목록 및 총 개수
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.listAlimtalkMessageResults("my-client-1", {
  startUpdateDate: new Date("2023-01-01T00:00:00+09:00"),
  endUpdateDate: new Date("2023-01-31T23:59:00+09:00"),
  messageStatus: "COMPLETED"
});
```

countAlimtalkMessageResults

countAlimtalkMessageResults(
externalId: string,
query: ListAlimtalkMessageResultsRequest,
): Promise<CountAlimtalkMessageResultsResponse>
알림톡 메시지 결과 건수를 조회합니다.

조건에 맞는 메시지 결과의 총 건수를 조회합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- query: ListAlimtalkMessageResultsRequest
  조회 조건
Returns Promise<CountAlimtalkMessageResultsResponse>
결과 건수 정보
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.countAlimtalkMessageResults("my-client-1", {
  startUpdateDate: new Date("2023-01-01T00:00:00+09:00"),
  endUpdateDate: new Date("2023-01-31T23:59:00+09:00"),
  messageStatus: "COMPLETED"
});
// result: { count: 1234 }
```

listAlimtalkMassMessages

listAlimtalkMassMessages(
externalId: string,
query: ListAlimtalkMassMessagesRequest,
): Promise<ListAlimtalkMassMessagesResponse>
알림톡 대량 메시지 요청 목록을 조회합니다.

대량 발송 요청 내역을 조회합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- query: ListAlimtalkMassMessagesRequest
  조회 조건
Returns Promise<ListAlimtalkMassMessagesResponse>
대량 메시지 요청 목록 및 총 개수
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.listAlimtalkMassMessages("my-client-1", {
  startRequestDate: new Date("2023-01-01T00:00:00+09:00"),
  endRequestDate: new Date("2023-01-31T23:59:00+09:00")
});
```

listAlimtalkMassRecipients

listAlimtalkMassRecipients(
    externalId: string,
    requestId: string,
    query: ListAlimtalkMassRecipientsRequest,
): Promise<ListAlimtalkMassRecipientsResponse>
알림톡 대량 메시지 수신자 목록을 조회합니다.

특정 대량 발송 요청의 수신자 목록을 조회합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- requestId: string
  요청 ID
- query: ListAlimtalkMassRecipientsRequest
  조회 조건
Returns Promise<ListAlimtalkMassRecipientsResponse>
수신자 목록 및 총 개수
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

Throws
NotFoundException 요청 ID가 존재하지 않는 경우

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.listAlimtalkMassRecipients("my-client-1", "MASS_REQ_123", {
  startRequestDate: new Date("2023-01-01T00:00:00+09:00"),
  endRequestDate: new Date("2023-01-31T23:59:00+09:00")
});
```

getAlimtalkMassRecipient

getAlimtalkMassRecipient(
    externalId: string,
    requestId: string,
    recipientSeq: number,
): Promise<AlimtalkMassRecipient>
알림톡 대량 메시지 수신자 단건을 조회합니다.

특정 대량 발송 요청의 특정 수신자 정보를 조회합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- requestId: string
  요청 ID
- recipientSeq: number
  수신자 시퀀스 번호
Returns Promise<AlimtalkMassRecipient>
수신자 상세 정보
Throws
NotFoundException 수신자가 존재하지 않는 경우

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const recipient = await kakaoClient.getAlimtalkMassRecipient("my-client-1", "MASS_REQ_123", 1);
```

listAlimtalkAuthMessages

listAlimtalkAuthMessages(
externalId: string,
query: ListAlimtalkMessagesRequest,
): Promise<ListAlimtalkMessagesResponse>
알림톡 인증 메시지 목록을 조회합니다.

인증 메시지 발송 내역을 조회합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- query: ListAlimtalkMessagesRequest
  조회 조건
Returns Promise<ListAlimtalkMessagesResponse>
인증 메시지 목록 및 총 개수
Throws
InvalidParameterException 요청 데이터가 유효하지 않은 경우

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const result = await kakaoClient.listAlimtalkAuthMessages("my-client-1", {
  startRequestDate: new Date("2023-01-01T00:00:00+09:00"),
  endRequestDate: new Date("2023-01-31T23:59:00+09:00")
});
```

getAlimtalkAuthMessage

getAlimtalkAuthMessage(
    externalId: string,
    requestId: string,
    recipientSeq: number,
): Promise<GetAlimtalkMessageResponse>
알림톡 인증 메시지 단건을 조회합니다.

요청 ID와 수신자 시퀀스 번호로 특정 인증 메시지의 상세 정보를 조회합니다.
Parameters
- externalId: string
  클라이언트 연동 ID
- requestId: string
  요청 ID
- recipientSeq: number
  수신자 시퀀스 번호
Returns Promise<GetAlimtalkMessageResponse>
인증 메시지 상세 정보
Throws
NotFoundException 메시지가 존재하지 않는 경우

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

Throws
InternalServerErrorException 서버 오류가 발생한 경우
Example
```
const message = await kakaoClient.getAlimtalkAuthMessage("my-client-1", "AUTH_MSG_123", 1);
```

Properties

`Protected`credentials

credentials: AwesomeMessageCredentials

API 인증 크레덴셜

Class KakaoAlimtalkClient

Example

Index

Constructors

Methods

Properties

Constructors

constructor

Parameters

Returns KakaoAlimtalkClient

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>

sendAlimtalkSubstituteMessage

Parameters

Returns Promise<SendAlimtalkMessageResponse>

Throws

Throws

Throws

Throws

Example

sendAlimtalkRawMessage

Parameters

Returns Promise<SendAlimtalkMessageResponse>

Throws

Throws

Throws

Throws

Example

sendAlimtalkAuthSubstituteMessage

Parameters

Returns Promise<SendAlimtalkMessageResponse>

Throws

Throws

Throws

Throws

Example

sendAlimtalkAuthRawMessage

Parameters

Returns Promise<SendAlimtalkMessageResponse>

Throws

Throws

Throws

Throws

Example

listAlimtalkMessages

Parameters

Returns Promise<ListAlimtalkMessagesResponse>

Throws

Throws

Throws

Example

getAlimtalkMessage

Parameters

`Protected`createSendHeaders

`Protected`get

`Protected`post

`Protected`postFormData

`Protected`put

`Protected`delete

`Protected`deleteWithBody

`Protected`credentials