친구톡
카카오톡 채널을 맺은 이용자 대상으로만 메시지 발송이 가능한 대신, 광고성 메시지도 발송 가능한 API
서비스를 이용하시려면 [서비스 콘솔 / 발신번호]에서 발신번호 등록을 수행해야 합니다.
서비스를 이용하시려면 [서비스 콘솔 / 템플릿 관리]에서 신규 등록을 수행해야 합니다.
발송 제약 시간(20:50 ~ 익일 08:00) 존재합니다.
해당 API는 메세지 발송 결과(WebHook)으로 결과를 전달할 수 있습니다.
친구톡 API
Path variable
Path variable(각 URI 내 중괄호({}) 로 묶인 경로 변수)는 아래 내용을 참고하여 호출 시 누락되지 않도록 해주세요.
service_id
서비스 유형 id
ft-text : 친구톡 텍스트
ft-image : 친구톡 이미지
ft-wide : 친구톡 와이드
ft-wide-item-list: 친구톡 와이드 아이템 리스트
ft-carousel-feed: 친구톡 캐러셀 피드
카카오 친구톡 API
POST https://9tpssuhbpx.apigw.ntruss.com/{service_id}/v2/send
Headers
Authorization*
string
사용자ID;secret_key
Content-Type*
string
application/json;charset=utf-8
Request Body
msg_data*
array
메시지 발송 상세 데이터 (최대 10건)
sender_key*
string
카카오 비즈메시지 발신 프로필키 [서비스 콘솔 / 발신프로필 등록] 에서 등록 필요
header
string
친구톡 와이드 아이템 리스트 제목 (32 byte)
(친구톡 와이드 아이템 리스트 사용 시 필수)
msg*
string
전송 메시지 (공백 포함 1000자 제한)
receiver_number*
string
수신자 휴대폰 번호
sender_number*
string
발신자 전화번호
msg_key*
string
사용자가 관리하는 메시지 고유 키 (null 또는 공백일 경우 자동 부여)
echo_to_webhook
string
사용자가 API PLEX로부터 webhook을 받을 때 함께 받을 string (최대 256 byte)
ad_flag
string
광고성 메시지 필수 표기사항을 노출 (기본값 Y)
failback_data
object
발송 실패 시 대체 발송 데이터
secret_key
string
failback service의 sub_account의 secret_key ( failback 사용 시 필수)
attachement 상세
button
array
N
버튼 속성 데이터 (최대 5개)
url_pc
string
N
PC환경에서 버튼 클릭 시 이동할 URL
url_mobile
string
N
Mobile 환경에서 버튼 클릭 시 이동할 URL
scheme_android
string
N
Mobile android 환경에서 버튼 클릭 시 실행할 Application custom scheme
scheme_ios
string
N
Mobile ios 환경에서 버튼 클릭 시 실행 할 Application custom scheme
chat_extra
string
N
봇 전환 시 전달할 메타정보 (50 byte)
chat_event
string
N
봇 전환 시 연결할 봇 이벤트명 (50 byte)
image
object
N
친구톡 이미지, 친구톡 와이드에서 사용
img_url
string
N
이미지 경로 URL
img_link
string
N
이미지 클릭 시 이동할 url 미설정 시 카카오톡 내 이미지 뷰어 사용
item
object
N
친구톡 와이드 아이템 리스트 정보
list
array
N
와이드 아이템 리스트(최소 3개, 최대 4개)
title
string
Y
첫번째 아이템은 25자, 2~4번째 아이템은 30자 제한
img_url
string
Y
아이템 이미지 URL
sheme_android
string
N
Mobile android 환경에서 버튼 클릭 시 실행할 Application custom scheme
scheme_ios
string
N
Mobile ios 환경에서 버튼 클릭 시 실행 할 Application custom scheme
url_mobile
string
Y
Mobile 환경에서 버튼 클릭 시 이동할 URL
url_pc
string
N
PC환경에서 버튼 클릭 시 이동할 URL
carousel 상세
list
array
캐러셀 리스트(최소 2개, 최대 6개)
header
string
Y
캐러셀 아이템 제목 (20 byte)
message
string
Y
캐러셀 아이템 메시지 (180 byte)
attachment
object
button
array
name
string
Y
버튼 제목 (8 글자)
scheme_android
string
Mobile android 환경에서 버튼 클릭 시 실행할 Application custom scheme
scheme_ios
string
Mobile ios 환경에서 버튼 클릭 시 실행 할 Application custom scheme
url_mobile
string
Mobile 환경에서 버튼 클릭 시 이동할 URL
url_pc
string
pc 환경에서 버튼 클릭 시 이동할 URL
image
object
캐러셀 썸네일 이미지
img_url
string
Y
캐러셀 썸네일 이미지 주소
img_link
string
캐러셀 썸네일 링크 주소
coupon
object
캐러셀 최하단에 추가 되는 쿠폰
title
string
쿠폰 이름
description
string
쿠폰 설명 (12자)
scheme_android
string
Mobile android 환경에서 버튼 클릭 시 실행할 Application custom scheme
scheme_ios
string
Mobile ios 환경에서 버튼 클릭 시 실행 할 Application custom scheme
url_mobile
string
Mobile 환경에서 버튼 클릭 시 이동할 URL
url_pc
string
pc 환경에서 버튼 클릭 시 이동할 URL
tail
object
더보기 버튼 정보
scheme_android
string
Mobile android 환경에서 버튼 클릭 시 실행할 Application custom scheme
scheme_ios
string
Mobile ios 환경에서 버튼 클릭 시 실행 할 Application custom scheme
url_mobile
string
Mobile 환경에서 버튼 클릭 시 이동할 URL
url_pc
string
pc 환경에서 버튼 클릭 시 이동할 URL
버튼 타입
WL
url_mobile
string
Y
[웹링크] 바로연결 클릭 시 이동할 pc/mobile 환경별 web url
url_pc
string
N
위와 동일
AL
scheme_android
string
Y
[앱링크] scheme_ios, scheme_android, url_mobile 중 2가지 필수 입력
mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme
mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme
mobile 환경에서 버튼 클릭 시 이동할 url
scheme_ios
string
Y
위와 동일
url_mobile
string
Y
위와 동일
url_pc
string
-
pc 환경에서 버튼 클릭 시 이동할 url
BK
-
-
-
해당 버튼 텍스트 전송
MD
-
-
-
해당 버튼 텍스트 + 메시지 본문 전송
BC
-
-
-
상담톡을 이용하는 카카오톡 채널만 이용가능
chat_extra
string
N
상담톡 전환 시 전달할 메타정보
BT
-
-
-
카카오 I 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용가능
chat_extra
string
N
봇 전환 시 전달할 메타정보
chat_event
string
N
봇 전환 시 연결할 봇 이벤트명
BF
biz_form_key
string
Y
비즈폼 업로드를 통해 발급받은 비즈폼 키
발송 타입 별 버튼명 글자 수 제한
친구톡 텍스트(ft-text)
최대 14자
친구톡 이미지(ft-image)
최대 14자
친구톡 와이드(ft-wide)
최대 8자
친구톡 와이드 아이템 리스트(ft-wide-item-list)
최대 8자
친구톡 캐러셀 피드(ft-carousel-feed)
최대 8자
Request Body 예시
{
"msg_data": [
{
"msg_key": "user_key_1",
"sender_number": "010xxxxxxxx",
"receiver_number": "010xxxxxxxx",
"msg": "ft-text test",
"ad_flag": "N",
"sender_key": "user_sender_key_001",
"echo_to_webhook": "echo test",
"failback_data": {
"api_unique_id": "sms-standard",
"secret_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"sender_number": "010xxxxxxxx",
"receiver_number": "010xxxxxxxx",
"origin_cid": "0123456789",
"msg": "failback 본문입니다."
}
},
{
"sender_number": "010xxxxxxxx",
"receiver_number": "010xxxxxxxx",
"msg": "ft-text and button test",
"ad_flag": "N",
"attachment": {
"button": [
{
"name": "button1",
"type": "WL",
"url_pc": "https://www.apiplex.net",
"url_mobile": "https://m.apiplex.net"
},
{
"name": "button2",
"type": "WL",
"url_pc": "https://www.apiplex.net",
"url_mobile": "https://m.apiplex.net"
}
]
},
"sender_key": “user_sender_key_001”
}
]
}Response Body
results
array
메시지 수신 데이터
msg_key
string
메시지 고유 키
desc
string
접수 결과 코드 상세
정상 요청(접수 성공)
{
"results": [
{
"code": "C100",
"desc": "success",
"msg_key": "user_key_1"
},
{
"code": "C100",
"desc": "success",
"msg_key": "11520199-f289-4681-b0e3-354393a4b041"
}
]
}잘못된 요청 또는 에러
{
"code": "C400_2",
"name": "Invalid Parameter",
"description": "사용자 인증 실패"
}잘못된 list 내부 요청
{
"results": [
{
"code": "G141",
"desc": "수신번호 예외",
"msg_key": "user_key_101"
},
{
"code": "C100",
"desc": "success",
"msg_key": "22c35870-d4a5-46e3-9d64-17f42c1e3248"
}
]
}API PLEX 응답 코드
C100
성공
C400_1
잘못된 데이터 타입
response body의 description 참조
C400_2
잘못된 요청 파라미터
response body의 description 참조
C400_3
필수 파라미터 누락
response body의 description 참조
C404_1
데이터를 찾을 수 없음
response body의 description 참조
C500_1
서버 내부 에러
response body의 description 참조
G110
API UNIQUE ID 예외 (잘못된 URL)
G140
발신번호 예외
G141
수신번호 예외
G142
잘못된 echo_to_webhook
256 byte 초과 또는 type error
G150
여신 부족
G160
1회 발송 최대 수 초과
Last updated
Was this helpful?