Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Layanan webhook

Untuk menggunakan fulfillment dalam sistem produksi, Anda harus menerapkan dan men-deploy layanan webhook. Untuk menangani fulfillment, layanan webhook Anda harus menerima permintaan JSON dan menampilkan respons JSON seperti yang ditentukan dalam panduan ini. Alur pemrosesan mendetail untuk fulfillment dan webhook dijelaskan dalam Dokumen ringkasan fulfillment.

Persyaratan layanan webhook

Layanan webhook Anda harus memenuhi persyaratan berikut:

Menangani permintaan HTTPS. HTTP tidak didukung. Jika Anda menghosting layanan webhook di Google Cloud menggunakan solusi Compute atau Komputasi Serverless, lihat dokumentasi produk untuk penyajian dengan HTTPS. Untuk opsi hosting lainnya, lihat Mendapatkan sertifikat SSL untuk domain Anda.
Pastikan URL layanan webhook dapat diakses secara publik.
Menangani permintaan POST dengan isi WebhookRequest JSON.
Merespons permintaan WebhookRequest dengan isi WebhookResponse JSON.

Autentikasi

X	Item
Nama pengguna dan sandi login	Untuk setelan webhook, Anda dapat menentukan nilai nama pengguna dan sandi login opsional. Jika diberikan, Dialogflow akan menambahkan header HTTP otorisasi ke permintaan webhook. Header ini memiliki format: `"authorization: Basic <base 64 encoding of the string username:password>"`.
Header autentikasi	Untuk setelan webhook, Anda dapat menentukan pasangan nilai kunci header HTTP opsional. Jika diberikan, Dialogflow akan menambahkan header HTTP ini ke permintaan webhook. Biasanya, satu pasangan diberikan dengan kunci `authorization`.
Autentikasi bawaan Cloud Run Functions	Anda dapat menggunakan autentikasi bawaan saat menggunakan Cloud Run Functions. Untuk menggunakan jenis autentikasi ini, jangan berikan nama pengguna, sandi, atau header otorisasi. Jika Anda memberikan salah satu kolom ini, kolom tersebut tidak akan digunakan untuk autentikasi bawaan.
Token identitas layanan	Anda dapat menggunakan token identitas layanan untuk autentikasi. Jika Anda tidak memberikan nama pengguna login, sandi login, atau header dengan kunci `authorization`, Dialogflow akan otomatis mengasumsikan bahwa token identitas layanan harus digunakan dan menambahkan header HTTP otorisasi ke permintaan webhook. Header ini memiliki format: `"authorization: Bearer <identity token>"`.
Autentikasi TLS bersama	Lihat dokumentasi Autentikasi TLS bersama.

Permintaan webhook

Saat intent yang dikonfigurasi untuk fulfillment cocok, Dialogflow akan mengirimkan permintaan webhook POST HTTPS ke layanan webhook Anda. Isi permintaan ini adalah objek JSON dengan informasi tentang intent yang cocok.

Selain kueri pengguna akhir, banyak integrasi juga mengirimkan informasi tentang pengguna akhir. Misalnya, ID yang secara unik mengidentifikasi pengguna. Informasi ini dapat diakses menggunakan kolom originalDetectIntentRequest dalam permintaan webhook, yang berisi informasi yang dikirim dari platform integrasi.

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi WebhookRequest.

Berikut adalah contoh permintaan:

