> For the complete documentation index, see [llms.txt](https://tech.x2bee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tech.x2bee.com/dev-guide/developer-guide-en/dev-start/customer-message-sending/kakaotalk-notification-sending.md).

# KakaoTalk Notification Sending

This document covers the KakaoTalk notification sending source code and method.

First, it explains how to configure and verify the Config settings.\
Second, it explains how to write it at each business layer.

{% hint style="info" %}
**\<update>**

2023.08.03

* A failover-related guide has been added.
* We recommend calling Api Common when sending KakaoTalk notifications.
  {% endhint %}

***

## Config Settings

**application.yml example:**

```yaml
spring:
  bizMessage:
    accessKey: VHIZ4hLLrhf6uyRIrk4F
    secretKey: pHvcggk52DXYOYYUDvXyLi5RkcmwneeMoOx8xoTd
    alimTalk:
      plusFriendId: "@X2BEE"
      serviceId: ncp:kkobizmsg:kr:3094856:x2bee
```

Required properties

* <kbd>accessKey</kbd>
* <kbd>secretKey</kbd>
* <kbd>alimTalk.plusFriendId</kbd>
* <kbd>alimTalk.serviceId</kbd>

The above properties are issued by NCP (Naver Cloud Platform).

## Sample Source and Description

* Project example: <https://gitlab.x2bee.com/x2bee-venus-beta/venus-x2bee-api-sample-vanilla>

**BizMessageController** Example (Summary):

```java
... 
private final MessageSender messageSender;

/* 알림톡 샘플 */
@PostMapping("/alimTalk")
public ResponseEntity<Response> bizMessage() throws Exception {
    ...
    String templateCode = "PO2B";
    String template = "[#{coNm}] 배송시작 안내\n" +
                      "\n" +
                      "#{mbrNm} 고객님께서 주문하신 상품의 배송이 공 시작됩니다.\n" +
                      "\n" +
                      "■ 주문상품 정보\n" +
                      "- 주문번호 : #{orderNo}\n" +
                      "- 상품명 : #{goodsNm}\n" +
                      "\n" +
                      "※ 고객센터 #{ccNo}(유료)"; // Template 문구 -> 변수명 처리로 변경됨.

    // SendParams params = 임시객체 (비즈니스 로직 VO 사용 권장)
    SendParams params = SendParams.builder()
        .coNm("X2BEE")
        .mbrNm("김플래")
        .orderNo("O0000000001")
        .goodsNm("양말 외 1건")
        .ccNo("02-3333-4444")
        .build();

    template = messageSender.replaceTemplateFormat(template, params);

    List<Buttons> buttons = new ArrayList<>();
    // 버튼 추가
    buttons.add(Buttons.builder()
        .linkPc("https://plateer.com")      // https:// 포함, 필수
        .linkMobile("https://plateer.com")  // https:// 포함, 필수
        .name("주문상세 보기")               // 템플릿 버튼 명과 정확히 일치해야 함
        .type("WL")                         // 템플릿 버튼 타입과 정확히 일치해야 함. 기본 WL
        .build());

    for (int i = 0; i < 1; i++) {
        messagesList.add(MessagesRequest.builder()
            .receiverPhoneNumber("01012341234")
            .content(template)
            .buttons(buttons)
            .build());
    }

    //======================================================
    // API-COMMON 에서 직접 호출시
    BizMessageResponse str = messageSender.sendAlimTalk(messagesList, templateCode);
    //======================================================

    // API-COMMON 호출시
    BizMessageRequest request = BizMessageRequest.builder()
        .messages(messagesList)     // 필수
        .templateCode(templateCode) // 필수
        .build();

    BizMessageResponse response = restApiUtil.post(
        this.commonApiUrl + "/api/common/interface/bizmessage/sendalimtalk",
        request,
        new ParameterizedTypeReference<Response<BizMessageResponse>>() {}
    ).getPayload();

    ...
}
...
```

* (1), (2), (7), (8) should be written by referring to the table below.
* <mark style="color:red;">For (2), (7), (8), the template content, button name, and button type must exactly match what was approved on Naver Cloud Platform.</mark>
* Refer to the <kbd><mark style="color:red;">Template Content column<mark style="color:red;"></kbd> <mark style="color:red;">and the</mark> <kbd><mark style="color:red;">type<mark style="color:red;"></kbd> <mark style="color:red;">and</mark> <kbd><mark style="color:red;">name<mark style="color:red;"></kbd> <mark style="color:red;">of the Button column.</mark>

{% hint style="info" %}
If the #{...} variable names in the template content match the variable names of the business logic VO, they will be substituted in replaceTemplateFormat. The example's SendParams is not provided.
{% endhint %}

### NCP Approved Template List Table

<table><thead><tr><th width="77.888916015625"></th><th width="107">TMPL-CODE (1)</th><th width="108.111083984375">Classification</th><th>Template Content (2)</th><th>Button (7), (8)</th></tr></thead><tbody><tr><td>1</td><td>PO1A</td><td>Product Q&#x26;A Answer Complete</td><td><pre><code>[#{고객사명}] 상품Q&#x26;A 답변완료 안내 고객님께서 문의하신 내용에 대한 답변이 완료되었습니다. ※ 고객센터 #{고객센터전화번호}(유료)
</code></pre></td><td>type : WL name : 상품Q&#x26;A 문의 답변 확인</td></tr><tr><td>2</td><td>PO2A</td><td>Order Complete</td><td><pre><code>[#{고객사명}] 주문완료 안내 #{고객명} 고객님의 주문이 완료되었습니다. ■ 주문정보 - 주문번호 : #{주문번호} - 주문일 : #{주문일} - 상품명 : #{상품명외N건(수량)개} - 결제금액 : #{결제금액}원 - 배송지 : #{배송지} ※ 고객센터 #{고객센터전화번호}(유료)
</code></pre></td><td>type : WL name : 주문상세 보기</td></tr><tr><td>3</td><td>PO2B</td><td>Delivery Started</td><td><pre><code>[#{고객사명}] 배송시작 안내 #{고객명} 고객님께서 주문하신 상품의 배송이 공 시작됩니다. ■ 주문상품 정보 - 주문번호 : #{주문번호} - 상품명 : #{상품명외N건(수량)개} ※ 고객센터 #{고객센터전화번호}(유료)
</code></pre></td><td>type : WL name : 주문상세 보기</td></tr><tr><td>4</td><td>PO2C</td><td>Delivery Delayed</td><td><pre><code>[#{고객사명}] 배송지연 안내 #{고객명} 고객님께서 주문하신 상품의 배송이 지연되고 있습니다. 불편을 드려 죄송합니다. 빠른시간 내 상품확보를 위해 최선을 다하겠습니다. 상품 수급이 불가하거나 장기화될 시 취소 안내를 드릴 수도 있습니다. ■ 주문상품 정보 - 주문번호 : #{주문번호} - 상품명 : #{상품명외N건(수량)개} 주문취소를 원하시는 경우, 고객센터로 연락 바랍니다. ※ 고객센터 #{고객센터전화번호}(유료)
</code></pre></td><td>type : WL name : 주문상세 보기</td></tr><tr><td>5</td><td>PO2D</td><td>Order Canceled</td><td><pre><code>[#{고객사명}] 주문취소 안내 고객님의 주문(#{주문번호})이 취소되었습니다. ■ 주문 취소정보 - 주문번호 : #{주문번호} - 상품명 : #{상품명외N건(수량)개} - 환불금액 : #{환불금액} ※ 고객센터 #{고객센터전화번호}(유료)
</code></pre></td><td>type : WL name : 주문상세 보기</td></tr><tr><td>6</td><td>PO2E</td><td>Exchange Received (Additional Shipping Fee Payment Request)</td><td><pre><code>[#{고객사명}] 교환배송비 결제 안내 #{고객명} 고객님께서 신청하신 교환이 접수되었습니다. 마이페이지에서 추가 배송비를 결제하신 후에 교환이 시작됩니다. ■ 교환 주문정보 - 주문번호 : #{주문번호} - 상품명 : #{상품명외N건(수량)개} - 교환 옵션 : #{컴러,사이즈} → #{컴러,사이즈} - 추가 배송비: #{추가배송비} 교환 요청하신 상품은 고객사에 수거된 후, 새 상품이 출고됩니다. (상품 불량, 재고 부족 등의 이슈로 교환이 진행되지 않을 수 있는 점 양해 부탁드립니다.) 수거부터 교환 배송까지는 약 7일 정도 소요되며, 수거가 지연될 경우 고객사 고객센터로 문의 부탁드립니다. ※ 고객센터 #{고객센터전화번호}(유료)
</code></pre></td><td>type : WL name : 주문상세 보기</td></tr><tr><td>7</td><td>PO2F</td><td>Exchange Received</td><td><pre><code>[#{고객사명}] 교환접수 안내 #{고객명} 고객님께서 신청하신 교환이 접수되었습니다. ■ 교환 주문정보 - 주문번호 : #{주문번호} - 상품명 : #{상품명외N건(수량)개} - 교환 옵션 : #{컴러,사이즈} → #{컴러,사이즈} 교환 요청하신 상품은 고객사에 수거된 후, 새 상품이 출고됩니다. (상품 불량, 재고 부족 등의 이슈로 교환이 진행되지 않을 수 있는 점 양해 부탁드립니다.) 수거부터 교환 배송까지는 약 7일 정도 소요되며, 수거가 지연될 경우 고객사 고객센터로 문의 부탁드립니다. ※ 고객센터 #{고객센터전화번호}(유료)
</code></pre></td><td>type : WL name : 주문상세 보기</td></tr><tr><td>8</td><td>PO2G</td><td>Exchange Delivery Started</td><td><pre><code>[#{고객사명}] 교환 배송시작 안내 #{고객명} 고객님께서 신청하신 교환 상품의 배송이 공 시작됩니다. ■ 교환상품 정보 - 주문번호 : #{주문번호} - 상품명(수량) : #{상품명(수량)} ※ 고객센터 #{고객센터전화번호}(유료)
</code></pre></td><td>type : WL name : 주문상세 보기</td></tr><tr><td>9</td><td>PO2H</td><td>Return Received</td><td><pre><code>[#{고객사명}] 반품접수 안내 #{고객명} 고객님께서 신청하신 반품이 접수되었습니다. ■ 반품 주문정보 - 주문번호 : #{주문번호} - 상품명 : #{상품명외N건(수량)개} 반품 수거는 평일 기준 2~3일 내에 배송 받으신 택배사 기사님을 통해 수거될 예정입니다. ※ 고객센터 #{고객센터전화번호}(유료)
</code></pre></td><td>type : WL name : 주문상세 보기</td></tr><tr><td>10</td><td>PO2I</td><td>Return Received (Additional Shipping Fee Payment Request)</td><td><pre><code>[#{고객사명}] 반품 배송비 결제 안내 #{고객명} 고객님께서 신청하신 반품이 접수되었습니다. 마이페이지에서 추가 배송비를 결제하신 후에 교환이 시작됩니다. ■ 반품 주문정보 - 주문번호 : #{주문번호} - 상품명 : #{상품명외N건(수량)개} - 추가 배송비: #{추가배송비} 반품 수거는 평일 기준 2~3일 내에 배송 받으신 택배사 기사님을 통해 수거될 예정입니다. ※ 고객센터 #{고객센터전화번호}(유료)
</code></pre></td><td>type : WL name : 주문상세 보기</td></tr><tr><td>11</td><td>PO2J</td><td>Return Complete</td><td><pre><code>[#{고객사명}] 반품완료 안내 #{고객명} 고객님께서 신청하신 반품이 완료되었습니다. 반품완료일을 기준으로 카드환불은 평일 35일 후 처리되며, 정확한 날짜는 카드사별로 상이합니다. 실시간 계좌이체의 경우, 평일 12일 후(오후 6시 전후) 환불됩니다. ■ 반품정보 - 주문번호 : #{주문번호} - 상품명 : #{상품명외N건(수량)개} - 환불금액 : #{환불금액} 배송비 등 차감으로 인해 환불금액이 상이할 수 있으며, 보다 자세한 내용은 환불내역을 확인 부탁드립니다. ※ 고객센터 #{고객센터전화번호}(유료)
</code></pre></td><td>type : WL name : 주문상세 보기</td></tr><tr><td>12</td><td>PO3A</td><td>Event Winner - Prize</td><td><pre><code>[#{고객사명}] 이벤트 당쎄 안내 #{고객명} 고객님, 이벤트 경품 당쎄을 축하 드립니다. 당쎄자 안내사항을 확인해 주세요. - 당쎄된 이벤트: #{이벤트명} - 당쎄 경품: #{당쎄경품명} - 경품 발송일: #{경품발송일} 당쎄된 경품은 이벤트 응모 시 입력한 주소지로 발송됩니다. #{경품발송일3일전날짜}까지 경품 수령지 주소를 확인/변경해 주세요. 경품 수령지 주소 변경: #{마이페이지참여내역} ※ 이 메시지는 고객님이 참여한 이벤트 당쎄으로 지급된 경품 안내 메시지입니다. ※ 당쎄된 경품의 제세공과금 22%는 당쎄자 본인 부담입니다. ※ 고객센터 #{고객센터전화번호}(유료)
</code></pre></td><td>type : WL name : 마이페이지 참여내역</td></tr><tr><td>13</td><td>PO2K</td><td>1:1 Inquiry Answer Complete</td><td><pre><code>[#{고객사명}] 1:1 문의 답변완료 안내 #{고객명} 고객님, 문의하신 내용에 대한 답변이 완료되었습니다. 1:1문의에서 답변을 확인해주세요. ※ 고객센터 #{0000-0000}(유료)
</code></pre></td><td>type : WL name : 1:1문의 답변 확인</td></tr><tr><td>14</td><td>PO3B</td><td>Scheduled for Dormant Account Conversion</td><td><pre><code>[#{고객사명}] 1년 이상 미로그인 회원 휴면 계정 전환 예정 안내 안녕하세요, #{고객명} 고객님 고객사명은 「개인정보보호법 제 39조 6」에 따라 최근 1년간 고객사명에 로그인하지 않으신 고객님의 개인정보를 보호하기 위해, 다음과 같이 고객님 계정 정보를 휴면 상태로 전환할 예정임을 안내드립니다. 휴면전환 계정 : #{ID} 휴면전환 예정 일자 : #{휴면전환예정일} 개인정보 보호 대상 : 회원 가입 시 입력한 개인정보와 주문 시 입력한 개인정보(이름, 성별, 생년월일, 전화번호, 이메일, 주소 등) ※ 고객사명의 다양한 혜택을 계속해서 이용하시고자 하는 경우, #{휴면전환예정일-1일}까지 고객사명에 로그인하시면 계속 이용이 가능합니다. ※ 고객센터 #{0000-0000}(유료)
</code></pre></td><td></td></tr><tr><td>15</td><td>PO3C</td><td>Membership Registration</td><td><pre><code>[#{고객사명}] 회원가입완료 안내 #{고객명} 고객님, 회원 가입을 진심으로 감사드립니다. 앞으로도 많은 관심과 이용 부탁 드립니다. ※ 고객센터 #{0000-0000}(유료)
</code></pre></td><td></td></tr><tr><td>16</td><td>PO3D</td><td>Marketing Consent</td><td><pre><code>[#{고객사명}] 정기적 수신동의 안내 #{고객명} 고객님, 이 메시지는 정보통신망법에 따라 2년마다 발송되는 광고성 정보 수신동의 확인 메시지 입니다. 이전 수신동의일자 : #{YYYY}년 #{MM}월 #{DD}일 앞으로도 유익한 소식과 다양한 혜택으로 찾아밝겠습니다.
</code></pre></td><td></td></tr><tr><td>17</td><td>PO3E</td><td>Membership Withdrawal</td><td><pre><code>[#{고객사명}] 개인정보 파기 및 탈퇴 예정 안내 #{고객명} 고객님, 고객사명은 고객님의 탈퇴 요청에 따라 고객님의 개인정보를 보호하기 위해, 다음과 같이 개인정보 파기 및 탈퇴 처리가 진행될 예정입니다. 탈퇴 계정 : #{ID} 파기 대상 개인정보 : 이름, 성별, 생년월일, 전화번호, 이메일, 주소 등 ※ 개인정보 파기 및 탈퇴 이후에 서비스 이용을 원하시면, 신규 회원가입을 하셔야 합니다. ※ 본 메시지는 고객사명 온라인 쇼핑몰의 개인정보처리방침에 따라 발송된 메시지입니다. ※ 고객센터 #{0000-0000}(유료)
</code></pre></td><td></td></tr><tr><td>18</td><td>PO3F</td><td>Temporary Password Notice</td><td><pre><code>[#{고객사명}] 임시 비밀번호 안내 #{고객명}고객님의 임시 비밀번호는 [#{임시비밀번호}]입니다.
</code></pre></td><td></td></tr><tr><td>19</td><td>PO3G</td><td>Admin Verification Code Notice</td><td><pre><code>[#{고객사명}] 임시 비밀번호 안내 #{사용자명}님께서 요청하신 임시 비밀번호는 [#{인증번호}] 입니다.
</code></pre></td><td></td></tr></tbody></table>

(3) Set the parameters to be substituted for the #{...} in the template content to the corresponding variables of the VO used in the business logic.

* <mark style="color:red;">If the template variable (#{…}) name matches the VO's variable name, it will be replaced.</mark>
* <mark style="color:red;">The example's SendParams is not provided.</mark>

(4) Map the template content and the parameter list using the `replaceTemplateFormat` method of <kbd>MessageSender</kbd>.

(5), (6) Both links are required and must include **https\://**.

(9) If you are sending a KakaoTalk notification from a project other than `x2bee-api-common-vanilla`, call the api-common API.\
As shown in the example source, put the required parameters into a <kbd>BizMessageRequest</kbd> object and call the <kbd>/api/common/interface/bizmessage/sendalimtalk</kbd> endpoint using the POST method.

* <kbd>messages</kbd> and <kbd>templateCode</kbd> are required parameters.
* <kbd>commonApiUrl</kbd> is the URL specified in application.yml.

## Failover Configuration (When KakaoTalk Notification Sending Fails)

* Currently, the Failover setting for the X2BEE KakaoTalk channel is set to <mark style="color:red;">True</mark>, so <kbd>messages.useSmsFailover</kbd> is <mark style="color:red;">requested as true by default regardless of whether the variable is set</mark>.\
  Therefore, if you do not want to use Failover, you must set the <kbd>messages.useSmsFailover</kbd> variable to false.
* All parameters within <kbd>failoverConfig</kbd> are Optional; if not written, they are sent as described in the Notes column for each parameter below.
* <kbd>messages.failoverConfig.from</kbd> does not need to be written, as it is automatically registered with the sender number specified in the NCP Console.

<table><thead><tr><th width="172.5555419921875">Item</th><th width="120.1112060546875">Mandatory</th><th width="88.2222900390625">Type</th><th>Description</th><th>Notes</th></tr></thead><tbody><tr><td>plusFriendId</td><td>Mandatory</td><td>String</td><td>KakaoTalk channel name (formerly Plus Friend ID)</td><td></td></tr><tr><td>templateCode</td><td>Mandatory</td><td>String</td><td>Template code</td><td></td></tr><tr><td>messages</td><td>Mandatory</td><td>Object</td><td>Message information</td><td>- See items below (messages.XXX)<br>- Max 100</td></tr><tr><td>messages.useSmsFailover</td><td>Optional</td><td>Boolean</td><td>Whether to use SMS Failover</td><td>- Available only for KakaoTalk channels with Failover configured<br>- Default: follows the KakaoTalk channel's Failover setting</td></tr><tr><td>messages.failoverConfig</td><td>Optional</td><td>Object</td><td>Failover configuration</td><td>See items below</td></tr><tr><td>messages.failoverConfig.type</td><td>Optional</td><td>String</td><td>Failover SMS message Type</td><td>- SMS or LMS<br>- Default: automatically applied based on content length (90 bytes or less: SMS, over: LMS)</td></tr><tr><td>messages.failoverConfig.from</td><td>Optional</td><td>String</td><td>Failover SMS sender number</td><td>- Default: the sender number selected when Failover was configured<br>- Failover does not work if an unapproved sender number is used</td></tr><tr><td>messages.failoverConfig.subject</td><td>Optional</td><td>String</td><td>Failover SMS subject</td><td>- Used when operating as LMS type<br>- Default: KakaoTalk channel name</td></tr><tr><td>messages.failoverConfig.content</td><td>Optional</td><td>String</td><td>Failover SMS content</td><td>Default: KakaoTalk notification message content (excluding buttons)</td></tr></tbody></table>

***