기존 Dialogflow 메신저

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

새 Dialogflow 메신저로 마이그레이션

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

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

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

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

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

HTML 맞춤설정

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

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

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

메신저 스크린샷

자바스크립트 이벤트

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

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

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

`renderCustomCard`

이 함수는 Dialogflow 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 이벤트입니다.

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

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

다음 표에서는 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`	문자열	옵션 링크

응답 유형 결합

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

기존 Dialogflow 메신저

새 Dialogflow 메신저로 마이그레이션

HTML 맞춤설정

CSS 맞춤설정

자바스크립트 이벤트

df-accordion-clicked

df-button-clicked

df-chip-clicked

df-info-card-clicked

df-list-element-clicked

df-messenger-error

df-messenger-loaded

df-request-sent

df-response-received

df-user-input-entered

자바스크립트 함수

renderCustomText

renderCustomCard

showMinChat

Fulfillment

정보 응답 유형

설명 응답 유형

이미지 응답 유형

버튼 응답 유형

목록 응답 유형

아코디언 응답 유형

추천 칩 응답 유형

응답 유형 결합

디버깅

`df-accordion-clicked`

`df-button-clicked`

`df-chip-clicked`

`df-info-card-clicked`

`df-list-element-clicked`

`df-messenger-error`

`df-messenger-loaded`

`df-request-sent`

`df-response-received`

`df-user-input-entered`

`renderCustomText`

`renderCustomCard`

`showMinChat`