브랜드메시지 발송 - AllTalk Developers

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' },
});

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' },
});

{
  "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
}

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

POST

friendTalk

brand

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' },
});

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' },
});

{
  "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
}

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

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

발송 유형

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

`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

string

required

제공받은 API key

Body (JSON)

number

required

제공받은 브랜드메시지 서비스 번호

string

required

말풍선 타입. TEXT, IMAGE, WIDE, WIDE_ITEM_LIST, CAROUSEL_FEED, PREMIUM_VIDEO, COMMERCE, CAROUSEL_COMMERCE 중 하나

string

required

그룹코드

object[]

required

수신자 배열. 각 항목은 아래 필드로 구성됩니다. (단건 발송 시 mobile 문자열로 대체 가능)

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

string

default:"FREE"

발송 유형. FREE(자유형) 또는 BASIC(기본형)

string

등록된 브랜드메시지 템플릿 코드. sendType=BASIC인 경우 필수

string

default:"I"

발송 대상. I / F / N / M (위 표 참조)

string

발신 채널 ID. targeting이 N 또는 M인 경우 필수

string

본문 메시지 (자유형 TEXT 등에서 사용)

string

이미지 URL (자유형 IMAGE / WIDE)

object[]

버튼 정보 (JSON Array). 각 버튼의 link1(PC URL), link2(모바일 URL) 지정

object[]

캐러셀 아이템 배열 (자유형 CAROUSEL_FEED)

object

아이템 리스트 (자유형 WIDE_ITEM_LIST)

object

쿠폰 정보

string

헤더 텍스트

string

부가 정보 텍스트

boolean

default:"false"

대체문자 발송 여부

string

대체문자 본문 (alter=true 시)

string

대체문자 발신번호 (alter=true 시 필수). 사전에 등록된 발신번호만 사용 가능합니다.

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

예제

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' },
});

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' },
});

{
  "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
}

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

응답 필드

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

참고

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

​발송 유형

​대상(타겟팅)과 과금

​Base URL

​Headers

​Body (JSON)

​예제

​응답 필드

​참고

발송 유형

대상(타겟팅)과 과금

Base URL

Headers

Body (JSON)

예제

응답 필드

참고