새로운 메시지 포맷 가이드

Overview

2025-12-31 업데이트 된 contents_type 변경 사항에 대해 설명하는 문서입니다. 신규 타입인 template, 기존 타입 normal에 대한 변경 사항을 설명 합니다.

템플릿 V1/V2 적용 대상 안내

템플릿 V1 업체: Biz API, 아카이브, 상담내역 API, Happytalk Embedded 사용 고객사
→ Data Dictionary(V2)를 참고하여 대응 개발이 필요합니다.
템플릿 V2 업체: 위 조건에 해당하지 않는 고객사

템플릿 V2 유형 사용을 희망하실 경우, 대응 개발 완료 후 해피톡 고객센터로 문의해 주시기 바랍니다.

자세한 내용은 템플릿 타입 전환 안내(~26/06/30) 공지에서 확인하실 수 있습니다.

참고 사항

normal 메시지

기존에 상담사 메시지로 발송되던 normal 메시지도 template 타입으로 발화됩니다. 또한 normal 타입 메시지에 경우 카카오 상담톡에 한해 보안 메시지가 제공됩니다.

보안 메시지 (isLocked)

보안 메시지에 경우 카카오 상담톡에서만 지원됩니다. 이외 채널에서는 일괄 false로 처리됩니다.

normal 타입 추가 사항

1. 보안 메시지

보안 메시지 설명

카카오 상담톡에서 보안 메시지로 발송할 수 있는 기능이며, 채팅v2에서 상담사가 보안 메시지를 활성화 하여 발화 하면 "발송 케이스"에 따라 보안 메시지로 변환되어 발송됩니다.

발송 케이스

발송 케이스 상세

단일 텍스트

입력창에 텍스트만 입력하여 발송할 경우 기존 text 타입에서 normal 타입으로 변경되며 isLocked 필드에 정의된 값이 true로 전달됩니다.

데이터 포맷

데이터 포맷 예시

단일 텍스트

{
    "text": "단일 텍스트 보안 메시지 설정 데이터 예시",
    "image_url": "",
    "link":
    {
        "name":
        [],
        "url":
        []
    },
    "isLocked": true
}

데이터 포맷 필드별 설정

필드별 설정

메시지 포맷Link

필드명	데이터 타입	필수여부	설명
text	text (1000)	Y	메시지 문구
image_url	text(1000)	N	이미지 링크 (보안 메시지에서는 미지원)
link	Link	N	링크 버튼
isLocked	Boolean	Y	보안메시지 발화 여부 (default : false)

필드명	데이터 타입	필수여부	설명
name	String[]	Y	링크 버튼 제목 리스트
url	String[]	Y	링크 버튼 URL 리스트

template 타입 정의

1. TEXT 타입

TEXT 타입 설명

텍스트를 기준으로 구성된 혼합형 메시지 입니다.

메시지 구성 형태

텍스트 + 버튼
텍스트 + 바로 연결 버튼
텍스트 + 버튼 + 바로 연결 버튼

데이터 포맷

TEXT 타입 데이터 포맷

{
    "type": "TEXT",
    "message": "텍스트 + 버튼 + 바로연결",
    "buttonList": [
        {
            "type": "TEXT",
            "name": "챗봇 발화 버튼"
        },
        {
            "type": "WEB_LINK",
            "name": "링크 버튼",
            "pcUrl": "https://www.naver.com",
            "mobileUrl": "https://m.naver.com"
        },
        {
            "type": "COUPON",
            "name": "쿠폰",
            "description": "쿠폰 테스트",
            "pcUrl": "https://www.naver.com",
            "mobileUrl": "https://m.naver.com",
            "schemaAOS": "https://www.naver.com", // 현재는 일반 URL만 지원, 앱 스키마는 추후 지원 예정
            "schemaIOS": "https://www.naver.com"  // 현재는 일반 URL만 지원, 앱 스키마는 추후 지원 예정
        }
    ],
    "quickReplyList": [
        {
            "type": "TEXT",
            "name": "챗봇 발화 버튼"
        },
        {
            "type": "WEB_LINK",
            "name": "링크 버튼",
            "pcUrl": "https://www.naver.com",
            "mobileUrl": "https://m.naver.com"
        }
    ],
    "isLocked": false
}

필드 정의

