7.kakao biz 친구톡 APIkakao biz 친구톡 API

LABEdit

7.1개요

7.2용어 정의

7.2.1허브 파트너(Hub Partner)

7.2.2카카오톡 채널(Kakao Talk Channel)

7.3선결 조건

메시지 API를 사용하여 메시지 전송을 대행하기 위해 아래의 조건이 선결되어야 한다.

7.4API 스펙

7.4.1Host

7.4.2메시지 전송 요청

[Request]
[Parameter]

키

타입

필수

설명

예제

message_type

text(2)

Y

메시지 타입

(FT: 친구톡텍스트, FI: 친구톡이미지, FW: 친구톡와이드이미지)

"message_type":"FT"

senderKey

text(40)

Y

발신 프로필 키

"sender_key":

"2662e99eb7a1f21abb3955278e9955f5a9a99b62"

phone_number

text(16)

N

사용자 전화번호

(국가코드(82)를 포함한 전화번호)

"phone_number":"821012345678"

app_user_id

text(20)

N

앱유저아이디

phone_number 혹은 app_user_id 둘 중 하나는 반드시 있어야 한다.

phone_number와 app_user_id의 정보가 동시에 요청된 경우 phone_number로만 발송합니다.

"app_user_id":"12345"

user_key

text(30)

N

사용자 식별키

카카오톡 채널 봇을 이용해 받은 카카오톡 채널 사용자 식별키

"user_key":"MZjEVK4x18_V"

message

text(1000)

N

사용자에게 전달될 메시지

(공백 포함 1000자로 제한)

"message":"채널 추가 없이 보내는 정보형 메시지 ‘카카오톡 비즈메시지’를 소개합니다."

ad_flag

text(1)

N

광고성 메시지 필수 표기 사항을 노출

(노출 여부 Y/N, 기본값 Y)

"ad_flag":"Y"

attachment

json

N

메시지에 첨부할 내용

(링크 버튼)

"attachment":{"button":

[{"name":"비즈메시지소개",

"type":"WL",

"url_pc":"http://bizmessage.kakao.com/",

"url_mobile":"http://bizmessage.kakao.com/"}]}

<4.4 Attachment 에서 확인 가능>

[Response]

키

타입

필수

설명

예제

code

text(4)

Y

처리 결과 코드

(0000은 정상 / 나머지는 오류)

"code ":"0000"

message

text

N

오류 메시지

(오류시 존재하는 값)

"message ":"NoSendAvailableTimeException(1)"

7.4.3친구톡 상품 타입

7.4.3.1텍스트 타입

7.4.3.2이미지 타입

7.4.3.3와이드 말풍선 타입

7.4.4Attachment

친구톡은 <4.2 메시지 전송 요청>의 요청 필드 중 attachment 값에 링크 버튼을 첨부하여 발송할 수 있다.
버튼은 목록으로(Array) 최대 5개까지 템플릿에 등록하여 발송할 수 있다.
[Parameter]

키


타입

필수

설명

buttons




버튼 목록


name

text(14)

Y

버튼명


type

text(2)

Y

버튼 타입 아래 button 타입에서 확인 가능


scheme_android

text

-

mobile android 환경에서 버튼 클릭 시 실행할

application custom scheme


scheme_ios

text

-

mobile ios 환경에서 버튼 클릭 시 실행할

application custom scheme


url_mobile

text


mobile 환경에서 버튼 클릭 시 이동할 url


url_pc

text

-

pc 환경에서 버튼 클릭 시 이동할 url

image

img_url

text

Y

노출할 이미지


img_link

text

N

이미지 클릭시 이동할 url

[Example]
"attachment":{"button":[{"name":"비즈메시지 소개","type":"WL","url_pc":"http://bizmessage.kakao.com/", "url_mobile":"http://bizmessage.kakao.com/"}]}

"attachment":{"button":[{"name":"비즈메시지 소개","type":"WL","url_pc":"http://bizmessage.kakao.com/", "url_mobile":"http://bizmessage.kakao.com/"}], "image":{"img_url":"img_url","img_link":"http://bizmessage.kakao.com/"}}

"attachment":{"button":[{"name":"비즈메시지 소개","type":"WL","url_pc":"http://bizmessage.kakao.com/", "url_mobile":"http://bizmessage.kakao.com/"},{"name":"커스텀스킴 테스트","type":"AL","scheme_ios":"scheme://xxx.xx", "scheme_android":"scheme://xxx.xx"}]}

"attachment":{"button":[{"name":"톡에서 설문하기","type":"BF","biz_form_key":"==========="}]}

7.4.4.1button 타입별 속성

필수 파라메터를 모두 입력하셔야 정상적인 발송이 가능합니다.

버튼타입

속성

타입

필수

설명

WL

url_mobile

text

Y

버튼 클릭 시 이동할 pc/mobile환경별 web url


url_pc

text

N


AL

scheme_android

text

-

scheme_ios, scheme_android, url_mobile 중 2가지 필수 입력

mobile android 환경에서 버튼 클릭 시 실행할

application custom scheme


scheme_ios

text

-

mobile ios 환경에서 버튼 클릭 시 실행할

application custom scheme


