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

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

준비물

• 카카오 발신프로필 키(kakaoSenderKey) → 발신번호 사전등록
• 콘솔에 등록한 브랜드메시지 템플릿의 friendTemplateUuid
• 광고성 메시지라면 adFlag: "Y" 와 광고 규칙 준수

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 입니다. 자세한 내용은 친구톡 종료 대응에 있습니다.

언어별 예제

Node.js / 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

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

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

REST 직접 호출

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 를 함께 넘겨야 합니다.

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

캠페인 결과 조회

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

# 목록 (기본 최근 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 를 쓰세요.

다음 단계

• 친구톡 종료 대응 마이그레이션
• 광고성 메시지 규칙