> ## Documentation Index
> Fetch the complete documentation index at: https://developer.alltalk.co.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# 브랜드메시지 발송

> 카카오 비즈니스 채널을 통해 브랜드메시지(친구톡 기반)를 전송합니다. 텍스트/이미지/와이드/캐러셀/커머스/영상 등 다양한 말풍선 타입을 지원합니다.

<Note>
  브랜드메시지는 발신 채널(비즈니스 채널)이 등록되어 있어야 하며, 비친구 대상(M/N 타겟팅)은 채널 친구 5만명 이상 승인된 채널만 발송할 수 있습니다.
</Note>

## 발송 유형

브랜드메시지는 두 가지 발송 유형을 지원합니다.

| `sendType`        | 설명                        | `template` | 지원 말풍선 타입                                                  |
| ----------------- | ------------------------- | ---------- | ---------------------------------------------------------- |
| `FREE` (자유형, 기본값) | 본문/이미지를 요청에 직접 담아 발송      | 불필요        | `TEXT`, `IMAGE`, `WIDE`, `WIDE_ITEM_LIST`, `CAROUSEL_FEED` |
| `BASIC` (기본형)     | 사전 등록·승인된 브랜드메시지 템플릿으로 발송 | **필수**     | 전체 (`PREMIUM_VIDEO`, `COMMERCE`, `CAROUSEL_COMMERCE` 포함)   |

## 대상(타겟팅)과 과금

| `targeting` | 대상               | 과금 기준                | 비고                         |
| ----------- | ---------------- | -------------------- | -------------------------- |
| `I` (기본값)   | 발송 요청 대상 ∩ 채널 친구 | 친구 (`bm_friend`)     |                            |
| `F`         | 채널 전체 친구         | 친구 (`bm_friend`)     |                            |
| `N`         | 비친구              | 비친구 (`bm_nonfriend`) | `channelId` 필수, 5만명+ 승인 채널 |
| `M`         | 친구 + 비친구         | 비친구 (`bm_nonfriend`) | `channelId` 필수, 5만명+ 승인 채널 |

## Base URL

```
https://api.alltalk.co.kr
```

## Headers

<ParamField header="apikey" type="string" required>
  제공받은 API key
</ParamField>

## Body (JSON)

<ParamField body="service" type="number" required>
  제공받은 브랜드메시지 서비스 번호
</ParamField>

<ParamField body="chatBubbleType" type="string" required>
  말풍선 타입. `TEXT`, `IMAGE`, `WIDE`, `WIDE_ITEM_LIST`, `CAROUSEL_FEED`, `PREMIUM_VIDEO`, `COMMERCE`, `CAROUSEL_COMMERCE` 중 하나
</ParamField>

<ParamField body="groupId" type="string" required>
  그룹코드
</ParamField>

<ParamField body="numbers" type="object[]" required>
  수신자 배열. 각 항목은 아래 필드로 구성됩니다. (단건 발송 시 `mobile` 문자열로 대체 가능)

  * `key` (number): unique key
  * `hp` (string): 수신자 핸드폰 번호
  * `name` (string): 수신자 이름
  * `VAR1`, `VAR2`, ... (string): 템플릿 가변변수에 대입될 값 (BASIC)
</ParamField>

<ParamField body="sendType" type="string" default="FREE">
  발송 유형. `FREE`(자유형) 또는 `BASIC`(기본형)
</ParamField>

<ParamField body="template" type="string">
  등록된 브랜드메시지 템플릿 코드. `sendType=BASIC`인 경우 필수
</ParamField>

<ParamField body="targeting" type="string" default="I">
  발송 대상. `I` / `F` / `N` / `M` (위 표 참조)
</ParamField>

<ParamField body="channelId" type="string">
  발신 채널 ID. `targeting`이 `N` 또는 `M`인 경우 필수
</ParamField>

<ParamField body="message" type="string">
  본문 메시지 (자유형 `TEXT` 등에서 사용)
</ParamField>

<ParamField body="image" type="string">
  이미지 URL (자유형 `IMAGE` / `WIDE`)
</ParamField>

<ParamField body="buttons" type="object[]">
  버튼 정보 (JSON Array). 각 버튼의 `link1`(PC URL), `link2`(모바일 URL) 지정
</ParamField>

<ParamField body="carousel" type="object[]">
  캐러셀 아이템 배열 (자유형 `CAROUSEL_FEED`)
</ParamField>

<ParamField body="item" type="object">
  아이템 리스트 (자유형 `WIDE_ITEM_LIST`)
</ParamField>

<ParamField body="coupon" type="object">
  쿠폰 정보
</ParamField>

