# 카카오 브랜드 메세지 발송 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://260547158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTQoY0rYrzNUQxhlUfYFm%2Fuploads%2FT5E5Pe2KhDHk5FVsqLCf%2F%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-10-15%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%2011.45.20.png?alt=media&#x26;token=5c679d53-6ec1-4eab-a282-47be8182a4be" 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",
    "template_id": "abecde", 
    "target_group": "I",
    "brand_message_fields": {}
  }
]
```

### 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>target_group</code></td><td><a href="#m-n-i">브랜드 메시지 대상자 그룹 ( M,N, I ) </a></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>brand_message_fields</code></td><td>브랜드 메세지 템플릿 내 카카오 개인화 속성<br>자세한 사항은 <a href="#brand_message_fields">브랜드 메세지 개인화 필드</a> 를 참고해주세요.</td><td></td></tr><tr><td><p></p><p><code>override_image_fields</code></p></td><td>브랜드 메시지 템플릿에서 사용한 이미지 외에 다른 이미지 첨부시 사용</td><td></td></tr></tbody></table>

#### 브랜드 메시지 대상자 그룹 ( M,N, I )&#x20;

<figure><img src="https://260547158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTQoY0rYrzNUQxhlUfYFm%2Fuploads%2F1IkolxPB2mex7gEr5bgU%2F%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-10-14%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.30.59.png?alt=media&#x26;token=970f02d4-8bd4-4cc7-a3e5-bea5d3586f96" alt=""><figcaption></figcaption></figure>

#### 카카오 개인화 (brand\_message\_fields) 관련

* 템플릿에서 사용하는 변수명은 콘솔 및[ 브랜드 메시지 개인화 필드 조회 API](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/open-api/api/fields#id-3.-api)를 통해 확인 가능합니다.&#x20;
  * 콘솔 > 템플릿 상세 > 본문 영역 #{} 으로 표시된 개인화 필드를 참고해주세요.
* 모든 필드명이 템플릿에 정의된 이름과 정확히 일치해야 하며, 누락되거나 타입 불일치 시 400 에러 반환됩니다.

  <figure><img src="https://260547158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTQoY0rYrzNUQxhlUfYFm%2Fuploads%2FiHhdBNLnE4o9gUDUUUGx%2F%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-10-15%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%2011.54.46.png?alt=media&#x26;token=676e45c4-7628-41ab-9aee-ee33b9772840" alt="" width="563"><figcaption></figcaption></figure>

### 재정의 이미지 (override\_image\_fields) 관련  <a href="#notifications" id="notifications"></a>

* 브랜드 메시지 템플릿에 정의된 이미지 대신 다른 이미지를 사용하고자 할 때 설정하는 필드입니다.
* 템플릿에 포함된 이미지의 개수만큼 배열 요소를 정의해야 합니다.
* 변경하지 않을 이미지는 **빈 객체(`{}`)** 로 유지합니다.
* 변경할 이미지는 **`image_url`** 필드에 새 이미지 URL을 입력합니다.

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

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

## Open API 스펙

## 카카오 브랜드 메시지 발송

> 지정한 프로젝트의 템플릿 ID와 개인화 필드 정보를 이용해   카카오 브랜드 메시지를 \<strong>여러 사용자에게 일괄 발송\</strong>합니다.   캠페인 ID를 지정하면 발송 내역이 분석 지표와 연결됩니다.<br>

```json
{"openapi":"3.0.3","info":{"title":"Marketap 카카오 브랜드 메시지 발송 API","version":"1.0.0"},"security":[{"bearerAuth":[]}],"paths":{"https://crm.marketap.io/api/v1/sender/kakao-brand-message":{"post":{"summary":"카카오 브랜드 메시지 발송","description":"지정한 프로젝트의 템플릿 ID와 개인화 필드 정보를 이용해   카카오 브랜드 메시지를 <strong>여러 사용자에게 일괄 발송</strong>합니다.   캠페인 ID를 지정하면 발송 내역이 분석 지표와 연결됩니다.\n","parameters":[{"name":"project_id","in":"query","required":true,"description":"프로젝트 ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","description":"브랜드 메시지 발송 요청 목록","items":{"$ref":"#/components/schemas/SendBrandMessageReq"}}}}},"responses":{"200":{"description":"발송 요청 성공","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"발송 결과 리스트","items":{"type":"object","properties":{"message_id":{"type":"string","description":"메시지 요청 식별자"},"user_id":{"type":"string","description":"수신자 사용자 ID"},"phone_number":{"type":"string","description":"수신자 전화번호"},"status":{"type":"integer","description":"결과 코드 (200000 성공)"},"message":{"type":"string","description":"결과 메시지"}}}},"code":{"type":"integer"},"message":{"type":"string"}}}}}},"400":{"description":"잘못된 요청 (필수 필드 누락 등)"},"401":{"description":"인증 실패 (토큰 누락 또는 만료)"},"500":{"description":"내부 서버 오류"}}}}},"components":{"schemas":{"SendBrandMessageReq":{"type":"object","required":["sender_profile_id","user_id","phone_number","target_group","template_id"],"properties":{"campaign_id":{"type":"string","nullable":true,"description":"캠페인 ID (선택)"},"sender_profile_id":{"type":"string","description":"카카오 발신 프로필 ID"},"user_id":{"type":"string","description":"사용자 식별자"},"phone_number":{"type":"string","description":"수신자 전화번호"},"target_group":{"type":"string","description":"메시지 발송 대상 그룹","enum":["M","N","I"]},"template_id":{"type":"string","description":"발송에 사용할 브랜드 메시지 템플릿 ID"},"brand_message_fields":{"$ref":"#/components/schemas/BrandMessageFields"},"override_image_fields":{"type":"array","nullable":true,"description":"템플릿에 정의된 이미지 대신 다른 이미지를 사용하고 싶을 때 지정합니다.   템플릿 내 이미지 개수와 동일한 길이의 배열을 전달해야 하며,   변경하지 않을 이미지는 빈 객체 `{}` 로 남깁니다.\n","items":{"$ref":"#/components/schemas/ImageVariable"}}}},"BrandMessageFields":{"type":"object","description":"브랜드 메시지 템플릿의 개인화 필드 정보","properties":{"content":{"type":"object","additionalProperties":{"type":"string"},"description":"본문, 헤더, 부가정보 등 텍스트 및 콘텐츠 영역"},"coupon":{"$ref":"#/components/schemas/CouponPersonalizeField"},"buttons":{"type":"object","additionalProperties":{"type":"string"},"description":"버튼별 URL 및 텍스트"},"commerce":{"$ref":"#/components/schemas/CommercePersonalizeField"},"carousel_commerce":{"type":"array","description":"캐러셀 커머스형 콘텐츠 리스트","items":{"$ref":"#/components/schemas/CarouselCommercePersonalizeField"}},"carousel":{"type":"array","description":"캐러셀 피드 콘텐츠 리스트","items":{"$ref":"#/components/schemas/CarouselPersonalizeField"}}}},"CouponPersonalizeField":{"type":"object","description":"쿠폰 영역의 개인화 필드","properties":{"title":{"type":"object","additionalProperties":{"type":"string"},"description":"쿠폰 할"},"common":{"type":"object","additionalProperties":{"type":"string"},"description":"쿠폰 설명 및 URL 영역"}}},"CommercePersonalizeField":{"type":"object","description":"커머스형 메시지의 개인화 필드","properties":{"content":{"type":"object","additionalProperties":{"type":"string"}},"product_name":{"type":"object","additionalProperties":{"type":"string"},"description":"상품명"},"price":{"$ref":"#/components/schemas/CommercePricePersonalize"}}},"CommercePricePersonalize":{"type":"object","description":"커머스 가격 관련 개인화 필드","properties":{"regular_price":{"type":"object","additionalProperties":{"type":"string"},"description":"정상가"},"discount_price":{"type":"object","additionalProperties":{"type":"string"},"description":"할인가"},"discount_rate":{"type":"object","additionalProperties":{"type":"string"},"description":"할인율"},"discount_fixed":{"type":"object","additionalProperties":{"type":"string"},"description":"정액할인가"}}},"CarouselCommercePersonalizeField":{"type":"object","description":"캐러셀 커머스형 메시지의 개인화 필드","properties":{"content":{"type":"object","additionalProperties":{"type":"string"}},"buttons":{"type":"object","additionalProperties":{"type":"string"},"description":"버튼 리스트"},"coupon":{"$ref":"#/components/schemas/CouponPersonalizeField"},"product_name":{"type":"object","additionalProperties":{"type":"string"},"description":"상품명 관련 개인화 필드"},"price":{"$ref":"#/components/schemas/CommercePricePersonalize"}}},"CarouselPersonalizeField":{"type":"object","description":"일반 캐러셀(피드형) 메시지의 개인화 필드","properties":{"content":{"type":"object","additionalProperties":{"type":"string"},"description":"캐러셀 아이템의 부가정보 영역"},"coupon":{"$ref":"#/components/schemas/CouponPersonalizeField"},"buttons":{"type":"object","additionalProperties":{"type":"string"},"description":"버튼 개인화 영역"}}},"ImageVariable":{"type":"object","description":"대체 이미지 설정 정보","properties":{"image_url":{"type":"string","nullable":true,"description":"대체할 이미지의 URL"},"image_click_url":{"type":"string","nullable":true,"description":"이미지 클릭 시 이동할 URL"}}}}}}
```