브랜드메시지는 카카오 채널을 통한 **마케팅·홍보 메시지** 채널입니다. 정보성만 가능한 알림톡과 달리 광고를 보낼 수 있고, 친구톡과 달리 **채널 친구가 아닌 사람에게도** 보낼 수 있습니다.

> **v2 전용입니다.** v1 에는 이 엔드포인트가 없습니다.

## 준비물

- 카카오 발신프로필 키(`kakaoSenderKey`) → [발신번호 사전등록](/ko/cookbook/sender-number)
- 콘솔에 등록한 브랜드메시지 템플릿의 **`friendTemplateUuid`**
- 광고성 메시지라면 `adFlag: "Y"` 와 [광고 규칙](/ko/cookbook/ad-message-rules) 준수

## `targeting` 이 경로를 가른다

| `targeting` | 대상 | 발송 방식 | `contacts` |
| --- | --- | --- | --- |
| `M` | 채널 친구 | 단건(`BRAND_BASIC`) | 필수 |
| `N` | 채널 친구가 **아닌** 수신자 | 단건(`BRAND_BASIC`) | 필수 |
| `I` | 지정 대상 | 단건(`BRAND_BASIC`) | 필수 |
| `F` | 수신 동의한 **전체** 채널 친구 | 동보(`BRAND_GROUP`) | 불필요 |

`F` 는 수신자를 지정하지 않으므로 응답에 발송 건수가 없고 **접수 여부만** 돌아옵니다. 결과는 캠페인 조회로 확인합니다.

## 메시지 타입

요청에는 **친구톡 코드를 그대로** 넘깁니다. 서버가 브랜드메시지 코드로 변환합니다.

| 넘기는 값 | 변환 결과 | 내용 |
| --- | --- | --- |
| `FT` | `BT` | 텍스트 |
| `FI` | `BI` | 이미지 |
| `FW` | `BW` | 와이드 이미지 |
| `FL` | `BL` | 리스트 |
| `FC` | `BC` | 커머스 |
| `FM` | `BM` | 복합 |
| `FP` | `BP` | 프리미엄 동영상 |
| `FA` | `BA` | 캐러셀 |

**중요한 예외**: `FT`/`FI`/`FW` 를 `M`/`N`/`I` 로 보내면 이 엔드포인트는 `NOT_A_BRAND_MESSAGE` 를 반환합니다. 자유 본문을 개별 수신자에게 보내는 경로는 여전히 `/api/v2/friends/send` 입니다. 자세한 내용은 [친구톡 종료 대응](/ko/cookbook/friendtalk-sunset)에 있습니다.

## 언어별 예제

### Node.js / TypeScript

```typescript
// 단건 발송 — 채널 친구 대상
await sendgo.brandMessage.send({
  targeting: 'M',
  messageType: 'FL',
  friendTemplateUuid: '9cd5460b-6458-4edc-9b11-c26d3013c340',
  adFlag: 'Y',
  contacts: [{ contact: '01012345678', var1: '29,000원' }],
});

// 단건 발송 — 채널 친구가 아닌 수신자
await sendgo.brandMessage.send({
  targeting: 'N',
  messageType: 'FM',
  friendTemplateUuid: '9cd5460b-6458-4edc-9b11-c26d3013c340',
  adFlag: 'Y',
  contacts: [{ contact: '01012345678' }],
});

// 동보 발송 — 수신 동의한 전체 채널 친구 (contacts 없음)
await sendgo.brandMessage.broadcast({
  messageType: 'FW',
  friendTemplateUuid: '9cd5460b-6458-4edc-9b11-c26d3013c340',
  adFlag: 'Y',
});

// 캠페인 결과 확인
const list = await sendgo.brandMessage.campaigns({ count: 10 });
const one  = await sendgo.brandMessage.campaign(campaignId);
```

### Python

```python
client.brand_message.send(
    targeting="M",
    message_type="FL",
    friend_template_uuid="9cd5460b-6458-4edc-9b11-c26d3013c340",
    ad_flag="Y",
    contacts=[{"contact": "01012345678", "var1": "29,000원"}],
)
```

### PHP · Laravel

```php
<?php

$sendgo->brandMessage->send([
    'targeting'          => 'M',
    'messageType'        => 'FL',
    'friendTemplateUuid' => '9cd5460b-6458-4edc-9b11-c26d3013c340',
    'adFlag'             => 'Y',
    'contacts'           => [['contact' => '01012345678', 'var1' => '29,000원']],
]);
```

### REST 직접 호출

```bash
curl -X POST https://sendgo.io/api/v2/brand-messages/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kakaoSenderKey": "your_kakao_sender_key",
    "targeting": "F",
    "messageType": "FW",
    "friendTemplateUuid": "9cd5460b-6458-4edc-9b11-c26d3013c340",
    "adFlag": "Y",
    "scheduleType": "DIRECTLY"
  }'
```

## SMS 대체 발송

브랜드메시지도 `replaceSms: "Y"` 로 실패 시 문자 대체가 가능합니다. `smsSubject` 와 `smsContent`, 그리고 `senderKey` 를 함께 넘겨야 합니다.

```typescript
await sendgo.brandMessage.send({
  targeting: 'M',
  messageType: 'FL',
  friendTemplateUuid: '...',
  replaceSms: 'Y',
  smsSubject: '[여름 특가]',
  smsContent: '여름 한정 특가를 확인하세요.',
  contacts: [{ contact: '01012345678' }],
});
```

## 캠페인 결과 조회

동보 발송은 접수만 확인되므로 결과를 따로 조회합니다.

```bash
# 목록 (기본 최근 90일)
curl "https://sendgo.io/api/v2/brand-messages?count=30" -H "Authorization: Bearer $TOKEN"

# 상세 — 발송 응답의 campaignId 사용
curl "https://sendgo.io/api/v2/brand-messages/$CAMPAIGN_ID" -H "Authorization: Bearer $TOKEN"
```

이 엔드포인트는 브랜드메시지 캠페인(`BRAND_GROUP`, `BRAND_BASIC`)만 반환합니다. 친구톡 캠페인은 `/api/v2/friends` 를 쓰세요.

## 다음 단계

- [친구톡 종료 대응 마이그레이션](/ko/cookbook/friendtalk-sunset)
- [광고성 메시지 규칙](/ko/cookbook/ad-message-rules)