# 카카오 알림톡 발송 API

## 사전 작업 <a href="#pre-work" id="pre-work"></a>

### 토큰 발급 <a href="#token" id="token"></a>

서버에서 발송API를 요청하기 전, 먼저 프로젝트에 유효한 토큰을 발급받아 주세요.

{% content-ref url="../authentication" %}
[authentication](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/open-api/authentication)
{% endcontent-ref %}

### 채널 설정 <a href="#channel" id="channel"></a>

* 발신 프로필 등록 및 템플릿 심사를 모두 완료해야 합니다.
* 콘솔 경로:

  * 발신 프로필 등록: \[마켓탭 콘솔 > 채널 관리 > 카카오톡 ]

  <figure><img src="https://content.gitbook.com/content/TQoY0rYrzNUQxhlUfYFm/blobs/dvaQD3mqKWVUP4XqEpiw/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-03-31%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.53.17.png" alt="" width="563"><figcaption></figcaption></figure>

  * 템플릿 등록: \[마켓탭 콘솔 > 채널 관리 > 템플릿 관리]

    <figure><img src="https://content.gitbook.com/content/TQoY0rYrzNUQxhlUfYFm/blobs/geKRApxPwVsTFNm6oB93/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-03-31%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.53.42.png" alt="" width="563"><figcaption></figcaption></figure>

## 카카오 알림톡 발송 API

**Method**: `POST`

**Content-Type**: `application/json`

```json
[
  {
    "sender_profile_id": "a2i3lnl",
    "phone_number": "01000000000",
    "campaign_id": "sender_api_campaign",
    "user_id": "sender_api_user_id",
    "alimtalk_fields": [
      {
        "name": "고객",
        "value": "회원"
      },
      {
        "name": "상품명",
        "value": "가방"
      },
      {
        "name": "택배사",
        "value": "test"
      },
      {
        "name": "운송장번호",
        "value": "11010101010"
      },
      {
        "name": "주문번호",
        "value": "11010101010"
      }
    ],
    "template_id": "ekf1h3o"
  }
]
```

### Payload 필드 설명

<table><thead><tr><th width="211.74737548828125">필드명</th><th width="452.4539794921875">설명</th><th>필수 여부</th></tr></thead><tbody><tr><td><code>sender_profile_id</code></td><td>카카오 발신 프로필 ID</td><td><mark style="color:red;">required</mark></td></tr><tr><td><code>campaign_id</code></td><td>메세지 발송 결과를 캠페인 ID 단위로 확인하고 싶을 때 사용하실 수 있습니다.</td><td></td></tr><tr><td><code>user_id</code></td><td>메세지 발송 결과를 확인할 유저 ID</td><td><mark style="color:red;">required</mark></td></tr><tr><td><code>phone_number</code></td><td>발송 대상 전화 번호 ( ex <code>01012345678</code> )</td><td><mark style="color:red;">required</mark></td></tr><tr><td><code>template_id</code></td><td>알림톡 템플릿 ID</td><td><mark style="color:red;">required</mark></td></tr><tr><td><code>alimtalk_fields</code></td><td>알림톡 템플릿 내 카카오 개인화 속성</td><td></td></tr></tbody></table>

* 카카오 개인화 (alimtalk\_fileds) 관련

  * 템플릿에서 사용하는 변수명은 콘솔 > 템플릿 상세화면에서 확인 가능합니다.&#x20;
    * 템플릿 상세 > 본문 영역 #{} 으로 표시된 개인화 필드를 참고해주세요.
  * 모든 필드명이 템플릿에 정의된 이름과 정확히 일치해야 하며, 누락되거나 타입 불일치 시 400 에러 반환됩니다.

  <div><figure><img src="https://content.gitbook.com/content/TQoY0rYrzNUQxhlUfYFm/blobs/ORbI3KyVH3nRrMqwxdTL/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-03-31%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%206.06.13.png" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="https://content.gitbook.com/content/TQoY0rYrzNUQxhlUfYFm/blobs/CEdcKs6F7vuzaHgQsVZR/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-03-31%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%206.06.49.png" alt="" width="563"><figcaption></figcaption></figure></div>

### 주의사항 및 기타 안내 <a href="#notifications" id="notifications"></a>

* 발송 API는 실시간으로 처리되며, 요청당 최대 100개의 전화번호로 발송이 가능합니다.
* 수신 번호가 유효하지 않거나 템플릿이 승인되지 않은 경우 실패 응답이 반환됩니다.
* 묶음 발송인 경우 **병렬처리가 아닌 순차적 발송**으로 단건 발송에 비해 응답 속도가 느릴수 있는점 참고 부탁드립니다.
* 트래픽 집중 시간대에는 발송이 지연될 수 있습니다.

## Open API 스펙

## Send a Kakao Alimtalk message

> Sends a Kakao Alimtalk message using a registered template.

```json
{"openapi":"3.0.0","info":{"title":"Marketap Message API","version":"1.0.0"},"servers":[{"url":"https://crm.marketap.io","description":"Production Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SendAlimTalkMessageReq":{"type":"object","required":["phone_number","template_id","sender_profile_id","user_id"],"properties":{"phone_number":{"type":"string"},"template_id":{"type":"string"},"sender_profile_id":{"type":"string"},"campaign_id":{"type":"string"},"user_id":{"type":"string"},"alimTalk_fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"tracking_options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"redirect_url":{"type":"string","format":"uri"}}}}}},"SenderResponse":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/SendMessageResult"}}}},"SendMessageResult":{"type":"object","properties":{"message_id":{"type":"string"},"user_id":{"type":"string"},"phone_number":{"type":"string"},"status":{"type":"integer"},"message":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}},"paths":{"/api/v1/sender/kakao-alimtalk":{"post":{"summary":"Send a Kakao Alimtalk message","description":"Sends a Kakao Alimtalk message using a registered template.","operationId":"sendAlimTalkMessage","parameters":[{"name":"project_id","in":"query","required":true,"schema":{"type":"string"},"description":"프로젝트 ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SendAlimTalkMessageReq"}}}}},"responses":{"200":{"description":"The request has been accepted for processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SenderResponse"}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```