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 yang dapat Anda gunakan untuk menghosting layanan webhook. Contoh ini juga menggunakan bahasa pemrograman Go, tetapi Anda dapat menggunakan bahasa yang didukung oleh Cloud Functions. Anda tidak perlu mengedit kode untuk panduan ini.

Contoh kode webhook 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 di panduan memulai Membangun agen menggunakan alur. Langkah-langkah di bawah ini akan terus berfungsi pada agen yang sama. Jika Anda tidak lagi memiliki agen tersebut, Anda dapat mendownload agen dan memulihkannya.

Buat Cloud Function

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

  1. Agen Dialogflow CX dan fungsi harus berada dalam project yang sama. Cara ini adalah cara termudah bagi Dialogflow CX untuk memiliki akses aman ke fungsi Anda. Untuk memilih project Anda, buka pemilih project.
  2. Buka halaman ringkasan Cloud Functions.
  3. Klik Create Function, lalu tetapkan kolom berikut:
    • Environment: Generasi ke-1
    • Nama fungsi: 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.
    • Autentikasi: Wajibkan autentikasi
    • Wajibkan HTTPS: dicentang
  4. Klik Simpan.
  5. Klik Berikutnya (Anda tidak memerlukan setelan runtime, build, koneksi, atau keamanan khusus).
  6. Tetapkan kolom berikut:
    • Runtime: Pilih runtime Go terbaru.
    • Kode sumber: Editor Inline
    • Entry point: 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.

Buat webhook

Setelah webhook ada sebagai Cloud Function, Anda akan mengaitkan webhook ini dengan agen Anda. Untuk membuat webhook untuk 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:
    • Nama tampilan: shirts-agent-webhook
    • Webhook URL: Berikan URL webhook yang Anda simpan saat membuat fungsi.
    • Subtype: Standard.
    • Semua kolom lainnya menggunakan nilai default.
  8. Klik Simpan.

Menggunakan webhook

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

  1. Pilih tab Build.
  2. Klik halaman Konfirmasi Pesanan untuk meluaskan halaman pada grafik pembuat agen.
  3. Klik kolom Pemenuhan Entri di halaman untuk membuka panel pemenuhan.
  4. Hapus respons teks yang ada di bagian 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 pemenuhan.

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 Konfirmasi Pesanan yang sama:

  1. Klik rute kondisi yang ditampilkan dengan kondisi true untuk membuka panel rute.
  2. Scroll ke bawah ke bagian Pemenuhan di panel rute, lalu tambahkan respons teks berikut di bagian judul Agen mengatakan: 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, lalu tekan enter.

Karena Anda memberikan ukuran dan warna, agen memiliki semua yang diperlukan untuk membuat pesanan kemeja, sehingga agen akan langsung beralih ke halaman Konfirmasi Pesanan.

Screenshot grafik agen

Berikut ini deskripsi respons agen:

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