{
  "responseId": "response-id",
  "session": "projects/project-id/agent/sessions/session-id",
  "queryResult": {
    "queryText": "End-user expression",
    "parameters": {
      "param-name": "param-value"
    },
    "allRequiredParamsPresent": true,
    "fulfillmentText": "Response configured for matched intent",
    "fulfillmentMessages": [
      {
        "text": {
          "text": [
            "Response configured for matched intent"
          ]
        }
      }
    ],
    "outputContexts": [
      {
        "name": "projects/project-id/agent/sessions/session-id/contexts/context-name",
        "lifespanCount": 5,
        "parameters": {
          "param-name": "param-value"
        }
      }
    ],
    "intent": {
      "name": "projects/project-id/agent/intents/intent-id",
      "displayName": "matched-intent-name"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en"
  },
  "originalDetectIntentRequest": {}
}

Respons webhook

Setelah menerima permintaan, webhook Anda harus mengirimkan respons. Isi respons ini adalah objek JSON yang berisi informasi berikut:

Respons yang ditampilkan Dialogflow kepada pengguna akhir.
Pembaruan pada konteks yang aktif untuk percakapan.
Peristiwa tindak lanjut untuk memicu pencocokan intent.
Payload kustom yang akan dikirim ke integrasi atau klien deteksi intent.

Batasan berikut berlaku untuk respons Anda:

Berikan respons dalam waktu 10 detik untuk aplikasi Asisten Google atau 5 detik untuk aplikasi lain; jika tidak, waktu tunggu permintaan akan habis.
Batasi ukuran respons maksimal 64 KiB.

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi WebhookResponse.

Respons teks

Berikut adalah contoh respons teks:

{
  "fulfillmentMessages": [
    {
      "text": {
        "text": [
          "Text response from webhook"
        ]
      }
    }
  ]
}

Respons kartu

Berikut adalah contoh respons kartu:

{
  "fulfillmentMessages": [
    {
      "card": {
        "title": "card title",
        "subtitle": "card text",
        "imageUri": "https://example.com/images/example.png",
        "buttons": [
          {
            "text": "button text",
            "postback": "https://example.com/path/for/end-user/to/follow"
          }
        ]
      }
    }
  ]
}

Respons Asisten Google

Berikut adalah contoh respons Asisten Google:

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "this is a Google Assistant response"
            }
          }
        ]
      }
    }
  }
}

Konteks

Berikut adalah contoh yang menetapkan konteks output:

{
  "fulfillmentMessages": [
    {
      "text": {
        "text": [
          "Text response from webhook"
        ]
      }
    }
  ],
  "outputContexts": [
    {
      "name": "projects/project-id/agent/sessions/session-id/contexts/context-name",
      "lifespanCount": 5,
      "parameters": {
        "param-name": "param-value"
      }
    }
  ]
}

Acara

Berikut adalah contoh yang memanggil peristiwa kustom:

{
  "followupEventInput": {
    "name": "event-name",
    "languageCode": "en-US",
    "parameters": {
      "param-name": "param-value"
    }
  }
}

Entity sesi

Berikut adalah contoh yang menetapkan entity sesi:

{
  "fulfillmentMessages": [
    {
      "text": {
        "text": [
          "Choose apple or orange"
        ]
      }
    }
  ],
  "sessionEntityTypes":[
    {
      "name":"projects/project-id/agent/sessions/session-id/entityTypes/fruit",
      "entities":[
        {
          "value":"APPLE_KEY",
          "synonyms":[
            "apple",
            "green apple",
            "crabapple"
          ]
        },
        {
          "value":"ORANGE_KEY",
          "synonyms":[
            "orange"
          ]
        }
      ],
      "entityOverrideMode":"ENTITY_OVERRIDE_MODE_OVERRIDE"
    }
  ]
}

Payload kustom

Berikut adalah contoh yang menyediakan payload kustom:

{
  "fulfillmentMessages": [
    {
      "payload": {
        "facebook": { // for Facebook Messenger integration
          "attachment": {
            "type": "",
            "payload": {}
          }
        },
        "slack": { // for Slack integration
          "text": "",
          "attachments": []
        },
        "richContent": [ // for Dialogflow Messenger integration
          [
            {
              "type": "image",
              "rawUrl": "https://example.com/images/logo.png",
              "accessibilityText": "Example logo"
            }
          ]
        ],
        // custom integration payload here
      }
    }
  ]
}

Mengaktifkan dan mengelola fulfillment

Untuk mengaktifkan dan mengelola fulfillment bagi agen Anda dengan konsol:

Buka konsol Dialogflow ES.
Pilih agen.
Pilih Fulfillment di menu sidebar.
Alihkan kolom Webhook ke Enabled.
Berikan detail untuk layanan webhook Anda dalam formulir. Jika webhook Anda tidak memerlukan autentikasi, kosongkan kolom autentikasi.
Klik Simpan.

Screenshot pengaktifan fulfillment.

Untuk mengaktifkan dan mengelola fulfillment bagi agen Anda dengan API, lihat referensi agen. Metode getFulfillment dan updateFulfillment memungkinkan Anda mengelola setelan fulfillment.

Untuk mengaktifkan fulfillment untuk intent dengan konsol:

Pilih Intents di menu sidebar kiri.
Pilih intent.
Buka bagian Fulfillment.
Aktifkan Enable webhook call for this intent.
Klik Simpan.

Untuk mengaktifkan fulfillment untuk intent dengan API, lihat referensi intent dan tetapkan kolom webhookState ke WEBHOOK_STATE_ENABLED.

