카카오 친구톡은 **2025-12-31 로 종료**되었습니다. 후속 채널은 브랜드메시지입니다.

가장 먼저 알아야 할 것: **기존 코드는 깨지지 않습니다.** 엔드포인트는 유지되고 호출도 성공합니다. 하지만 실제로 나가는 것은 카카오가 자동 대체한 브랜드메시지이므로, 무엇이 달라지는지는 알고 있어야 합니다.

## 지금 무슨 일이 일어나고 있나

| | 2025-12-31 이전 | 2026-01-01 이후 |
| --- | --- | --- |
| `/api/v2/friends/send` 호출 | 친구톡 발송 | 호출 성공, **브랜드메시지(자유형)로 자동 대체 발송** |
| 엔드포인트 제거 여부 | — | 제거되지 않음 |
| 신규 개발 | 친구톡 | **브랜드메시지** |

## 언제 옮겨야 하나

### 지금 옮겨야 하는 경우

- **템플릿 기반 리치 타입**이 필요하다 — `FL`(리스트), `FC`(커머스), `FM`(복합), `FP`(프리미엄 동영상), `FA`(캐러셀)
- **채널 친구가 아닌 수신자**에게 보내야 한다 — `targeting: N` 또는 `I`
- **수신 동의한 전체 채널 친구에게 동보**를 보내야 한다 — `targeting: F`, 수신자 목록 없이

이 셋은 친구톡으로는 애초에 불가능했던 것들입니다. 브랜드메시지로 옮기는 이유가 "종료 대응"이라기보다 **기능 확장**에 가깝습니다.

### 당장 안 옮겨도 되는 경우

- **자유 본문 타입(`FT`/`FI`/`FW`)을 개별 수신자에게** 보내는 코드

이 조합은 오히려 친구톡 엔드포인트를 **계속 써야 합니다.** 브랜드메시지 엔드포인트는 같은 조합에 `NOT_A_BRAND_MESSAGE` 를 반환합니다.

```typescript
// 이건 그대로 둔다 — 브랜드메시지로 옮기면 NOT_A_BRAND_MESSAGE 가 난다.
await sendgo.friendtalk.send({
  messageType: 'FT',
  content: '안녕하세요! 이벤트 안내드립니다.',
  contacts: [{ contact: '01012345678' }],
});
```

### 대체 발송 자체를 원하지 않는다면

친구톡 요청이 브랜드메시지로 대체되는 것을 원하지 않으면, 친구톡을 시도하지 말고 [문자](/ko/cookbook/send-sms)로 보내세요.

## 메시지 타입 대응표

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

| 친구톡 | 브랜드메시지 | 내용 |
| --- | --- | --- |
| `FT` | `BT` | 텍스트 |
| `FI` | `BI` | 이미지 |
| `FW` | `BW` | 와이드 이미지 |
| `FL` | `BL` | 리스트 |
| `FC` | `BC` | 커머스 |
| `FM` | `BM` | 복합 |
| `FP` | `BP` | 프리미엄 동영상 |
| `FA` | `BA` | 캐러셀 |

코드에서 `BT`, `BI` 로 바꿔 쓰지 마세요. 넘기는 값은 `FT`, `FI` 그대로입니다.

## 옮기는 법

### 옮기기 전 (친구톡, 개별 수신자)

```typescript
await sendgo.friendtalk.send({
  messageType: 'FI',
  content: '이번 주 특가 상품을 확인하세요!',
  imageUrl: 'https://cdn.example.com/banner.jpg',
  adFlag: 'Y',
  contacts: [{ contact: '01012345678' }],
});
```

### 옮긴 뒤 (브랜드메시지, 템플릿 기반)

브랜드메시지는 콘솔에 등록한 템플릿을 참조합니다. `friendTemplateUuid` 가 필요합니다.

```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.broadcast({
  messageType: 'FW',
  friendTemplateUuid: '9cd5460b-6458-4edc-9b11-c26d3013c340',
  adFlag: 'Y',
});
```

가장 큰 차이는 **본문을 요청에 싣지 않는다**는 점입니다. 친구톡은 `content` 를 그때그때 넘겼지만, 브랜드메시지의 리치 타입은 등록된 템플릿을 참조하고 변수만 채웁니다.

## 캠페인 조회도 갈라진다

```bash
# 브랜드메시지 캠페인 (BRAND_GROUP, BRAND_BASIC)
GET /api/v2/brand-messages

# 친구톡 캠페인
GET /api/v2/friends
```

브랜드메시지 목록 엔드포인트는 친구톡 캠페인을 반환하지 않습니다. 두 채널을 함께 쓰고 있다면 리포트 코드에서 둘 다 조회해야 합니다.

## 체크리스트

- [ ] 친구톡 발송 코드를 전부 찾았다 (`friendtalk`, `friends/send`)
- [ ] 각 호출이 `FT`/`FI`/`FW` + 개별 수신자인지 확인했다 → 그렇다면 **그대로 둔다**
- [ ] 리치 타입·비친구·동보가 필요한 곳을 골라냈다 → 브랜드메시지로 이전
- [ ] 콘솔에 브랜드메시지 템플릿을 등록하고 `friendTemplateUuid` 를 확보했다
- [ ] 광고성이라면 `adFlag: 'Y'` 와 [광고 규칙](/ko/cookbook/ad-message-rules)을 확인했다
- [ ] 리포트·통계 코드가 두 엔드포인트를 모두 조회한다
- [ ] SDK 를 1.2.1 이상으로 올렸다 (친구톡 종료가 반영된 버전)

## 다음 단계

- [브랜드메시지 보내기](/ko/cookbook/send-brand-message)
- [광고성 메시지 규칙](/ko/cookbook/ad-message-rules)