# 알림톡

{% hint style="warning" %}
서비스를 이용하시려면 **\[서비스 콘솔 / 발신번호]**에서 **발신번호 등록**을 수행해야 합니다.
{% endhint %}

{% hint style="warning" %}
서비스를 이용하시려면 **\[서비스 콘솔 / 템플릿 관리]**에서 **신규 등록**을 수행해야 합니다.
{% endhint %}

{% hint style="info" %}
모든 알림톡 API의 인코딩은 UTF-8 을 기본으로 합니다.
{% endhint %}

{% hint style="success" %}
해당 API는 [메세지 발송 결과(WebHook)](/ko/service/kakao-message/webhook.md)으로 결과를 전달할 수 있습니다.
{% endhint %}

## 알림톡 API

### Path variable

{% hint style="warning" %}
Path variable(각 URI 내 중괄호({}) 로 묶인 경로 변수)는 아래 내용을 참고하여 호출 시 누락되지 않도록 해주세요.
{% endhint %}

<table><thead><tr><th width="192">code</th><th>설명</th></tr></thead><tbody><tr><td>service_id</td><td><p>서비스 유형 id</p><ul><li>at-standard : 스탠다드 알림톡</li><li>at-bulk : 대량 알림톡</li><li>at-finance : 금융 알림톡</li><li>at-verify : 인증 알림톡</li></ul></td></tr></tbody></table>

## Kakao 알림톡 API

<mark style="color:green;">`POST`</mark> `https://27ep4ci1w0.apigw.ntruss.com/{service_id}/v2/send`

#### Headers

| Name                                            | Type   | Description                    |
| ----------------------------------------------- | ------ | ------------------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | 사용자ID;secret\_key              |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json;charset=utf-8 |

#### Request Body

<table><thead><tr><th width="224">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>msg_type<mark style="color:red;">*</mark></td><td>string</td><td>메시지타입 ("AT" | “AI”) <br>AT: 알림톡 (<strong>강조유형</strong>이 <strong>이미지형</strong>을 <strong>제외</strong>한 모든 경우) <br>AI: 이미지 알림톡</td></tr><tr><td>msg_data<mark style="color:red;">*</mark></td><td>array</td><td>메시지 발송 상세 데이터 (최대 10건)</td></tr><tr><td>    sender_number<mark style="color:red;">*</mark></td><td>string</td><td>발신자 전화번호</td></tr><tr><td>    msg_key<mark style="color:red;">*</mark></td><td>string</td><td>사용자가 관리하는 메시지 고유 키 (null 또는 공백일 경우 자동 부여)</td></tr><tr><td>    header</td><td>string</td><td>메시지 상단 표기 제목 (16자)</td></tr><tr><td>    msg<mark style="color:red;">*</mark></td><td>string</td><td>전송 메시지 (공백 포함 1000자 제한)</td></tr><tr><td>    receiver_number<mark style="color:red;">*</mark></td><td>string</td><td>수신자 휴대폰 번호</td></tr><tr><td>    title</td><td>string</td><td>알림톡 강조 정보 (50자)</td></tr><tr><td>    template_code<mark style="color:red;">*</mark></td><td>string</td><td>알림톡 템플릿 코드 <br><mark style="color:purple;"><strong>[서비스 콘솔 / 템플릿 관리]에서 등록 필요</strong></mark></td></tr><tr><td>    sender_key<mark style="color:red;">*</mark></td><td>string</td><td>카카오 비즈메시지 발신 프로필키 <br><mark style="color:purple;"><strong>[서비스 콘솔 / 발신프로필 등록] 에서 등록 필요</strong></mark></td></tr><tr><td>    currency_type</td><td>string</td><td><p>모먼트 광고 전환 최적화 전용 message 내 포함된 가격/금액/결제금액의 통화단위</p><p>KRW, USD, EUR 등 국제 통화 코드 사용</p></td></tr><tr><td>    price</td><td>number</td><td>메시지내 포함된 가격정보</td></tr><tr><td>    attachment</td><td>object</td><td><p>버튼 혹은 이미지 데이터</p><p>(<a href="#attachment">attachment 상세</a> 참조)</p></td></tr><tr><td>    supplement</td><td>object</td><td>링크 바로연결 데이터<br>(<a href="#supplement">supplement 상세</a> 참조)</td></tr><tr><td>    echo_to_webhook</td><td>string</td><td>사용자가 API PLEX로부터 webhook을 받을 때 함께 받을 string (최대 256 byte)</td></tr><tr><td>    failback_data</td><td>object</td><td>발송 실패 시 대체 발송 데이터</td></tr><tr><td>        api_unique_id</td><td>string</td><td><p>failback service의 고유 id (failback 사용 시 필수)</p><p>(<a href="/pages/hMQ4qMBObS8s2sC3zo8Z">failback</a> 참조)</p></td></tr><tr><td>        secret_key</td><td>string</td><td>failback service의 sub_account의 secret_key ( failback 사용 시 필수)</td></tr><tr><td></td><td>String</td><td>failback service의 본문에서 사용할 payload 해당 service의 본문에서 필요로 하는 내용을 기재 (<a href="#request-body-1">예시</a> 참조)</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK 응답 반환 완료" %}