Error webhook

Jika layanan webhook mengalami error, layanan tersebut akan menampilkan salah satu kode status HTTP berikut:

400: Permintaan tidak valid
401: Unauthorized
403: Terlarang
404: Tidak ditemukan
500: Error server internal
503: Layanan tidak tersedia

Dalam salah satu situasi error berikut, Dialogflow merespons pengguna akhir dengan respons bawaan yang dikonfigurasi untuk intent yang cocok:

Waktu tunggu respons terlampaui.
Kode status error diterima.
Respons tidak valid.
Layanan webhook tidak tersedia.

Selain itu, jika panggilan API deteksi intent memicu pencocokan intent, kolom status dalam respons deteksi intent akan berisi informasi error webhook. Contoh:

"status": {
    "code": 206,
    "message": "Webhook call failed. <details of the error...>"
}

Percobaan ulang otomatis

Dialogflow ES menyertakan mekanisme internal yang otomatis mencoba ulang pada error webhook tertentu untuk meningkatkan ketahanan. Hanya error non-terminal yang dicoba ulang, seperti error waktu tunggu atau koneksi.

Untuk mengurangi kemungkinan panggilan duplikat:

Tetapkan nilai minimum waktu tunggu webhook yang lebih lama.
Dukung idempotensi dalam logika webhook Anda atau hapus duplikat permintaan.

Menggunakan Cloud Run Functions

Anda dapat menggunakan fungsi Cloud Run untuk fulfillment dengan beberapa cara. Editor inline Dialogflow terintegrasi dengan Cloud Run Functions. Saat Anda menggunakan editor inline untuk membuat dan mengedit kode webhook, Dialogflow akan membuat koneksi yang aman ke Cloud Function Anda.

Anda juga dapat menggunakan Cloud Function yang tidak dibuat oleh editor inline. Jika Cloud Function berada dalam project yang sama dengan agen, agen Anda dapat memanggil webhook tanpa memerlukan konfigurasi khusus.

Namun, Anda harus menyiapkan integrasi ini secara manual dalam dua situasi berikut:

Akun layanan Agen Layanan Dialogflow dengan alamat berikut harus ada untuk project agen Anda:
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
Akun layanan khusus ini dan kunci terkait biasanya dibuat secara otomatis saat Anda membuat agen pertama untuk sebuah project. Jika agen Anda dibuat sebelum 10 Mei 2021, Anda mungkin perlu memicu pembuatan akun layanan khusus ini dengan cara berikut:
1. Buat agen baru untuk project.
2. Jalankan perintah berikut:
```
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
```
Jika fungsi webhook Anda berada di project yang berbeda dengan agen, Anda harus memberikan peran IAM Invoker Cloud Functions ke akun layanan Agen Layanan Dialogflow di project fungsi Anda.

Token identitas layanan

Saat Dialogflow memanggil webhook, Dialogflow memberikan token Google Identity bersama permintaan. Webhook apa pun dapat secara opsional memvalidasi token menggunakan library klien Google atau library open source seperti github.com/googleapis/google-auth-library-nodejs. Misalnya, Anda dapat memverifikasi email token ID sebagai:

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

Sampel

Contoh berikut menunjukkan cara menerima WebhookRequest dan mengirim WebhookResponse. Contoh ini menggunakan intent yang dibuat di panduan memulai.

Go

Untuk melakukan autentikasi ke Dialogflow CX, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

type intent struct {
	DisplayName string `json:"displayName"`
}

type queryResult struct {
	Intent intent `json:"intent"`
}

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

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

// 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://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookRequest
type webhookRequest struct {
	Session     string      `json:"session"`
	ResponseID  string      `json:"responseId"`
	QueryResult queryResult `json:"queryResult"`
}

// 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://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookResponse
type webhookResponse struct {
	FulfillmentMessages []message `json:"fulfillmentMessages"`
}

// welcome creates a response for the welcome intent.
func welcome(request webhookRequest) (webhookResponse, error) {
	response := webhookResponse{
		FulfillmentMessages: []message{
			{
				Text: text{
					Text: []string{"Welcome from Dialogflow Go Webhook"},
				},
			},
		},
	}
	return response, nil
}