필드명	데이터 타입	필수여부	설명
type	Type	Y	템플릿 메시지 타입
message	text (1000)	Y	메시지 문구
buttonList	Button[]	N	메시지 버튼
quickReplyList	QuickReply[]	N	바로 연결 버튼
isLocked	Boolean	Y	보안메시지 발화 여부 (default : false)

2. IMAGE 타입

IMAGE 타입 설명

이미지를 포함하여 구성되는 혼합형 메시지 입니다.

메시지 구성 형태

이미지 + 텍스트
이미지 + 텍스트 + 버튼
이미지 + 텍스트 + 바로 연결 버튼
이미지 + 텍스트 + 버튼 + 바로 연결 버튼

데이터 포맷

IMAGE 타입 데이터 포맷

{
    "type": "IMAGE",
    "message": "이미지 + 텍스트 + 버튼 + 바로연결",
    "image": {
        "imageUrl": "https://static.happytalkio.com/이미지_URL_PATH"
    },
    "buttonList": [
        {
            "type": "TEXT",
            "name": "챗봇 발화 버튼"
        },
        {
            "type": "WEB_LINK",
            "name": "링크 버튼",
            "pcUrl": "https://www.naver.com",
            "mobileUrl": "https://m.naver.com"
        },
        {
            "type": "COUPON",
            "name": "쿠폰",
            "description": "쿠폰 테스트",
            "pcUrl": "https://www.naver.com",
            "mobileUrl": "https://m.naver.com",
            "schemaAOS": "https://www.naver.com", // 현재는 일반 URL만 지원, 앱 스키마는 추후 지원 예정
            "schemaIOS": "https://www.naver.com"  // 현재는 일반 URL만 지원, 앱 스키마는 추후 지원 예정
        }
    ],
    "quickReplyList": [
        {
            "type": "TEXT",
            "name": "챗봇 발화 버튼"
        },
        {
            "type": "WEB_LINK",
            "name": "링크 버튼",
            "pcUrl": "https://www.naver.com",
            "mobileUrl": "https://m.naver.com"
        }
    ],
    "isLocked": false
}

필드 정의

필드명	데이터 타입	필수여부	설명
type	Type	Y	템플릿 메시지 타입
message	text (1000)	Y	메시지 문구
image	Image	Y	이미지 정보 필드
buttonList	Button[]	N	메시지 버튼
quickReplyList	QuickReply[]	N	바로 연결 버튼
isLocked	Boolean	Y	보안메시지 발화 여부 (default : false)

3. CAROUSEL 타입

CAROUSEL 타입 설명

혼합형 메시지를 슬라이드 형태로 구성한 메시지 입니다.

메시지 구성 형태

캐러셀
캐러셀 + 바로 연결 버튼

데이터 포맷

CAROUSEL 타입 데이터 포맷

{
    "type": "CAROUSEL",
    "message": "캐러셀 + 바로 연결",
    "carouselBlocks": [
        {
            "header": "캐러셀 1번 헤더",
            "message": "캐러셀 1번 메시지",
            "image": {
                "imageUrl": "https://static.happytalkio.com/이미지_URL_PATH1"
            },
            "buttonList": [
                {
                    "type": "TEXT",
                    "name": "챗봇 발화 버튼"
                },
                {
                    "type": "WEB_LINK",
                    "name": "링크 버튼",
                    "pcUrl": "https://www.naver.com",
                    "mobileUrl": "https://m.naver.com"
                }
            ],
            "coupon": {
                "name": "쿠폰",
                "description": "쿠폰 테스트",
                "pcUrl": "https://www.naver.com",
                "mobileUrl": "https://m.naver.com",
                "schemaAOS": "https://www.naver.com", // 현재는 일반 URL만 지원, 앱 스키마는 추후 지원 예정
                "schemaIOS": "https://www.naver.com"  // 현재는 일반 URL만 지원, 앱 스키마는 추후 지원 예정
            }
        },
        {
            "header": "캐러셀 2번 헤더",
            "message": "캐러셀 2번 메시지",
            "image": {
                "imageUrl": "https://static.happytalkio.com/이미지_URL_PATH2"
            },
            "buttonList": [
                {
                    "type": "TEXT",
                    "name": "챗봇 발화 버튼"
                },
                {
                    "type": "WEB_LINK",
                    "name": "링크 버튼",
                    "pcUrl": "https://www.naver.com",
                    "mobileUrl": "https://m.naver.com"
                }
            ],
            "coupon": {
                "name": "쿠폰",
                "description": "쿠폰 테스트",
                "pcUrl": "https://www.naver.com",
                "mobileUrl": "https://m.naver.com",
                "schemaAOS": "https://www.naver.com", // 현재는 일반 URL만 지원, 앱 스키마는 추후 지원 예정
                "schemaIOS": "https://www.naver.com"  // 현재는 일반 URL만 지원, 앱 스키마는 추후 지원 예정
            }
        }
    ],
    "quickReplyList": [
        {
            "type": "TEXT",
            "name": "챗봇 발화 버튼"
        },
        {
            "type": "WEB_LINK",
            "name": "링크 버튼",
            "pcUrl": "https://www.naver.com",
            "mobileUrl": "https://m.naver.com"
        }
    ],
    "isLocked": false
}

