1-1. 메시지 기본 정보 발송
발송 방법 및 전송/수신 파라미터 정의
SSL Protocol을 이용하여 파라미터들을 핑거푸시 Server to Server API Server(이하 API Server)에 전달합니다.
API Server로 전달해야 할 파라미터들은 아래 표를 참조해 주세요.
HTTPS Headers
Content-Type
필수
application/json
HTTPS Parameters
[표 1.1] 다수 발송, 메시지 IDX 받기 HTTPS, Parameters
senderKey
필수
text(40)
카카오 발신프로필 키
messageType
필수
text(2)
메시지 유형 FT – 텍스트형 FI – 이미지형 FW – 와이드 이미지형 FL – 와이드 아이템 리스트형 FC – 캐러셀 피드형 FP – 프리미엄 동영상형 FM – 커머스형 FA – 캐러셀 커머스형
title
선택
text(100)
캠페인 구분용 제목
sendStatus
선택
text(4)
0001: 바로 발송(default)
0002: 예약발송
sendDate
선택
text(20)
발송 시간 yyyy-MM-dd HH:mm:ss
idType
선택
text(3)
수신 대상자 타입 RCT: 수신자 전화번호 (default) AUI: 앱유저 아이디 KUK: 카카오톡 채널 사용자 식별 키
orgCode
선택
text(20)
부서 코드 (핑거푸시 사이트에서 발급받은 부서 코드)
header
선택
text(20)
와이드 아이템리스트, 프리미엄 동영상형 메시지 타입에 표기할 제목
message
선택
text
사용자에게 전달될 메시지
텍스트형 - 최대 1,000자 (줄바꿈: 최대 33개, URL 형식 입력 가능)
이미지형 - 최대 400자 (줄바꿈: 최대 29개)
와이드 이미지형 - 최대 76자 (줄바꿈: 최대 1개)
프리미엄 동영상형 - 최대 76자 (줄바꿈: 최대 1개)
additional_content
선택
text(34)
부가 정보 (공백 포함 34자로 제한) 커머스 타입(FM, FA)에서 사용
adult
선택
text(1)
성인용 메시지 여부 (default: N)
mmsAttach
선택
object
전환 발송용 문자 재처리 정보 JSON
mmsAttach.mmsContent
필수
byte(2000)
문자 메시지 내용 (90Byte이하일 경우 : SMS로 발송, 90Byte초과시는 LMS로 발송)
mmsAttach.subject
필수
byte(40)
문자 메시지 제목
mmsAttach.callback
필수
text(25)
사전 등록된 발신자 전화번호
mmsAttach.originCid
선택
text(9)
특부가 사업번호(특부가 사업자의 경우 필수)
[표 1.1.1] attach Json Parameters
button
-
list
버튼 목록
button.name
필수
text(14)
버튼 제목
(텍스트형, 이미지형 외 최대 8자)
button.type
필수
text(2)
버튼 타입 WL: 웹 링크 버튼 AL: 앱 링크 버튼 BK: 봇 키워드 버튼(버튼 클릭시 텍스트 전송) MD: 메시지 전달 버튼(버튼 클릭시 텍스트 + 메시지 본문 전송)
button.url_mobile
-
text
Mobile 환경에서 버튼 클릭 시 이동할 URL
button.url_pc
-
text
PC 환경에서 버튼 클릭 시 이동할 URL
button.scheme_android
-
text
Mobile Android 환경에서 버튼 클릭 시 실행할 Application Custom Scheme
button.scheme_ios
-
text
Mobile IOS 환경에서 버튼 클릭 시 실행할 Application Custom Scheme
image
-
object
이미지 정보
image.img_url
필수
text
이미지 업로드 후 발급된 이미지 URL
image.img_link
선택
text
이미지 클릭 시 이동할 URL 미설정시 카카오톡 내 이미지 뷰어 사용
item
-
object
와이드 아이템 리스트 정보
item.list
필수
list
와이드 아이템 리스트(최소: 3, 최대 4)
item.list.title
필수
text(25)
아이템 제목(단 1번째 아이템 25자로 제한)
item.list.img_url
필수
text
아이템 이미지 업로드 후 발급된 이미지 URL
item.list.url_mobile
필수
text
Mobile 환경에서 버튼 클릭 시 이동할 URL
item.list.url_pc
선택
text
PC 환경에서 버튼 클릭 시 이동할 URL
item.list.scheme_android
선택
text
Mobile Android 환경에서 버튼 클릭 시 실행할 Application Custom Scheme
item.list.scheme_ios
선택
text
Mobile IOS 환경에서 버튼 클릭 시 실행할 Application Custom Scheme
coupon
-
object
쿠폰 정보
coupon.title
필수
text
쿠폰 이름 형식 (5가지 형식으로 제한)
"${숫자}원 할인 쿠폰" (숫자는 1이상 99,999,999 이하)
"${숫자}% 할인 쿠폰" (숫자는 1이상 100 이하)
"배송비 할인 쿠폰"
"${7자 이내} 무료 쿠폰"
"${7자 이내} UP 쿠폰"
coupon.description
필수
text
쿠폰 상세 설명
와이드이미지, 와이드아이템리스트, 프리미엄 동영상 : 최대 18자
그 외 : 최대 12자
coupon.url_mobile
-
text
Mobile 환경에서 버튼 클릭 시 이동할 URL
coupon.url_pc
-
text
PC 환경에서 버튼 클릭 시 이동할 URL
coupon.scheme_android
-
text
Mobile Android 환경에서 버튼 클릭 시 실행할 Application Custom Scheme
coupon.scheme_ios
-
text
Mobile IOS 환경에서 버튼 클릭 시 실행할 Application Custom Scheme
commerce
-
object
커머스 정보
commerce.title
필수
text(30)
상품 제목
commerce.regular_price
필수
number
정상가격 (0 ~ 99,999,999)
commerce.discount_price
선택
number
discount_price Number N 할인가격 (0 ~ 99,999,999)
commerce.discount_rate
선택
number
할인율 할인가격 존재시 할인율, 정액할인가격 중 하나 는 필수 (0 ~ 100)
commerce.discount_fixed
선택
number
정액할인가격 할인가격 존재시 할인율, 정액할인가격 중 하나 는 필수 (0 ~ 999,999)
video
-
object
비디오 정보
video.video_url
필수
text
카카오TV 동영상 URL
video.thumbnail_url
선택
text
동영상 썸네일용 이미지 URL, 없는 경우 동영상 기본썸네일 사용
[표 1.1.2] carousel Json Parameters
carousel.head
-
object
캐러셀 인트로 정보 - 캐러셀 커머스 유형(FA) 전용
carousel.head.header
필수
text(20)
캐러셀 인트로 헤더
carousel.head.content
필수
text(50)
캐러셀 인트로 내용
carousel.head.image_url
필수
text
캐러셀 인트로 이미지 주소
carousel.head.url_mobile
선택
text
Mobile 환경에서 버튼 클릭 시 이동할 URL
carousel.head.url_pc
선택
text
PC 환경에서 버튼 클릭 시 이동할 URL
carousel.head.scheme_android
선택
text
Mobile Android 환경에서 버튼 클릭 시 실행할 Application Custom Scheme
carousel.head.scheme_ios
선택
text
Mobile IOS 환경에서 버튼 클릭 시 실행할 Application Custom Scheme
carousel.list
필수
list
캐러셀 아이템 리스트(최소 2: 최대 6)
carousel.list.header
선택
text(20)
캐러셀 아이템 제목(줄바꿈 불가)
- 캐러셀 피드 유형(FC) 전용
carousel.list.message
선택
text(180)
캐러셀 아이템 메시지(줄바꿈 최대 2개)
- 캐러셀 피드 유형(FC) 전용
carousel.list.additional_content
선택
text(34)
부가 정보 (공백 포함 34자로 제한) 캐러셀 커머스형타입 전용
carousel.tail
선택
object
더보기 버튼 정보
carousel.tail.url_mobile
필수
text
Mobile 환경에서 버튼 클릭 시 이동할 URL
carousel.tail.url_pc
선택
text
PC 환경에서 버튼 클릭 시 이동할 URL
carousel.tail.scheme_android
선택
text
Mobile Android 환경에서 버튼 클릭 시 실행할 Application Custom Scheme
carousel.tail.scheme_ios
선택
text
Mobile IOS 환경에서 버튼 클릭 시 실행할 Application Custom Scheme
Request JSON Sample
메시지 유형별 발송 예시는 3. 자유형 발송 유형별 샘플을 확인해주세요.
Response JSON
API 서버에서 전달 받은 파라미터 처리 후 결과를 JSON 형태로 제공합니다. code 값이 200 이고, processCode가 20001 이면 다음 대상자 등록 프로세스를 진행합니다.
[표 1.2] 발송 JSON 결과
code
결과 코드
message
결과 메시지
data.msgIdx
메시지 번호
data.processCode
메시지 처리 단계 코드
data.ratelimitRemaining
잔여 분(minute) 동안 가능한 요청 횟수
data.retryAfter
요청 갱신 시간까지 남은 초(second)
[표 1.3] 발송 JSON 결과의 result code 유형
200
정상처리 됨
401
접근 권한이 없습니다.
계정 서비스 권한 여부
403
필수 값이 없습니다.
429
분당 호출 수 초과
4033
메시지에 대한 접근 권한이 없습니다.
브랜드 메시지 템플릿 정보 없음
4035
유효한 호출이 아닙니다.
인증 토큰 누락
4036
유효한 호출이 아닙니다.
인증 토큰 만료
4037
유효한 호출이 아닙니다.
화이트리스트에 존재하지 않는 IP
500
서버 에러
[표 1.4] JSON 결과의 processCode code 유형
20001
브랜드 메시지 등록 정상 처리
메시지 아이디가 반환됨
20002
발송 대상자 등록 정상 처리
20003
브랜드 메시지 등록 완료
Last updated