{% endtab %}
{% endtabs %}

###

### attachment 상세

<table data-full-width="false"><thead><tr><th width="204">키</th><th width="128">타입</th><th width="70" align="center">필수</th><th>설명</th></tr></thead><tbody><tr><td>button</td><td>array</td><td align="center">N</td><td>버튼 속성 데이터 (최대 5개)</td></tr><tr><td>    name</td><td>string</td><td align="center">Y</td><td>버튼 제목 (14자)</td></tr><tr><td>    type</td><td>string</td><td align="center">Y</td><td>버튼 타입 (하단 <a href="#undefined-2"><strong>버튼 타입</strong></a> 참조)</td></tr><tr><td>    url_pc</td><td>string</td><td align="center">N</td><td>PC환경에서 버튼 클릭 시 이동할 URL</td></tr><tr><td>    url_mobile</td><td>string</td><td align="center">N</td><td>Mobile 환경에서 버튼 클릭 시 이동할 URL</td></tr><tr><td>    scheme_android</td><td>string</td><td align="center">N</td><td>Mobile android 환경에서 버튼 클릭 시 실행할 Application custom scheme</td></tr><tr><td>    scheme_ios</td><td>string</td><td align="center">N</td><td>Mobile ios환경에서 버튼 클릭 시 실행 할 Application custom scheme</td></tr><tr><td>    chat_extra</td><td>string</td><td align="center">N</td><td>봇 전환 시 전달할 메타정보 (50자)</td></tr><tr><td>    chat_event</td><td>string</td><td align="center">N</td><td>봇 전환 시 연결할 봇 이벤트명 (50자)</td></tr><tr><td>item_highlight</td><td>object</td><td align="center">N</td><td>아이템 하이라이트</td></tr><tr><td>    title</td><td>string</td><td align="center">Y</td><td>타이틀 (30자, 이미지가 있는 경우 최대 21자)</td></tr><tr><td>    description</td><td>string</td><td align="center">Y</td><td>부가정보 (19자, 이미지가 있는 경우 최대 13자)</td></tr><tr><td>item</td><td>object</td><td align="center">N</td><td>아이템 리스트와 아이템 요약 정보</td></tr><tr><td>    list</td><td>array</td><td align="center">Y</td><td>아이템 리스트</td></tr><tr><td>        title</td><td>string</td><td align="center">Y</td><td>타이틀 (6자)</td></tr><tr><td>        description</td><td>string</td><td align="center">Y</td><td>가격 정보 (23자)</td></tr><tr><td>    summary</td><td>object</td><td align="center">N</td><td>아이템 요약 정보</td></tr><tr><td>        title</td><td>string</td><td align="center">Y</td><td>타이틀 (6자)</td></tr><tr><td>        description</td><td>string</td><td align="center">Y</td><td>가격 정보 (14자)</td></tr></tbody></table>

### supplement 상세

<table data-full-width="false"><thead><tr><th width="213">키</th><th width="128">타입</th><th width="68" align="center">필수</th><th>설명</th></tr></thead><tbody><tr><td>quick_reply</td><td>array</td><td align="center">N</td><td>바로 연결 목록</td></tr><tr><td>    name</td><td>string</td><td align="center">Y</td><td>바로 연결 제목 (14자)</td></tr><tr><td>    type</td><td>string</td><td align="center">Y</td><td>바로 연결 타입 (하단 <a href="#undefined-3"><strong>바로연결 타입</strong></a> 참조)</td></tr><tr><td>    scheme_android</td><td>string</td><td align="center">N</td><td>Mobile android 환경에서 버튼 클릭 시 실행할 Application custom scheme</td></tr><tr><td>    scheme_ios</td><td>string</td><td align="center">N</td><td>Mobile ios환경에서 버튼 클릭 시 실행 할 Application custom scheme</td></tr><tr><td>    url_mobile</td><td>string</td><td align="center">N</td><td>Mobile 환경에서 버튼 클릭 시 이동할 URL</td></tr><tr><td>    url_pc</td><td>string</td><td align="center">N</td><td>PC환경에서 버튼 클릭 시 이동할 URL</td></tr><tr><td>    chat_extra</td><td>string</td><td align="center">N</td><td>봇 전환 시 전달할 메타 정보 (200 byte)</td></tr><tr><td>    chat_event</td><td>string</td><td align="center">N</td><td>봇 전환 시 연결할 봇 이벤트 명 (200 byte)</td></tr></tbody></table>