url_mobile

text

-

mobile 환경에서 버튼 클릭 시 이동할 url


url_pc

text

N

pc 환경에서 버튼 클릭 시 이동할 url

BK

-

-

-

해당 버튼 텍스트 전송

MD

-

-

-

해당 버튼 텍스트 + 메시지 본문 전송

BC

-

-

-

상담톡을 이용하는 카카오톡 채널만 이용가능


chat_extra

text

N

상담톡 전환 시 전달할 메타정보

BT

-

-

-

카카오 I 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용가능


chat_extra

text

N

봇 전환 시 전달할 메타정보


chat_event

text

N

봇 전환 시 연결할 봇 이벤트명

7.5코드 정의

code

설명


0000


정상코드

1001

NoJsonBody

Request Body가 Json형식이 아님

1002

InvalidHubPartnerKey

허브 파트너 키가 유효하지 않음

1003

InvalidSenderKey

발신 프로필 키가 유효하지 않음

1004

NoValueJsonElement

Request Body(Json)에서 name을 찾을 수 없음

1006

DeletedSender

삭제된 발신프로필. (메시지 사업 담당자에게 문의)

1007

StoppedSender

차단 상태의 발신프로필. (메시지 사업 담당자에게 문의)

1011

ContractNotFound

계약정보를 찾을 수 없음. (메시지 사업 담당자에게 문의)

1012

InvalidUserKeyException

잘못된 형식의 유저키 요청

1013

InvalidAppLink

유효하지 않은 app연결

1014

InvalidBizNum

유효하지 않은 사업자번호

1015

TalkUserIdNotFonud

유효하지 않은 app user id 요청

1016

BizNumNotEqual

사업자등록번호 불일치

1020

InvalidReceiveUser

전화번호 or app user id가 유효하지 않거나 미입력 요청

1021

BlockedProfile

차단 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)

1022

DeactivatedProfile

닫힘 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)

1023

DeletedProfile

삭제된 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)

1024

DeletingProfile

삭제대기 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)

1025

SpammedProfile

메시지차단 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)

1030

InvalidParameterException

잘못된 파라메터 요청

2003

FailedToSendMessageByNoFriendshipException

(테스트 발송) 카카오톡 채널을 추가하지 않았음

2006

FailedToMatchSerialNumberPrefixPattern

<4.2 메시지 전송 요청>에 명시된 시리얼넘버 형식 불일치

3000

UnexpectedException

예기치 않은 오류 발생

3006

FailedToSendMessageException

내부 시스템 오류로 메시지 전송 실패

3008

InvalidPhoneNumberException

전화번호 오류

3010

JsonParseException

Json 파싱 오류

3011

MessageNotFoundException

메시지가 존재하지 않음

3012

SerialNumberDuplicatedException

메시지 일련번호가 중복됨

- 메시지 일련번호는 CS처리를 위해 고유한 값이 부여되어야 함.

3013

MessageEmptyException

메시지가 비어 있음

3014

MessageLengthOverLimitException

메시지 길이 제한 오류

(텍스트 타입 1000자 초과, 이미지 타입 400자 초과)

3018

NoSendAvailableException

메시지를 전송할 수 없음

3022

NoSendAvailableTimeException

메시지 발송 가능한 시간이 아님

(친구톡 / 마케팅 메시지는 08시부터 20시 50분까지 발송 가능)

3024

MessageInvalidImageException

메시지에 포함된 이미지를 전송할 수 없음

(이미지주소 또는 링크가 올바르지 않거나 이미지가 규격에 맞지 않음)

4000

ResponseHistoryNotFoundException

메시지 전송 결과를 찾을 수 없음

4001

UnknownMessageStatusError

알 수 없는 메시지 상태

5000

InvalidTestUser

(테스트 발송) 관리자 혹은 일회성 인증을 받은 사용자가 아님

5001

DailyTestLimitExceeded

(테스트 발송) 일일 발송량 초과

9998

현재 서비스를 제공하고 있지 않습니다.

시스템에 문제가 발생하여 담당자가 확인하고 있는 경우

9999

시스템에서 알 수 없는 문제가 발생하였습니다.

담당자가 확인 중입니다.

시스템에 문제가 발생하여 담당자가 확인하고 있는 경우

7.6친구톡 이미지 업로드

7.6.1공통

7.6.2이미지 업로드 요청

POST /ft/upload_image
[Request]

키

타입

필수

설명

image

binary

Y

업로드할 이미지 파일

[Response]

키

타입

설명

code

text

결과코드

image

text

업로드된 이미지 url

7.6.3와이드 말풍선 이미지 요청

POST /ft/wide/upload_image
[Request]

키

타입

필수

설명

image

binary

Y

업로드할 이미지 파일

[Response]

키

타입

설명

code

text

결과코드

image

text

업로드된 이미지 url

7.6.4코드 정의

code

message


설명

200

-


요청 성공

403

-


권한 없음

405

-


파라미터 오류

600

FailedToUploadImageException

InvalidImageMaxLengthException

이미지 용량 초과



InvalidImageSizeException

발송할 수 없는 이미지 사이즈



InvalidImageFormatException

지원하지 않는 이미지 형식