필드 정의

필드명	데이터 타입	필수여부	설명
type	Type	Y	템플릿 메시지 타입
carouselBlocks	Carousel[]	Y	캐러셀 상세 메시지 정의 필드
quickReplyList	QuickReply[]	N	바로 연결 버튼
isLocked	Boolean	Y	보안메시지 발화 여부 (default : false)

Data Dictionary

Template Dictionary

TypeButtonButtonTypeQuickReplyQuickReplyTypeImageCarouselCoupon

타입명	설명
TEXT	텍스트 메시지와 버튼, 바로연결 등 혼합형 메시지를 발화하는 타입
IMAGE	이미지 + 텍스트 메시지와 버튼, 바로연결 등 혼합형 메시지를 발화하는 타입
CAROUSEL	별도의 필드에 메시지를 정의하여 블록을 슬라이드 형태로 보여줄 수 있는 타입

필드명	데이터 타입	필수여부	설명
type	ButtonType	Y	버튼 타입을 정의하는 필드
name	text (30)	Y	버튼 이름
pcUrl	text(1000)	Y/N	PC 환경에서 지정된 URL로 연결 해주는 필드 (ButtonType이 WEB_LINK 일때 필수)
mobileUrl	text(1000)	Y/N	MOBILE 환경에서 지정된 URL로 연결 해주는 필드 (ButtonType이 WEB_LINK 일때 필수)
schemaAOS	text(1000)	N	안드로이드 기기 환경에서 앱스키마를 호출할 수 있는 필드 (추후 지원 예정)
schemaIOS	text(1000)	N	IOS 기기 환경에서 앱스키마를 호출할 수 있는 필드 (추후 지원 예정)

타입명	설명
TEXT	버튼 이름을 발화하는 버튼
WEB_LINK	지정된 URL로 이동 시키는 버튼
COUPON	쿠폰 형태 버튼

필드명	데이터 타입	필수여부	설명
type	QuickReplyType	Y	바로 연결 버튼 타입을 정의하는 필드
name	text (14)	Y	바로 연결 버튼 이름
pcUrl	text(1000)	Y/N	PC 환경에서 지정된 URL로 연결 해주는 필드 (QuickReplyType이 WEB_LINK 일때 필수)
mobileUrl	text(1000)	Y/N	MOBILE 환경에서 지정된 URL로 연결 해주는 필드 (QuickReplyType이 WEB_LINK 일때 필수)

타입명	설명
TEXT	버튼 이름을 발화하는 버튼
WEB_LINK	지정된 URL로 이동 시키는 버튼

필드명	데이터 타입	필수여부	설명
imageUrl	text	Y	해피톡 서버에 업로드된 이미지 URL

필드명	데이터 타입	필수여부	설명
header	text(20)	Y	헤더 문구 필드
message	text(180)	Y	메시지 필드
image	Image	Y	이미지 정보 필드
buttonList	Button[]	N	버튼 필드 정의시 최소 1개, 최대 2개
coupon	Coupon	N	쿠폰 정보 필드

필드명	데이터 타입	필수여부	설명
name	text (30)	Y	쿠폰 이름
description	text (12)	Y	쿠폰 설명
pcUrl	text(1000)	Y	PC 환경에서 지정된 URL로 연결 해주는 필드
mobileUrl	text(1000)	Y	MOBILE 환경에서 지정된 URL로 연결 해주는 필드
schemaAOS	text(1000)	N	안드로이드 기기 환경에서 앱스키마를 호출할 수 있는 필드 (추후 지원 예정)
schemaIOS	text(1000)	N	IOS 기기 환경에서 앱스키마를 호출할 수 있는 필드 (추후 지원 예정)