기존 Dialogflow CX 메신저

기존 Dialogflow CX 메신저 통합은 웹사이트에 삽입할 수 있는 맞춤설정 가능한 에이전트용 채팅 대화상자를 제공합니다. 채팅 대화는 최종 사용자가 열고 닫을 수 있는 대화상자로 구현됩니다. 채팅 대화상자가 열리면 화면 오른쪽 하단의 콘텐츠 위에 표시됩니다.

최신 Dialogflow CX 메신저로 마이그레이션

Dialogflow CX 메신저 최신 버전은 에이전트 쿼리 액세스와 더 많은 사용자 인터페이스 구성 옵션을 제어할 수 있는 인증을 제공합니다. 기존 버전의 모든 사용자가 새 버전으로 마이그레이션하는 것이 좋습니다.

2023년 8월 29일 이전에 Dialogflow CX 메신저 통합을 사용 설정한 경우 기존 버전을 사용하고 있을 수 있습니다. 기존 버전을 사용 중인지 확인하려면 웹사이트에 삽입된 메신저 HTML 코드를 검토하세요. 다음 스크립트가 표시되면 기존 버전을 사용하고 있는 것입니다.

https://www.gstatic.com/dialogflow-console/fast/messenger-cx/bootstrap.js?v=1

새 버전으로 마이그레이션하려면 다음 안내를 따르세요.

  1. 웹사이트에서 모든 HTML, CSS, 자바스크립트 메신저 코드를 삭제합니다.
  2. 최신 Dialogflow CX 메신저 통합 안내를 따르세요.

HTML 맞춤설정

채팅 대화상자가 표시되고 동작하는 방식을 다양한 측면으로 맞춤설정할 수 있습니다. df-messenger HTML 요소에는 다음과 같은 속성이 있습니다.

속성 입력 정책 값
agent-id 필수 에이전트와 연결된 에이전트 ID입니다. 에이전트 ID가 미리 입력되어 있습니다.
chat-icon 선택사항 채팅 대화상자 열기 버튼에 사용되는 아이콘입니다. 기본 아이콘은 대화형 에이전트(Dialogflow CX) 아이콘입니다. 이 필드는 공개 URL이어야 합니다. 아이콘 크기는 36x36픽셀이어야 합니다.
chat-title 필수 채팅 대화상자 상단에 표시되는 제목입니다. 에이전트 이름이 미리 입력되어 있습니다.
df-cx 필수 CX 에이전트와의 상호작용을 나타냅니다. 'true'를 값으로 사용합니다.
expand 선택사항 페이지를 로드할 때 채팅 대화상자가 열리도록 설정하는 부울 속성입니다. 기본적으로 페이지가 로드되면 채팅 대화상자가 닫힙니다.
intent 선택사항 채팅 대화상자가 열릴 때 호출되는 커스텀 이벤트입니다. 이 이벤트에 대해 호출되고 첫 번째 에이전트 메시지를 생성하는 이벤트 핸들러를 사용할 수 있습니다.
language-code 필수 첫 번째 인텐트의 기본 언어 코드입니다. 에이전트의 기본 언어가 미리 입력되어 있습니다.
location 필수 에이전트의 리전입니다.
session-id 선택사항 세션 ID입니다. 이 속성이 제공되지 않으면 통합 시 대화상자마다 고유 ID가 생성됩니다.
user-id 선택사항 여러 세션에서 사용자를 추적하는 데 사용할 수 있습니다. 인텐트 인식 요청의 queryParams.payload.userId 필드를 통해 대화형 에이전트(Dialogflow CX)에 값을 전달할 수 있으며 대화형 에이전트(Dialogflow CX)는 WebhookRequest.payload.userId 필드를 통해 이 값을 제공합니다.
wait-open 선택사항 대화상자가 실제로 열릴 때까지 intent 속성에 정의된 커스텀 이벤트를 지연하는 불리언 속성입니다.

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>

위의 설정은 다음과 같이 표시됩니다.

메신저 스크린샷

JavaScript 이벤트

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
  },
  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 CX)에서 단순 텍스트 응답으로 제공된 것처럼 렌더링합니다.

예를 들면 다음과 같습니다.

const dfMessenger = document.querySelector('df-messenger');
dfMessenger.renderCustomText('Custom text');

renderCustomCard

이 함수는 대화형 에이전트(Dialogflow CX) fulfillment에서 제공된 것처럼 커스텀 카드를 렌더링합니다. 커스텀 페이로드 응답 형식은 Fulfillment 섹션에 정의되어 있습니다.

예를 들면 다음과 같습니다.

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();

Fulfillment

fulfillment를 만들 때 텍스트 응답과 커스텀 페이로드를 만들 수 있습니다. 텍스트 응답은 기본 에이전트 응답에 사용되며 커스텀 페이로드는 서식 있는 응답에 사용됩니다. 모든 응답 유형의 커스텀 페이로드 형식은 다음과 같은 기본 구조입니다.

{
  "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 CX) 이벤트입니다.

예를 들면 다음과 같습니다.

{
  "richContent": [
    [
      {
        "type": "button",
        "icon": {
          "type": "chevron_right",
          "color": "#FF9800"
        },
        "text": "Button text",
        "link": "https://example.com",
        "event": {
          "name": ""
        }
      }
    ]
  ]
}

목록 응답 유형

목록 응답 유형은 사용자가 선택할 수 있는 옵션이 여러 개 있는 카드입니다.

메신저 스크린샷

응답에는 list 및 divider 응답 유형의 배열이 포함됩니다. 다음 표에서는 list 유형을 설명합니다.

이름 유형 설명
type 문자열 응답 유형: 'list'
title 문자열 옵션 제목
subtitle 문자열 옵션 자막
event 객체 옵션을 클릭하면 트리거되는 대화형 에이전트(Dialogflow CX) 이벤트입니다.

다음 표에서는 divider 유형을 설명합니다.

이름 유형 설명
type 문자열 응답 유형: 'divider'

예를 들면 다음과 같습니다.

{
  "richContent": [
    [
      {
        "type": "list",
        "title": "List item 1 title",
        "subtitle": "List item 1 subtitle",
        "event": {
          "name": ""
        }
      },
      {
        "type": "divider"
      },
      {
        "type": "list",
        "title": "List item 2 title",
        "subtitle": "List item 2 subtitle",
        "event": {
          "name": ""
        }
      }
    ]
  ]
}

아코디언 응답 유형

아코디언 응답 유형은 사용자가 클릭하거나 터치하여 더 많은 텍스트를 볼 수 있는 작은 카드입니다.

메신저 스크린샷

다음 표에서는 필드를 설명합니다.

이름 유형 설명
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 CX 메신저의 개별 서식 있는 메시지 요소는 니즈에 맞게 커스텀 카드를 만드는 데 사용될 수 있습니다. 다음은 위에 나열된 요소 중 일부를 사용한 예시입니다.

메신저 스크린샷

{
  "richContent": [
    [
      {
        "type": "image",
        "rawUrl": "https://example.com/images/logo.png",
        "accessibilityText": "Conversational Agents (Dialogflow CX) across platforms"
      },
      {
        "type": "info",
        "title": "Conversational Agents (Dialogflow CX)",
        "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 CX 메신저로 에이전트를 로컬에서 테스트하려면 다음 안내를 따르세요.

  • HTML 맞춤설정 섹션의 설명대로 페이지에 Dialogflow CX 메신저 요소를 삽입합니다.
  • 특정 포트로 페이지의 로컬 HTTP 서버를 시작합니다.
  • http://localhost:port_number에서 페이지에 액세스합니다.