// getAgentName creates a response for the get-agent-name intent.
func getAgentName(request webhookRequest) (webhookResponse, error) {
	response := webhookResponse{
		FulfillmentMessages: []message{
			{
				Text: text{
					Text: []string{"My name is Dialogflow Go Webhook"},
				},
			},
		},
	}
	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)

	// Call intent handler
	switch intent := request.QueryResult.Intent.DisplayName; intent {
	case "Default Welcome Intent":
		response, err = welcome(request)
	case "get-agent-name":
		response, err = getAgentName(request)
	default:
		err = fmt.Errorf("Unknown intent: %s", intent)
	}
	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
	}
}

Java

Untuk melakukan autentikasi ke Dialogflow CX, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.


// TODO: add GSON dependency to Pom file
// (https://mvnrepository.com/artifact/com.google.code.gson/gson/2.8.5)
// TODO: Uncomment the line bellow before running cloud function
// package com.example;

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.BufferedWriter;

public class Example implements HttpFunction {

  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonParser parser = new JsonParser();
    Gson gson = new GsonBuilder().create();

    JsonObject job = gson.fromJson(request.getReader(), JsonObject.class);
    String str =
        job.getAsJsonObject("queryResult")
            .getAsJsonObject("intent")
            .getAsJsonPrimitive("displayName")
            .toString();
    JsonObject o = null;
    String a = '"' + "Default Welcome Intent" + '"';
    String b = '"' + "get-agent-name" + '"';
    String responseText = "";

    if (str.equals(a)) {
      responseText = '"' + "Hello from a Java GCF Webhook" + '"';
    } else if (str.equals(b)) {
      responseText = '"' + "My name is Flowhook" + '"';
    } else {
      responseText = '"' + "Sorry I didn't get that" + '"';
    }

    o =
        parser
            .parse(
                "{\"fulfillmentMessages\": [ { \"text\": { \"text\": [ "
                    + responseText
                    + " ] } } ] }")
            .getAsJsonObject();

    BufferedWriter writer = response.getWriter();
    writer.write(o.toString());
  }
}

Node.js

Untuk melakukan autentikasi ke Dialogflow CX, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

const functions = require('@google-cloud/functions-framework');

// TODO: Add handleWebhook to 'Entry point' in the Google Cloud Function
functions.http('handleWebhook', (request, response) => {
  const tag = request.body.queryResult.intent.displayName;

  let jsonResponse = {};
  if (tag === 'Default Welcome Intent') {
    //fulfillment response to be sent to the agent if the request tag is equal to "welcome tag"
    jsonResponse = {
      fulfillment_messages: [
        {
          text: {
            //fulfillment text response to be sent to the agent
            text: ['Hello from a GCF Webhook'],
          },
        },
      ],
    };
  } else if (tag === 'get-name') {
    //fulfillment response to be sent to the agent if the request tag is equal to "welcome tag"
    jsonResponse = {
      fulfillment_messages: [
        {
          text: {
            //fulfillment text response to be sent to the agent
            text: ['My name is Flowhook'],
          },
        },
      ],
    };
  } else {
    jsonResponse = {
      //fulfillment text response to be sent to the agent if there are no defined responses for the specified tag
      fulfillment_messages: [
        {
          text: {
            ////fulfillment text response to be sent to the agent
            text: [
              `There are no fulfillment responses defined for "${tag}"" tag`,
            ],
          },
        },
      ],
    };
  }
  response.send(jsonResponse);
});

Python

Untuk melakukan autentikasi ke Dialogflow CX, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

# TODO: change the default Entry Point text to handleWebhook
import functions_framework


@functions_framework.http
def handleWebhook(request):
    req = request.get_json()

    responseText = ""
    intent = req["queryResult"]["intent"]["displayName"]

    if intent == "Default Welcome Intent":
        responseText = "Hello from a GCF Webhook"
    elif intent == "get-agent-name":
        responseText = "My name is Flowhook"
    else:
        responseText = f"There are no fulfillment responses defined for Intent {intent}"

    # You can also use the google.cloud.dialogflowcx_v3.types.WebhookRequest protos instead of manually writing the json object
    res = {"fulfillmentMessages": [{"text": {"text": [responseText]}}]}

    return res

Sebelumnya

Editor sebaris

Berikutnya

Webhook untuk pengisian slot

Layanan webhook Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Persyaratan layanan webhook

Autentikasi

Permintaan webhook

Respons webhook

Respons teks

Respons kartu

Respons Asisten Google

Konteks

Acara

Entity sesi

Payload kustom

Mengaktifkan dan mengelola fulfillment

Error webhook

Percobaan ulang otomatis

Menggunakan Cloud Run Functions

Token identitas layanan

Sampel

Go

Java

Node.js

Python

Layanan webhook