Plain 메시지 발송

Endpoint

[POST] API URL 정보

개발 및 테스트용 API운영 API

https://patch-kakao-api.happytalk.io/kakaoWebhook/v3/bzc/chat/send/plain

https://kakao-api.happytalk.io/kakaoWebhook/v3/bzc/chat/send/plain

Introduce

사용자에게 단일 요소로 구성된 말풍선 메시지를 발송하는 API입니다.

Request (Json)

Field Name	Type	Required	Description
Content-type	Text	Y	application/json
HT-Client-Id	Text	Y	고객센터에서 발급 받은 key
HT-Client-Secret	Text	Y	고객센터에서 발급 받은 token

Body

Field Name	Type (Length)	Required	Description
user_key	Text (20)	Y	사용자 고유 키
sender_key	Text (40)	Y	발신 프로필 키
serial_number	Text (30)	Y	메시지 고유 식별자
chat_bubble_type	Text (2)	Y	메시지 타입
message	Text (1000)	N	전송할 메시지 내용 (chat_bubble_type TEXT인 경우 필수)
attachment	Attachment	N	사용자에게 전달할 첨부 메시지

Example

REST API Sample

개발 및 테스트용 API운영 API

텍스트 타입이미지 타입동영상 타입

curl -X POST 'https://patch-kakao-api.happytalk.io/kakaoWebhook/v3/bzc/chat/send/plain' \
-H 'Content-Type: application/json' \
-H 'HT-Client-Id: example-id' \
-H 'HT-Client-Secret: example-secret' \
-d '{
    "user_key": "example-user_key",
    "sender_key": "example-sender_key",
    "serial_number": "abc111test",
    "chat_bubble_type": "TEXT",
    "message": "텍스트 타입 테스트입니다."
}'

curl -X POST 'https://patch-kakao-api.happytalk.io/kakaoWebhook/v3/bzc/chat/send/plain' \
-H 'Content-Type: application/json' \
-H 'HT-Client-Id: example-id' \
-H 'HT-Client-Secret: example-secret' \
-d '{
    "user_key": "example-user_key",
    "sender_key": "example-sender_key",
    "serial_number": "abc111test",
    "chat_bubble_type": "IMAGE",
    "attachment": {
        "image": {
            "img_url": "http://dn-m.talk.kakao.com/talkm/o1JvE58GUJ/cdK...2Z1/i_cefivr.jpg"
        }
    }
}'

curl -X POST 'https://patch-kakao-api.happytalk.io/kakaoWebhook/v3/bzc/chat/send/plain' \
-H 'Content-Type: application/json' \
-H 'HT-Client-Id: example-id' \
-H 'HT-Client-Secret: example-secret' \
-d '{
    "user_key": "example-user_key",
    "sender_key": "example-sender_key",
    "serial_number": "abc111test",
    "chat_bubble_type": "FILE", // (이외 VIDEO, AUDIO 타입도 지원)
    "attachment": {
        "file": {
            "file_url": "http://mud-kage.kakao.com/dn/PE6g8/o9HzDSANVC/6IyW1...FzOeK/f_rfyog5.zip",
            "file_name": "test.zip",
            "file_size": 61123
        }
    }
}'

텍스트 타입이미지 타입동영상 타입

curl -X POST 'https://kakao-api.happytalk.io/kakaoWebhook/v3/bzc/chat/send/plain' \
-H 'Content-Type: application/json' \
-H 'HT-Client-Id: example-id' \
-H 'HT-Client-Secret: example-secret' \
-d '{
    "user_key": "example-user_key",
    "sender_key": "example-sender_key",
    "serial_number": "abc111test",
    "chat_bubble_type": "TEXT",
    "message": "텍스트 타입 테스트입니다."
}'

curl -X POST 'https://kakao-api.happytalk.io/kakaoWebhook/v3/bzc/chat/send/plain' \
-H 'Content-Type: application/json' \
-H 'HT-Client-Id: example-id' \
-H 'HT-Client-Secret: example-secret' \
-d '{
    "user_key": "example-user_key",
    "sender_key": "example-sender_key",
    "serial_number": "abc111test",
    "chat_bubble_type": "IMAGE",
    "attachment": {
        "image": {
            "img_url": "http://dn-m.talk.kakao.com/talkm/o1JvE58GUJ/cdK...2Z1/i_cefivr.jpg"
        }
    }
}'

curl -X POST 'https://kakao-api.happytalk.io/kakaoWebhook/v3/bzc/chat/send/plain' \
-H 'Content-Type: application/json' \
-H 'HT-Client-Id: example-id' \
-H 'HT-Client-Secret: example-secret' \
-d '{
    "user_key": "example-user_key",
    "sender_key": "example-sender_key",
    "serial_number": "abc111test",
    "chat_bubble_type": "FILE", // (이외 VIDEO, AUDIO 타입도 지원)
    "attachment": {
        "file": {
            "file_url": "http://mud-kage.kakao.com/dn/PE6g8/o9HzDSANVC/6IyW1...FzOeK/f_rfyog5.zip",
            "file_name": "test.zip",
            "file_size": 61123
        }
    }
}'

Response (Json)

Parameter

Field Name	Type	Description
code	Text	결과 코드 (0은 정상 / 나머지는 오류)
message	Text	처리 실패 시 결과 메시지
created_at	Text	메시지 발송 후 카카오 DB에 저장된 시각

Example

Success

{
    "code": 0,
    "created_at": "2025-05-09T13:58:20.707"
}

Failure

{
    "code": -510,
    "message": "NoImageException(serialNumber: test-serial-number)"
}

Data Dictionary

Request DictionaryResponse Dictionary

chat_bubble_typeattachmentimagefile

Type	Description
TEXT	텍스트
IMAGE	이미지
VIDEO	비디오 파일
AUDIO	오디오 파일
FILE	일반 파일

Field Name	Type	Description
image	Image	이미지 요소 (Image 발송시 필수)
file	File	파일 요소 (Image를 제외한 파일 발송시 필수)

Field Name	Type	Required	Description
img_url	Text	Y	이미지 업로드 API로 등록한 이미지 URL
img_link	Text(1000)	N	이미지 클릭시 이동할 URL

Field Name	Type	Required	Description
file_url	Text	Y	파일 업로드 API로 등록한 이미지 URL
file_name	Text	N	파일명 - FILE 발송시 필수
file_size	Number	N	파일 크기 - FILE 발송시 필수

None

Reference

코드 정의

Plain 메시지 발송

Endpoint

Introduce

Request (Json)

Header

Body

Example

Response (Json)

Parameter

Example

Data Dictionary

Reference