빠른 시작: 웹훅 만들기

이 가이드에서는 에이전트를 보다 동적으로 사용할 수 있도록 웹훅을 사용하는 방법을 보여줍니다. Cloud Functions는 단순성으로 인해 웹훅을 호스팅하는 데 사용되지만 웹훅 서비스를 호스팅할 수 있는 여러 다른 방법이 있습니다. 또한 이 예시에서 Go 프로그래밍 언어가 사용되지만 Cloud Functions에서 지원되는 모든 언어를 사용할 수 있습니다. 이 가이드의 코드는 수정할 필요가 없습니다.

예시 웹훅 코드는 다음을 수행합니다.

  • 웹훅 요청에서 매개변수 값 읽기
  • 웹훅 응답에 매개변수 값 쓰
  • 웹훅 응답에 텍스트 응답 제공하기

시작하기 전에

웹훅을 사용할 생각이 없다면 이 빠른 시작을 건너 뛰어도 됩니다.

이 가이드를 읽기 전에 다음을 수행해야 합니다.

  1. Dialogflow CX 기본사항 읽기
  2. 설정 단계 수행하기
  3. 에이전트 빌드 빠른 시작 가이드의 단계 수행하기. 아래 단계는 동일한 에이전트에서 계속 작동합니다. 해당 에이전트가 더 이상 없다면 에이전트를 다운로드하여 복원할 수 있습니다.

Cloud 함수 만들기

Cloud 함수는 Google Cloud 콘솔로 만들 수 있습니다(문서 보기, 콘솔 열기). 이 가이드에 사용할 함수를 만들려면 다음 안내를 따르세요.

  1. Dialogflow CX 에이전트 및 함수가 모두 동일한 프로젝트에 있어야 합니다. 이것은 Dialogflow CX의 함수 보안 액세스를 위한 가장 쉬운 방법입니다. 프로젝트를 선택하려면 프로젝트 선택기로 이동합니다.
  2. Cloud Functions 개요 페이지로 이동하세요.
  3. 함수 만들기를 클릭하고 다음 입력란을 설정합니다.
    • 환경: 1세대
    • 함수 이름: shirts-agent-webhook
    • 리전: 에이전트에 리전을 지정한 경우 동일한 리전 사용
    • HTTP 트리거 유형: HTTP
    • URL: 여기에서 복사 버튼을 클릭하고 값을 저장합니다. 웹훅을 구성할 때 이 URL이 필요합니다.
    • 인증: 인증 필요
    • HTTPS 필요: 체크됨
  4. 저장을 클릭합니다.
  5. 다음를 클릭합니다(특수 런타임, 빌드, 연결, 보안 설정은 필요하지 않음).
  6. 다음 입력란을 설정합니다.
    • 런타임: 최신 Go 런타임 선택
    • 소스 코드: 인라인 편집기
    • 진입점: HandleWebhookRequest

  7. 코드를 다음으로 바꿉니다.

    // Package cxwh contains an example Dialogflow CX webhook
package cxwh

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
)

type fulfillmentInfo struct {
	Tag string `json:"tag"`
}

type sessionInfo struct {
	Session    string                 `json:"session"`
	Parameters map[string]interface{} `json:"parameters"`
}

type text struct {
	Text []string `json:"text"`
}

type responseMessage struct {
	Text text `json:"text"`
}

type fulfillmentResponse struct {
	Messages []responseMessage `json:"messages"`
}

// webhookRequest is used to unmarshal a WebhookRequest JSON object. Note that
// not all members need to be defined--just those that you need to process.
// As an alternative, you could use the types provided by the Dialogflow protocol buffers:
// https://pkg.go.dev/google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3#WebhookRequest
type webhookRequest struct {
	FulfillmentInfo fulfillmentInfo `json:"fulfillmentInfo"`
	SessionInfo     sessionInfo     `json:"sessionInfo"`
}

// webhookResponse is used to marshal a WebhookResponse JSON object. Note that
// not all members need to be defined--just those that you need to process.
// As an alternative, you could use the types provided by the Dialogflow protocol buffers:
// https://pkg.go.dev/google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3#WebhookResponse
type webhookResponse struct {
	FulfillmentResponse fulfillmentResponse `json:"fulfillmentResponse"`
	SessionInfo         sessionInfo         `json:"sessionInfo"`
}

// confirm handles webhook calls using the "confirm" tag.
func confirm(request webhookRequest) (webhookResponse, error) {
	// Create a text message that utilizes the "size" and "color"
	// parameters provided by the end-user.
	// This text message is used in the response below.
	t := fmt.Sprintf("You can pick up your order for a %s %s shirt in 5 days.",
		request.SessionInfo.Parameters["size"],
		request.SessionInfo.Parameters["color"])

	// Create session parameters that are populated in the response.
	// The "cancel-period" parameter is referenced by the agent.
	// This example hard codes the value 2, but a real system
	// might look up this value in a database.
	p := map[string]interface{}{"cancel-period": "2"}

	// Build and return the response.
	response := webhookResponse{
		FulfillmentResponse: fulfillmentResponse{
			Messages: []responseMessage{
				{
					Text: text{
						Text: []string{t},
					},
				},
			},
		},
		SessionInfo: sessionInfo{
			Parameters: p,
		},
	}
	return response, nil
}

// handleError handles internal errors.
func handleError(w http.ResponseWriter, err error) {
	w.WriteHeader(http.StatusInternalServerError)
	fmt.Fprintf(w, "ERROR: %v", err)
}