### 버튼 타입

<table data-full-width="false"><thead><tr><th width="121">버튼타입</th><th width="157">속성</th><th width="86">타입</th><th width="67" align="center">필수</th><th>설명</th></tr></thead><tbody><tr><td>WL</td><td>url_mobile</td><td>string</td><td align="center">Y</td><td>[웹링크]<br>바로 연결 클릭 시 이동할 pc/mobile 환경별 web url</td></tr><tr><td></td><td>url_pc</td><td>string</td><td align="center">N</td><td>위와 동일</td></tr><tr><td>AL</td><td>scheme_android</td><td>string</td><td align="center">Y</td><td><p></p><p>[앱링크] scheme_ios, scheme_android, url_mobile 중 2가지 필수 입력</p><ul><li>mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme</li><li>mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme</li><li>mobile 환경에서 버튼 클릭 시 이동할 url</li></ul></td></tr><tr><td></td><td>scheme_ios</td><td>string</td><td align="center">Y</td><td>위와 동일</td></tr><tr><td></td><td>url_mobile</td><td>string</td><td align="center">Y</td><td>위와 동일</td></tr><tr><td></td><td>url_pc</td><td>string</td><td align="center">-</td><td>pc 환경에서 버튼 클릭 시 이동할 url</td></tr><tr><td>DS</td><td>-</td><td>-</td><td align="center">-</td><td>버튼 클릭 시 배송조회 페이지로 이동</td></tr><tr><td>BK</td><td>-</td><td>-</td><td align="center">-</td><td>해당 버튼 텍스트 전송</td></tr><tr><td>MD</td><td>-</td><td>-</td><td align="center">-</td><td>해당 버튼 텍스트 + 메시지 본문 전송</td></tr><tr><td>BC</td><td>-</td><td>-</td><td align="center">-</td><td>상담톡을 이용하는 카카오톡 채널만 이용가능</td></tr><tr><td></td><td>chat_extra</td><td>string</td><td align="center">N</td><td>상담톡 전환 시 전달할 메타정보</td></tr><tr><td>BT</td><td>-</td><td>-</td><td align="center">-</td><td>카카오 I 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용가능</td></tr><tr><td></td><td>chat_extra</td><td>string</td><td align="center">N</td><td>봇 전환 시 전달할 메타정보</td></tr><tr><td></td><td>chat_event</td><td>string</td><td align="center">N</td><td>봇 전환 시 연결할 봇 이벤트명</td></tr><tr><td>AC</td><td>-</td><td>-</td><td align="center">-</td><td>버튼 클릭 시 카카오톡 채널 추가</td></tr><tr><td>P1</td><td>-</td><td>-</td><td align="center">-</td><td>이미지 보안 전송 플러그인</td></tr><tr><td>P2</td><td>-</td><td>-</td><td align="center">-</td><td>개인정보이용 플러그인</td></tr><tr><td>P3</td><td>-</td><td>-</td><td align="center">-</td><td>원클릭 결제 플러그인<br>(발송시 oneclick_id 또는 product_id를 필수로 전달해아 함)</td></tr></tbody></table>

### 바로 연결 타입

<table data-full-width="false"><thead><tr><th width="119.19999999999999">버튼타입</th><th width="158">속성</th><th width="93">타입</th><th width="65" align="center">필수</th><th>설명</th></tr></thead><tbody><tr><td>WL</td><td>url_mobile</td><td>string</td><td align="center">Y</td><td>[웹링크]<br>바로연결 클릭 시 이동할 pc/mobile 환경별 web url</td></tr><tr><td></td><td>url_pc</td><td>string</td><td align="center">N</td><td>위와 동일</td></tr><tr><td>AL</td><td>scheme_android</td><td>string</td><td align="center">Y</td><td><p></p><p>[앱링크] scheme_ios, scheme_android, url_mobile 중 2가지 필수 입력</p><ul><li>mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme</li><li>mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme</li><li>mobile 환경에서 버튼 클릭 시 이동할 url</li></ul></td></tr><tr><td></td><td>scheme_ios</td><td>string</td><td align="center">Y</td><td>위와 동일</td></tr><tr><td></td><td>url_mobile</td><td>string</td><td align="center">Y</td><td>위와 동일</td></tr><tr><td></td><td>url_pc</td><td>string</td><td align="center">-</td><td>pc 환경에서 버튼 클릭 시 이동할 url</td></tr><tr><td>BK</td><td>-</td><td>-</td><td align="center">-</td><td>해당 버튼 텍스트 전송</td></tr><tr><td>MD</td><td>-</td><td>-</td><td align="center">-</td><td>해당 버튼 텍스트 + 메시지 본문 전송</td></tr><tr><td>BC</td><td>-</td><td>-</td><td align="center">-</td><td>상담톡을 이용하는 카카오톡 채널만 이용가능</td></tr><tr><td></td><td>chat_extra</td><td>string</td><td align="center">N</td><td>상담톡 전환 시 전달할 메타정보</td></tr><tr><td>BT</td><td>-</td><td>-</td><td align="center">-</td><td>카카오 I 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용가능</td></tr><tr><td></td><td>chat_extra</td><td>string</td><td align="center">N</td><td>봇 전환 시 전달할 메타정보</td></tr><tr><td></td><td>chat_event</td><td>string</td><td align="center">N</td><td>봇 전환 시 연결할 봇 이벤트명</td></tr></tbody></table>

