Dialogflow 메신저

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

메신저 스크린샷

제한사항

설정 및 테스트

Dialogflow Messenger를 설정하고 사용 설정하려면 다음 안내를 따르세요.

  1. Dialogflow ES 콘솔로 이동합니다.
  2. 왼쪽 사이드바 메뉴에서 통합을 클릭합니다.
  3. Dialogflow 메신저를 클릭합니다.
  4. 구성 대화상자가 열립니다.
  5. 환경을 선택합니다.
  6. 사용 설정을 클릭합니다.
  7. 웹사이트에 붙여넣을 삽입 코드를 복사합니다.
  8. 사용해 보기를 클릭하여 에이전트를 테스트합니다.
  9. 창 오른쪽 하단에 Dialogflow 로고가 있는 버튼이 표시됩니다. 이 버튼을 클릭합니다.
  10. 상호작용할 수 있는 채팅 대화상자가 열립니다.
  11. 테스트가 완료되면 채팅 대화상자를 닫습니다.
  12. 구성 대화상자에서 닫기를 클릭합니다.

삽입

위에서 복사한 삽입 코드를 웹사이트의 웹페이지에 붙여넣습니다. <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>

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

메신저 스크린샷

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,
    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에서 페이지에 액세스합니다.