// HandleWebhookRequest handles WebhookRequest and sends the WebhookResponse.
func HandleWebhookRequest(w http.ResponseWriter, r *http.Request) {
	var request webhookRequest
	var response webhookResponse
	var err error

	// Read input JSON
	if err = json.NewDecoder(r.Body).Decode(&request); err != nil {
		handleError(w, err)
		return
	}
	log.Printf("Request: %+v", request)

	// Get the tag from the request, and call the corresponding
	// function that handles that tag.
	// This example only has one possible tag,
	// but most agents would have many.
	switch tag := request.FulfillmentInfo.Tag; tag {
	case "confirm":
		response, err = confirm(request)
	default:
		err = fmt.Errorf("Unknown tag: %s", tag)
	}
	if err != nil {
		handleError(w, err)
		return
	}
	log.Printf("Response: %+v", response)

	// Send response
	if err = json.NewEncoder(w).Encode(&response); err != nil {
		handleError(w, err)
		return
	}
}

  8. 배포를 클릭합니다.

  9. 상태 표시기에 함수가 성공적으로 배포된 것으로 표시될 때까지 기다립니다. 기다리는 동안 바로 전에 배포한 코드를 검사합니다. 코드 주석에는 중요한 세부정보가 기술되어 있습니다.

웹훅 만들기

이제 웹훅이 Cloud 함수로 존재하므로, 이 웹훅을 에이전트에 연결합니다. 에이전트에 대해 웹훅을 만들려면 다음 안내를 따르세요.

  1. Dialogflow CX 콘솔을 엽니다.
  2. Google Cloud 프로젝트를 선택합니다.
  3. 에이전트를 선택합니다.
  4. 관리 탭을 선택합니다.
  5. 웹훅을 클릭합니다.
  6. 만들기를 클릭합니다.
  7. 다음 입력란을 작성하세요.
    • 표시 이름: shirts-agent-webhook
    • 웹훅 URL: 함수를 만들 때 저장한 웹훅 URL
    • 하위유형: 표준
    • 다른 모든 필드는 기본값 사용
  8. 저장을 클릭합니다.

웹훅 사용

이제 웹훅이 에이전트에 제공되었으므로 fulfillment에서 웹훅을 사용합니다. 주문 확인 페이지에는 현재 정적 텍스트 응답이 있는 항목 fulfillment가 있습니다. 웹훅을 사용하도록 fulfillment를 업데이트하려면 다음 안내를 따르세요.

  1. 빌드 탭을 선택합니다.
  2. 주문 확인 페이지를 클릭하여 에이전트 빌더 그래프에서 페이지를 확장합니다.
  3. 페이지에서 항목 Fulfillment 필드를 클릭하여 fulfillment 패널을 엽니다.
  4. 에이전트 말하기 제목 아래에서 기존 텍스트 응답을 삭제합니다. 텍스트 위로 마우스를 가져가면 삭제 버튼이 표시됩니다.
  5. 웹훅 사용을 클릭합니다.
  6. 웹훅 드롭다운 메뉴에서 shirts-agent-webhook 옵션을 선택합니다.
  7. 태그 필드에 confirm을 입력합니다.
  8. 저장을 클릭합니다.
  9. fulfillment 패널을 닫습니다.

에이전트 그래프 스크린샷

배포된 웹훅 코드는 cancel-period라는 매개변수를 만드는 응답을 보냅니다. 동일한 주문 확인 페이지의 최종 에이전트 응답에서 이 매개변수를 참조하도록 에이전트를 업데이트하세요.

  1. true과 함께 표시된 조건 경로를 클릭하여 경로 패널을 엽니다.
  2. 경로 패널의 Fulfillment 섹션까지 아래로 스크롤하고 에이전트 말하기 제목 아래에 다음 텍스트 응답을 추가하세요. You can cancel your order within $session.params.cancel-period days. Goodbye.
  3. 저장을 클릭합니다.
  4. 경로 패널을 닫습니다.

에이전트 그래프 스크린샷

시뮬레이터에서 에이전트 테스트

에이전트 및 웹훅을 시뮬레이터로 테스트할 준비가 되었습니다.

  1. 에이전트 테스트를 클릭합니다.
  2. I want to buy a large red shirt를 입력하고 Enter 키를 누릅니다.

사이즈와 색상을 모두 제공하여 에이전트에서 셔츠 주문을 생성하는 데 필요한 모든 것을 제공했으므로 주문 확인 페이지로 바로 전환됩니다.

에이전트 그래프 스크린샷

다음은 에이전트 응답에 대한 설명입니다.

응답 설명
이제 새 주문을 시작합시다. 새 주문 페이지가 활성화되었으면 항목 fulfillment가 호출되었습니다. 이 fulfillment에서 응답이 트리거되었습니다.
사용자는 큰 빨간색 셔츠를 선택했습니다. 새 주문 페이지에 대해 모든 양식 매개변수가 제공되었으면 양식 작성을 위한 조건 경로 검사가 호출됩니다. 응답은 이 경로의 fulfillment에서 트리거되었습니다. 이 경로도 주문 확인 페이지로 전환됩니다.
5일 이내에 라지 사이즈의 빨간색 셔츠를 수령할 수 있습니다. 주문 확인 페이지의 항목 fulfillment가 웹훅을 호출합니다. 웹훅 코드에서 confirm 함수를 참조하세요. 이 함수는 이 텍스트 응답을 만들고 웹훅 요청에 제공된 매개변수를 사용합니다.
2일 이내에 주문을 취소할 수 있습니다. 감사합니다. 주문 확인 페이지에는 항상 true인 조건을 갖는 조건 경로가 있습니다. 이 응답은 해당 경로에 대해 fulfillment에 의해 트리거되었습니다. 응답은 웹훅 응답에서 웹훅으로 설정된 매개변수를 사용할 수 있습니다.
이전
에이전트 빌드
다음
통합으로 상호작용