카카오 친구톡은 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 를 반환합니다.

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

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

친구톡 요청이 브랜드메시지로 대체되는 것을 원하지 않으면, 친구톡을 시도하지 말고 문자로 보내세요.

메시지 타입 대응표

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

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

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

옮기는 법

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

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

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

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

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 를 그때그때 넘겼지만, 브랜드메시지의 리치 타입은 등록된 템플릿을 참조하고 변수만 채웁니다.

캠페인 조회도 갈라진다

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

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

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

체크리스트

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

다음 단계

• 브랜드메시지 보내기
• 광고성 메시지 규칙