친구톡

카카오톡 채널을 맺은 이용자 대상으로만 메시지 발송이 가능한 대신, 광고성 메시지도 발송 가능한 API

서비스를 이용하시려면 [서비스 콘솔 / 발신번호]에서 발신번호 등록을 수행해야 합니다.

서비스를 이용하시려면 [서비스 콘솔 / 템플릿 관리]에서 신규 등록을 수행해야 합니다.

발송 제약 시간(20:50 ~ 익일 08:00) 존재합니다.

친구톡 이미지, 친구톡 와이드에서 이미지를 넣으시려면 반드시 사전에 이미지 업로드 API를 사용해야 합니다.

모든 친구톡 API의 인코딩은 UTF-8 을 기본으로 합니다.

해당 API는 메세지 발송 결과(WebHook)으로 결과를 전달할 수 있습니다.

친구톡 API

Path variable

Path variable(각 URI 내 중괄호({}) 로 묶인 경로 변수)는 아래 내용을 참고하여 호출 시 누락되지 않도록 해주세요.

code	설명
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

Name	Type	Description
Authorization*	string	사용자ID;secret_key
Content-Type*	string	application/json;charset=utf-8

Request Body

Name	Type	Description
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)
attachment	object	버튼 혹은 이미지 데이터 (attachement 상세 참조)
ad_flag	string	광고성 메시지 필수 표기사항을 노출 (기본값 Y)
carousel	object	캐러셀 데이터 (carousel 상세 참조)
failback_data	object	발송 실패 시 대체 발송 데이터
secret_key	string	failback service의 sub_account의 secret_key ( failback 사용 시 필수)
api_unique_id	string	failback service의 고유 id (failback 사용 시 필수) (failback 참조)
	String	failback service의 본문에서 사용할 payload 해당 service의 본문에서 필요로 하는 내용을 기재 (예시 참조)

200: OK 응답 반환 완료

attachement 상세

키	타입	필수	설명
button	array	N	버튼 속성 데이터 (최대 5개)
name	string	Y	버튼 제목(최대 글자 수는 발송 타입에 따라서 상이함)
type	string	Y	버튼 타입 (하단 버튼 타입 참조)
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 byte)
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 글자)
type	string	Y	버튼 타입 (하단 버튼 타입 참조)
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

응답 http status가 200으로 return되어도 모든 요청의 정상 접수를 의미하지 않습니다.

(발송 건 별 접수 결과 코드(code 필드)로 정상 접수 여부를 확인할 수 있습니다.)

키		타입	설명
results		array	메시지 수신 데이터
	msg_key	string	메시지 고유 키
	code	string	접수 결과 코드 (문서 하단 API PLEX 응답 코드 참조)
	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 응답 코드

code	설명	상세 설명
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회 발송 최대 수 초과