Dialogflow 메신저 통합은 웹사이트에 삽입할 수 있는 맞춤설정 가능한 에이전트용 채팅 대화상자를 제공합니다. 채팅 대화는 최종 사용자가 열고 닫을 수 있는 대화상자로 구현됩니다. 채팅 대화상자가 열리면 화면 오른쪽 하단의 콘텐츠 위에 표시됩니다.
제한사항
- 이 통합에서는 기본 에이전트 언어만 지원합니다.
설정 및 테스트
Dialogflow Messenger를 설정하고 사용 설정하려면 다음 안내를 따르세요.
- Dialogflow ES 콘솔로 이동합니다.
- 왼쪽 사이드바 메뉴에서 통합을 클릭합니다.
- Dialogflow 메신저를 클릭합니다.
- 구성 대화상자가 열립니다.
- 환경을 선택합니다.
- 사용 설정을 클릭합니다.
- 웹사이트에 붙여넣을 삽입 코드를 복사합니다.
- 사용해 보기를 클릭하여 에이전트를 테스트합니다.
- 창 오른쪽 하단에 Dialogflow 로고가 있는 버튼이 표시됩니다. 이 버튼을 클릭합니다.
- 상호작용할 수 있는 채팅 대화상자가 열립니다.
- 테스트가 완료되면 채팅 대화상자를 닫습니다.
- 구성 대화상자에서 닫기를 클릭합니다.
삽입
위에서 복사한 삽입 코드를 웹사이트의 웹페이지에 붙여넣습니다.
<script>
및 <df-messenger>
HTML 요소는 페이지의 <body>
요소에 있어야 합니다.
반응형 레이아웃을 허용하려면 페이지에 다음을 추가합니다.
<meta name="viewport" content="width=device-width, initial-scale=1">
HTML 맞춤설정
채팅 대화상자가 표시되고 동작하는 방식을 다양한 측면으로 맞춤설정할 수 있습니다.
df-messenger
HTML 요소에는 다음과 같은 속성이 있습니다.
속성 | 입력 정책 | 값 |
---|---|---|
agent-id |
필수 | Dialogflow 에이전트와 연결된 에이전트 ID입니다. 에이전트 ID가 미리 입력되어 있습니다. |
chat-icon |
선택사항 | 채팅 대화상자 열기 버튼에 사용되는 아이콘입니다. Dialogflow 아이콘이 기본값입니다. 이 필드는 공개 URL이어야 합니다. 아이콘 크기는 36x36픽셀이어야 합니다. |
chat-title |
필수 | 채팅 대화상자 상단에 표시되는 제목입니다. 에이전트 이름이 미리 입력되어 있습니다. |
expand |
선택사항 | 페이지를 로드할 때 채팅 대화상자가 열리도록 설정하는 부울 속성입니다. 기본적으로 페이지가 로드되면 채팅 대화상자가 닫힙니다. |
intent |
선택사항 | 채팅 대화상자가 열릴 때 첫 번째 인텐트를 트리거하는 데 사용되는 이벤트입니다. WELCOME 이벤트가 미리 입력되어 있습니다. |
language-code |
필수 | 첫 번째 인텐트의 기본 언어 코드입니다. 에이전트의 기본 언어가 미리 입력되어 있습니다. |
session-id |
선택사항 | 세션 ID입니다. 이 속성이 제공되지 않으면 통합 시 대화상자마다 고유 ID가 생성됩니다. |
user-id |
선택사항 | 여러 세션에서 사용자를 추적하는 데 사용할 수 있습니다. 인텐트 인식 요청의 queryParams.payload.userId 필드를 통해 Dialogflow에 값을 전달할 수 있습니다. |
wait-open |
선택사항 | 대화상자가 실제로 열릴 때까지 시작 이벤트를 지연하는 부울 속성입니다. |
CSS 맞춤설정
CSS 변수를 설정하여 채팅 대화상자의 스타일을 맞춤설정할 수 있습니다.
다음 CSS 변수가 제공될 수 있습니다.
CSS 변수 | 영향을 받는 속성 |
---|---|
df-messenger-bot-message |
에이전트 메시지의 풍선 배경 색상입니다. |
df-messenger-button-titlebar-color |
플로팅 버튼의 색상과 채팅 대화상자의 제목 표시줄입니다. |
df-messenger-button-titlebar-font-color |
제목 표시줄에 있는 제목의 글꼴 색상입니다. |
df-messenger-chat-background-color |
채팅 대화상자 배경 색상입니다. |
df-messenger-font-color |
메시지 글꼴 색상입니다. |
df-messenger-input-box-color |
텍스트 입력 상자의 배경 색상입니다. |
df-messenger-input-font-color |
텍스트 입력 상자의 글꼴 색상입니다. |
df-messenger-input-placeholder-font-color |
텍스트 입력 상자에 있는 자리표시자 텍스트의 글꼴 색상입니다. |
df-messenger-minimized-chat-close-icon-color |
닫힌 채팅 뷰에 있는 닫기 아이콘의 색상입니다. |
df-messenger-send-icon |
텍스트 입력 상자에 있는 보내기 아이콘의 색상입니다. |
df-messenger-user-message |
사용자 메시지의 풍선 배경 색상입니다. |
예시 코드:
<style>
df-messenger {
--df-messenger-bot-message: #878fac;
--df-messenger-button-titlebar-color: #df9b56;
--df-messenger-chat-background-color: #fafafa;
--df-messenger-font-color: white;
--df-messenger-send-icon: #878fac;
--df-messenger-user-message: #479b3d;
}
</style>
위의 설정은 다음과 같이 표시됩니다.
자바스크립트 이벤트
Dialogflow 메신저는 이벤트 리스너를 만들 수 있는 다양한 이벤트를 트리거합니다.
이러한 이벤트의 이벤트 대상은 df-messenger
요소입니다.
df-messenger
요소에 이벤트 리스너를 추가하려면 다음 자바스크립트 코드를 추가합니다. 여기서 event-type
은 아래에 설명된 이벤트 이름 중 하나입니다.
const dfMessenger = document.querySelector('df-messenger');
dfMessenger.addEventListener('event-type', function (event) {
// Handle event
...
});
지원되는 이벤트 유형은 다음과 같습니다.
df-accordion-clicked
이 이벤트는 사용자가 아코디언 요소를 클릭하면 발생합니다. 이벤트 구조는 다음과 같습니다.
element: {
title: string,
subtitle: string,
image: {
src: {rawUrl: string}
},
text: string
}
df-button-clicked
이 이벤트는 사용자가 버튼 요소를 클릭할 때 발생합니다. 이벤트 구조는 다음과 같습니다.
element: {
icon: {
type: string,
color: string
},
text: string,
link: string,
event: EventInput,
payload: {}
}
df-chip-clicked
이 이벤트는 사용자가 추천 칩을 선택할 때 발생합니다. 이벤트 구조는 다음과 같습니다.
query: string // Text of the suggestion chip that was selected.
df-info-card-clicked
이 이벤트는 최종 사용자가 제목 표시줄의 정보 항목을 클릭하면 발생합니다. 이벤트 구조는 다음과 같습니다.
element: {
title: string,
image: {
src: {rawUrl: string}
},
actionLink: string
}
df-list-element-clicked
이 이벤트는 사용자가 목록에서 항목을 클릭할 때 발생합니다. 이벤트 구조는 다음과 같습니다.
element: {
title: string,
subtitle: string,
image: {
src: {rawUrl}
},
event: {
name: string,
parameters: {},
languageCode: string
},
payload: {}
}
df-messenger-error
이 이벤트는 Dialogflow API가 오류 상태 코드를 전송하면 발생합니다. 이벤트 구조는 다음과 같습니다.
error: {
"error": {
"code": <error_code>,
"message": <error_message>,
"status": <error_status>
}
}
df-messenger-loaded
이 이벤트는 df-messenger
요소가 완전히 로드되고 초기화되면 트리거됩니다.
df-request-sent
이 이벤트는 Dialogflow API에 요청이 생성되면 발생합니다.
이 이벤트는 df-response-received
와 함께 요청 지연 시간을 모니터링하는 데 사용됩니다.
이벤트 구조는 다음과 같습니다.
requestBody: {
"queryParams": {
object(QueryParameters)
},
"queryInput": {
object(QueryInput)
},
"inputAudio": string
}
df-response-received
이 이벤트는 Dialogflow API에서 응답이 수신될 때 발생합니다. 이벤트 구조는 다음과 같습니다.
response: detectIntentResponse
df-user-input-entered
이 이벤트는 최종 사용자가 쿼리를 입력할 때 발생합니다. 이벤트 구조는 다음과 같습니다.
input: string // Text entered by user
자바스크립트 함수
df-messenger
요소는 동작에 영향을 주기 위해 호출할 수 있는 함수를 제공합니다.
renderCustomText
이 함수는 단순 텍스트 메시지를 Dialogflow에서 단순 텍스트 응답으로 제공된 것처럼 렌더링합니다.
예:
const dfMessenger = document.querySelector('df-messenger');
dfMessenger.renderCustomText('Custom text');
renderCustomCard
이 함수는 커스텀 카드를 Dialogflow에서 서식 있는 응답 메시지로 제공된 것처럼 렌더링합니다. 커스텀 페이로드 응답 형식은 서식 있는 응답 메시지 섹션에 정의됩니다.
예:
const dfMessenger = document.querySelector('df-messenger');
const payload = [
{
"type": "info",
"title": "Info item title",
"subtitle": "Info item subtitle",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"actionLink": "https://example.com"
}];
dfMessenger.renderCustomCard(payload);
showMinChat
이 함수는 메시지 목록의 최소 버전을 표시합니다.
예:
const dfMessenger = document.querySelector('df-messenger');
dfMessenger.showMinChat();
리치 응답 메시지
서식 있는 응답 메시지를 만들 때 인텐트의 기본 응답 탭에서 텍스트 응답과 커스텀 페이로드를 만들 수 있습니다. 텍스트 응답은 기본 에이전트 응답에 사용되며 커스텀 페이로드는 서식 있는 응답에 사용됩니다. 모든 응답 유형의 커스텀 페이로드 형식은 다음과 같은 기본 구조입니다.
{
"richContent": [
[
{
"type": "type-id",
...
},
{
"type": "type-id",
...
}
],
[
{
"type": "type-id",
...
},
{
"type": "type-id",
...
}
]
]
}
richContent
값은 외부 배열 한 개와 내부 배열 여러 개를 허용합니다.
내부 배열 내 응답은 단일 시각적 카드에 결합됩니다.
외부 배열에 내부 배열이 여러 개 포함된 경우 내부 배열마다 카드가 여러 개 표시됩니다.
나머지 하위 섹션은 커스텀 페이로드에 구성할 수 있는 다양한 응답 유형을 설명합니다.
정보 응답 유형
정보 응답 유형은 사용자가 클릭하거나 터치할 수 있는 간단한 타이틀 카드입니다.
다음 표에서는 필드를 설명합니다.
이름 | 유형 | 설명 |
---|---|---|
type |
문자열 | 응답 유형: 'info' |
title |
문자열 | 카드 제목 |
subtitle |
문자열 | 카드 자막 |
image |
객체 | 이미지 |
image.src |
객체 | 이미지 소스 |
image.src.rawUrl |
문자열 | 이미지의 공개 URL |
actionLink |
문자열 | 카드 클릭할 때 추적할 URL |
예를 들면 다음과 같습니다.
{
"richContent": [
[
{
"type": "info",
"title": "Info item title",
"subtitle": "Info item subtitle",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"actionLink": "https://example.com"
}
]
]
}
설명 응답 유형
설명 응답 유형은 여러 줄로 구성된 텍스트를 포함할 수 있는 정보 카드입니다.
다음 표에서는 필드를 설명합니다.
이름 | 유형 | 설명 |
---|---|---|
type |
문자열 | 응답 유형: 'description' |
title |
문자열 | 카드 제목 |
text |
array<string> | 각 문자열이 새 줄에 렌더링되는 문자열의 배열 |
예를 들면 다음과 같습니다.
{
"richContent": [
[
{
"type": "description",
"title": "Description title",
"text": [
"This is text line 1.",
"This is text line 2."
]
}
]
]
}
이미지 응답 유형
이미지 응답 유형은 사용자가 클릭하거나 터치할 수 있는 이미지 카드입니다.
다음 표에서는 필드를 설명합니다.
이름 | 유형 | 설명 |
---|---|---|
type |
문자열 | 응답 유형: 'image' |
rawUrl |
문자열 | 이미지의 공개 URL |
accessibilityText |
문자열 | 이미지의 대체 텍스트 |
예를 들면 다음과 같습니다.
{
"richContent": [
[
{
"type": "image",
"rawUrl": "https://example.com/images/logo.png",
"accessibilityText": "Example logo"
}
]
]
}
버튼 응답 유형
버튼 응답 유형은 사용자가 클릭하거나 터치할 수 있는 아이콘이 있는 작은 버튼입니다.
다음 표에서는 필드를 설명합니다.
이름 | 유형 | 설명 |
---|---|---|
type |
문자열 | 응답 유형: 'button' |
icon |
객체 | 버튼용 아이콘 |
icon.type |
문자열 | 머티리얼 아이콘 라이브러리의 아이콘입니다. 기본 아이콘은 화살표입니다. |
icon.color |
문자열 | 색상 16진수 코드 |
text |
문자열 | 버튼 텍스트 |
link |
문자열 | 버튼을 클릭할 때 추적할 URL |
event |
객체 | 버튼을 클릭하면 트리거되는 Dialogflow 이벤트는 EventInput REST 참조를 확인하세요. |
예:
{
"richContent": [
[
{
"type": "button",
"icon": {
"type": "chevron_right",
"color": "#FF9800"
},
"text": "Button text",
"link": "https://example.com",
"event": {
"name": "",
"languageCode": "",
"parameters": {}
}
}
]
]
}
목록 응답 유형
목록 응답 유형은 사용자가 선택할 수 있는 옵션이 여러 개 있는 카드입니다.
응답에는 list
및 divider
응답 유형의 배열이 포함됩니다.
다음 표에서는 list
유형을 설명합니다.
이름 | 유형 | 설명 |
---|---|---|
type |
문자열 | 응답 유형: 'list' |
title |
문자열 | 옵션 제목 |
subtitle |
문자열 | 옵션 자막 |
event |
객체 | 옵션을 클릭하면 트리거되는 Dialogflow 이벤트는 EventInput REST 참조를 확인하세요. |
다음 표에서는 divider
유형을 설명합니다.
이름 | 유형 | 설명 |
---|---|---|
type |
문자열 | 응답 유형: 'divider' |
예를 들면 다음과 같습니다.
{
"richContent": [
[
{
"type": "list",
"title": "List item 1 title",
"subtitle": "List item 1 subtitle",
"event": {
"name": "",
"languageCode": "",
"parameters": {}
}
},
{
"type": "divider"
},
{
"type": "list",
"title": "List item 2 title",
"subtitle": "List item 2 subtitle",
"event": {
"name": "",
"languageCode": "",
"parameters": {}
}
}
]
]
}
아코디언 응답 유형
아코디언 응답 유형은 사용자가 클릭하거나 터치하여 더 많은 텍스트를 볼 수 있는 작은 카드입니다.
다음 표에서는 필드를 설명합니다.
이름 | 유형 | 설명 |
---|---|---|
type |
문자열 | 응답 유형: 'accordion' |
title |
문자열 | 아코디언 제목 |
subtitle |
문자열 | 아코디언 자막 |
image |
객체 | 이미지 |
image.src |
객체 | 이미지 소스 |
image.src.rawUrl |
문자열 | 이미지의 공개 URL |
text |
문자열 | 아코디언 텍스트 |
예를 들면 다음과 같습니다.
{
"richContent": [
[
{
"type": "accordion",
"title": "Accordion title",
"subtitle": "Accordion subtitle",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"text": "Accordion text"
}
]
]
}
추천 칩 응답 유형
추천 칩 응답 유형은 최종 사용자에게 클릭 가능한 추천 칩 목록을 제공합니다.
다음 표에서는 필드를 설명합니다.
이름 | 유형 | 설명 |
---|---|---|
type |
문자열 | 응답 유형: 'chips' |
options |
array<object> | 옵션 객체 배열 |
options[].text |
문자열 | 옵션 텍스트 |
options[].image |
객체 | 옵션 이미지 |
options[].image.src |
객체 | 옵션 이미지 소스 |
options[].image.src.rawUrl |
문자열 | 옵션 이미지의 공개 URL |
options[].link |
문자열 | 옵션 링크 |
예를 들면 다음과 같습니다.
{
"richContent": [
[
{
"type": "chips",
"options": [
{
"text": "Chip 1",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"link": "https://example.com"
},
{
"text": "Chip 2",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"link": "https://example.com"
}
]
}
]
]
}
응답 유형 결합
Dialogflow 메신저의 개별 서식 있는 메시지 요소는 니즈에 맞게 커스텀 카드를 만드는 데 사용될 수 있습니다. 다음은 위에 나열된 요소 중 일부를 사용한 예시입니다.
{
"richContent": [
[
{
"type": "image",
"rawUrl": "https://example.com/images/logo.png",
"accessibilityText": "Dialogflow across platforms"
},
{
"type": "info",
"title": "Dialogflow",
"subtitle": "Build natural and rich conversational experiences",
"actionLink": "https://cloud.google.com/dialogflow/docs"
},
{
"type": "chips",
"options": [
{
"text": "Case Studies",
"link": "https://cloud.google.com/dialogflow/case-studies"
},
{
"text": "Docs",
"link": "https://cloud.google.com/dialogflow/docs"
}
]
}
]
]
}
디버깅
Dialogflow 메신저로 에이전트를 로컬에서 테스트하려면 다음 안내를 따르세요.
- 위 설명처럼 페이지에 Dialogflow 메신저 요소를 삽입합니다.
- 특정 포트로 페이지의 로컬 HTTP 서버를 시작합니다.
http://localhost:port_number
에서 페이지에 액세스합니다.