<ParamField body="header" type="string">
  헤더 텍스트
</ParamField>

<ParamField body="additionalContent" type="string">
  부가 정보 텍스트
</ParamField>

<ParamField body="alter" type="boolean" default="false">
  대체문자 발송 여부
</ParamField>

<ParamField body="alterMessage" type="string">
  대체문자 본문 (`alter=true` 시)
</ParamField>

<ParamField body="callbackNo" type="string">
  대체문자 발신번호 (`alter=true` 시 필수). 사전에 등록된 발신번호만 사용 가능합니다.
</ParamField>

<Note>
  기본형(`BASIC`)은 이미지·캐러셀·아이템·커머스·쿠폰·버튼 등 구조적 데이터가 **템플릿에 이미 포함**되어 있습니다. 이 값들을 요청에 추가로 보내면 오류(`ERR_201`)가 발생하므로, 기본형에서는 `template`과 가변변수(`numbers[].VARn`)만 전달하세요.
</Note>

## 예제

<RequestExample>
  ```javascript Node.js (자유형 TEXT) theme={null}
  const talkData = {
    service: 1234567890,
    groupId: 'YOUR_GROUP_ID',
    chatBubbleType: 'TEXT',
    sendType: 'FREE',
    targeting: 'I',
    message: '[브랜드메시지] 이번 주 신규 혜택을 확인해보세요!',
    buttons: [
      { name: '혜택 보기', link1: 'https://example.com', link2: 'https://example.com' },
    ],
    numbers: [
      { key: 1, hp: '010-1234-5678', name: '홍길동' },
      { key: 2, hp: '010-5678-1234', name: '이몽룡' },
    ],
    alter: false,
  };

  await axios.post('https://api.alltalk.co.kr/friendTalk/brand', talkData, {
    headers: { apikey: 'YOUR_API_KEY' },
  });
  ```

  ```javascript Node.js (기본형 BASIC) theme={null}
  const talkData = {
    service: 1234567890,
    groupId: 'YOUR_GROUP_ID',
    chatBubbleType: 'COMMERCE',
    sendType: 'BASIC',
    targeting: 'M',
    channelId: 'YOUR_CHANNEL_ID',
    template: 'BM_TEMPLATE_CODE',
    numbers: [
      { key: 1, hp: '010-1234-5678', name: '홍길동', VAR1: '10,000원' },
    ],
  };

  await axios.post('https://api.alltalk.co.kr/friendTalk/brand', talkData, {
    headers: { apikey: 'YOUR_API_KEY' },
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "version": "1.0.0",
    "status": "success",
    "code": 200,
    "datetime": "2026-07-02 14:00:00",
    "value": [
      {
        "uid": 37668015179,
        "date": 1750383559053,
        "status": "OK"
      }
    ],
    "count": 1,
    "total": 1
  }
  ```

  ```json 403 theme={null}
  {
    "status": "error",
    "code": "ERR_MN_NOT_APPROVED",
    "message": "해당 채널은 M/N 타겟 발송 승인을 받지 않았습니다. (채널친구 5만명+ 승인 필요)"
  }
  ```
</ResponseExample>

## 응답 필드

| 필드               | 설명                                                                    |
| ---------------- | --------------------------------------------------------------------- |
| `version`        | API 버전                                                                |
| `status`         | `success` / `error`                                                   |
| `code`           | HTTP 상태 코드 또는 에러 코드                                                   |
| `datetime`       | 응답 시각                                                                 |
| `value[].uid`    | 수신자별 발송 식별자. 발송 결과 상세 조회에 사용                                          |
| `value[].date`   | 발송 시각 (epoch ms)                                                      |
| `value[].status` | 수신자별 결과 코드. `OK` / `KKO_*` / `ERR_*` ([에러코드](/guides/error-codes) 참조) |
| `count`          | 처리된 건수                                                                |
| `total`          | 전체 요청 건수                                                              |

## 참고

* 단건 발송은 `numbers` 대신 `mobile` 문자열만 보내도 됩니다. 이 경우 응답도 단건 포맷으로 반환됩니다.
* 자유형(`FREE`)은 `PREMIUM_VIDEO`, `COMMERCE`, `CAROUSEL_COMMERCE`를 지원하지 않습니다. 해당 타입은 기본형(`BASIC` + 템플릿)으로 발송하세요.
* `N`/`M` 타겟팅(비친구 발송)은 `channelId`가 필수이며, 채널 친구 5만명 이상 승인된 채널에서만 가능합니다.
* 발송 실패(`KKO_*`) 시 `alter: true`로 설정하면 자동으로 SMS 대체 발송이 진행됩니다.