### Request Body 예시

```json
{
    "msg_type": "AT",
    "msg_data": [
        {
            "msg_key": "user_key_1",
            "sender_number": "010xxxxxxxx",
            "receiver_number": "010xxxxxxxx",
            "msg": "기본형 선택안함 TEST 메세지 입니다.",
            "sender_key": "user_sender_key_001",
            "template_code": "user_template_code_001"
        },
        {
            "msg_key": "",
            "sender_number": "010xxxxxxxx",
            "receiver_number": "010xxxxxxxx",
            "title": "강조표기 테스트 제목입니다.",
            "msg": "강조표기 테스트 본문입니다.",
            "sender_key": "user_sender_key_001",
            "template_code": "user_template_code_002",
            "attachment": {
                "button": [
                    {
                        "name": "강조표기",
                        "type": "WL",
                        "url_pc": "https://www.apiplex.net",
                        "url_mobile": "https://m.apiplex.net"
                    }
                ]
            },
            "echo_to_webhook": "echo test",
            "failback_data": {
                "api_unique_id": "sms-standard",
                "secret_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "sender_number": "010xxxxxxxx",
                "receiver_number": "010xxxxxxxx",
                "origin_cid": "0123456789",
                "msg": "failback 본문입니다."
            }
        }
    ]
}
```

### Response Body

{% hint style="info" %}
응답 http status가 200으로 return되어도 모든 요청의 정상 접수를 의미하지 않습니다.

(발송 건 별 접수 결과 코드(code 필드)로 정상 접수 여부를 확인할 수 있습니다.)
{% endhint %}

```json
{
    "results": [
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "user_key_1"
        },
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "11520199-f289-4681-b0e3-354393a4b041"
        }
    ]
}
```

<table><thead><tr><th width="104">키</th><th width="110"> </th><th width="126">타입</th><th>설명</th></tr></thead><tbody><tr><td>results</td><td></td><td>array</td><td>메시지 수신 데이터</td></tr><tr><td> </td><td>msg_key</td><td>string</td><td>메시지 고유 키</td></tr><tr><td> </td><td>code</td><td>string</td><td>접수 결과 코드 (문서 하단 <a href="#api-plex"><strong>API PLEX 응답 코드</strong></a> 참조)</td></tr><tr><td> </td><td>desc</td><td>string</td><td>접수 결과 코드 상세</td></tr></tbody></table>

**잘못된 요청 또는 에러**

```json
{
    "code": "C400_2",
    "name": "Invalid Parameter",
    "description": "사용자 인증 실패"
}
```

**잘못된 list 내부 요청**

```json
{
    "results": [
        {
            "code": "G141",
            "desc": "수신번호 예외",
            "msg_key": "user_key_101"
        },
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "0e826855-299f-4328-82a1-d33720dcca23"
        }
    ]
}
```

### **API PLEX 응답 코드**

| code    | 설명                         | 상세 설명                         |
| ------- | -------------------------- | ----------------------------- |
| C100    | 성공                         |                               |
| C400\_1 | 잘못된 데이터 타입                 | response body의 description 참조 |
| C400\_2 | 잘못된 요청 파라미터                | response body의 description 참조 |
| C400\_3 | 필수 파라미터 누락                 | response body의 description 참조 |
| C404\_1 | 데이터를 찾을 수 없음               | response body의 description 참조 |
| C500\_1 | 서버 내부 에러                   | response body의 description 참조 |
| G110    | API UNIQUE ID 예외 (잘못된 URL) |                               |
| G140    | 발신번호 예외                    |                               |
| G141    | 수신번호 예외                    |                               |
| G142    | 잘못된 echo\_to\_webhook      | 256 byte 초과 또는 type error     |
| G150    | 여신 부족                      |                               |
| G160    | 1회 발송 최대 수 초과              |                               |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.apiplex.net/ko/service/kakao-message/kakao-alim-talk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.