Membuat webhook

Panduan ini menunjukkan cara menggunakan webhook, sehingga agen Anda dapat menjadi lebih dinamis. Cloud Functions digunakan untuk menghosting webhook karena kesederhanaannya, tetapi ada banyak cara lain untuk menghosting layanan webhook. Contoh ini juga menggunakan bahasa pemrograman Go, tetapi Anda dapat menggunakan bahasa apa pun yang didukung oleh Cloud Functions. Anda tidak perlu mengedit kode untuk panduan ini.

Kode webhook contoh melakukan hal berikut:

  • Membaca nilai parameter dari permintaan webhook.
  • Menulis nilai parameter ke respons webhook.
  • Memberikan respons teks dalam respons webhook.

Sebelum memulai

Jika tidak berencana menggunakan webhook, Anda dapat melewati panduan memulai ini.

Anda harus melakukan hal berikut sebelum membaca panduan ini:

  1. Baca dasar-dasar alur.
  2. Lakukan langkah-langkah penyiapan.
  3. Lakukan langkah-langkah dalam panduan memulai Membangun agen menggunakan alur. Langkah-langkah di bawah ini melanjutkan pekerjaan pada agen yang sama. Jika Anda tidak lagi memiliki agen tersebut, Anda dapat mendownload agen dan memulihkannya.

Membuat Cloud Function

Cloud Functions dapat dibuat dengan Konsol Google Cloud (buka dokumentasi, buka konsol). Untuk membuat fungsi untuk panduan ini:

  1. Penting bahwa agen Dialogflow CX dan fungsi Anda berada dalam project yang sama. Ini adalah cara termudah bagi Dialogflow CX untuk memiliki akses aman ke fungsi Anda. Untuk memilih project, buka pemilih project.
  2. Buka halaman ringkasan Cloud Functions.
  3. Klik Create Function, dan tetapkan kolom berikut:
    • Environment: 1st gen
    • Function name: shirts-agent-webhook
    • Region: Jika Anda menentukan region untuk agen, gunakan region yang sama.
    • Jenis Pemicu HTTP: HTTP
    • URL: Klik tombol salin di sini dan simpan nilainya. Anda akan memerlukan URL ini saat mengonfigurasi webhook.
    • Authentication: Require authentication
    • Require HTTPS: dicentang
  4. Klik Simpan.
  5. Klik Next (Anda tidak memerlukan setelan runtime, build, koneksi, atau keamanan khusus).
  6. Tetapkan kolom berikut:
    • Runtime: Pilih runtime Go terbaru.
    • Source code: Inline Editor
    • Titik entri: HandleWebhookRequest

  7. Ganti kode dengan kode berikut:

    // 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]any `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]any{"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. Klik Deploy.

  9. Tunggu hingga indikator status menunjukkan bahwa fungsi telah berhasil di-deploy. Sambil menunggu, periksa kode yang baru saja Anda deploy. Komentar kode menjelaskan detail penting.

Membuat webhook

Setelah webhook ada sebagai Cloud Function, Anda akan mengaitkan webhook ini dengan agen Anda. Untuk membuat webhook bagi agen Anda:

  1. Buka konsol Dialogflow CX.
  2. Pilih project Google Cloud Anda.
  3. Pilih agen Anda.
  4. Pilih tab Kelola.
  5. Klik Webhook.
  6. Klik Create.
  7. Lengkapi kolom berikut:
    • Display name: shirts-agent-webhook
    • URL Webhook: Berikan URL webhook yang Anda simpan saat membuat fungsi.
    • Subjenis: Standar.
    • Semua kolom lainnya menggunakan nilai default.
  8. Klik Simpan.

Menggunakan webhook

Setelah webhook tersedia untuk agen, Anda akan menggunakan webhook dalam fulfillment. Halaman Order Confirmation memiliki fulfillment entri, yang saat ini memiliki respons teks statis. Untuk memperbarui fulfillment agar menggunakan webhook Anda:

  1. Pilih tab Build.
  2. Klik halaman Order Confirmation untuk meluaskan halaman pada grafik agent builder.
  3. Klik kolom Entry Fulfillment di halaman untuk membuka panel fulfillment.
  4. Hapus respons teks yang ada di bawah judul Agent says. Saat Anda mengarahkan kursor ke teks, tombol hapus akan muncul.
  5. Klik Enable webhook.
  6. Pilih opsi shirts-agent-webhook dari menu dropdown Webhook.
  7. Masukkan confirm untuk kolom Tag.
  8. Klik Simpan.
  9. Tutup panel fulfillment.

Screenshot grafik agen

Kode webhook yang di-deploy mengirimkan respons yang membuat parameter bernama cancel-period. Perbarui agen untuk mereferensikan parameter ini dalam respons agen akhir untuk halaman Order Confirmation yang sama:

  1. Klik rute kondisi yang ditampilkan dengan kondisi true untuk membuka panel rute.
  2. Scroll ke bawah ke bagian Fulfillment di panel rute, lalu tambahkan respons teks berikut di bawah judul Agent says: You can cancel your order within $session.params.cancel-period days. Goodbye.
  3. Klik Simpan.
  4. Tutup panel rute.

Screenshot grafik agen

Menguji agen di simulator

Agen dan webhook Anda siap diuji dengan simulator:

  1. Klik Test Agent.
  2. Masukkan I want to buy a large red shirt dan tekan enter.

Karena Anda memberikan ukuran dan warna, Anda memberi agen semua yang diperlukan untuk membuat pesanan kemeja, sehingga agen langsung beralih ke halaman Order Confirmation.

Screenshot grafik agen

Berikut ini penjelasan tentang respons agen:

Respons Penjelasan
Oke, mari kita mulai pesanan baru. Saat halaman New Order menjadi aktif, fulfillment entri dipanggil. Respons dipicu dari fulfillment ini.
Anda telah memilih kemeja merah berukuran besar. Setelah semua parameter formulir diberikan untuk halaman New Order, rute kondisi yang memeriksa penyelesaian formulir akan dipanggil. Respons dipicu dari fulfillment untuk rute ini. Rute ini juga beralih ke halaman Konfirmasi Pesanan.
Anda dapat mengambil pesanan kemeja merah ukuran besar dalam 5 hari. Fulfillment entri untuk halaman Order Confirmation memanggil webhook. Lihat fungsi confirm dalam kode webhook. Fungsi tersebut membuat respons teks ini, dan menggunakan parameter yang disediakan dalam permintaan webhook.
Anda dapat membatalkan pesanan dalam waktu 2 hari. Selamat tinggal. Halaman Order Confirmation memiliki rute kondisi dengan kondisi yang selalu benar. Respons ini dipicu oleh fulfillment untuk rute tersebut. Perhatikan bahwa respons menggunakan parameter yang ditetapkan oleh webhook dalam respons webhook.
Sebelumnya
Membuat agen menggunakan alur
Berikutnya
Interaksi dengan integrasi