Mengimplementasikan webhook

Panduan ini menyediakan berbagai contoh untuk menerapkan webhook serta rekomendasi pemecahan masalah webhook.

Menetapkan parameter sesi

Contoh berikut menunjukkan cara menetapkan parameter sesi.

Go

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

Lihat Memulai cepat webhook.

Java

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

// TODO: Change class name to Example
// TODO: Uncomment the line below 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 java.io.BufferedWriter;

public class WebhookConfigureSessionParameters implements HttpFunction {
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject orderParameter = new JsonObject();
    orderParameter.addProperty("order_number", "12345");

    JsonObject parameterObject = new JsonObject();
    parameterObject.add("parameters", orderParameter);

    // Creates webhook response object
    JsonObject webhookResponse = new JsonObject();
    webhookResponse.add("session_info", parameterObject);

    Gson gson = new GsonBuilder().setPrettyPrinting().create();
    String jsonResponseObject = gson.toJson(webhookResponse);

    /** { "session_info": { "parameters": { "order_number": "12345" } } } */
    BufferedWriter writer = response.getWriter();
    // Sends the webhookResponseObject
    writer.write(jsonResponseObject.toString());
  }
}

Node.js

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

functions.http('configureSessionParams', (request, response) => {
  // Session parameter configured by the webhook
  const orderNumber = 123;

  const jsonResponse = {
    sessionInfo: {
      parameters: {
        orderNumber: orderNumber,
      },
    },
  };

  response.send(jsonResponse);
});

Python

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

import functions_framework

# TODO (developer): change entry point to configure_session_params in Cloud Function

@functions_framework.http
def configure_session_params(request):
    """Webhook to validate or configure new session parameters."""

    order_number = 123

    json_response = {
        "sessionInfo": {
            "parameters": {
                "orderNumber": order_number,
            },
        },
    }

    return json_response

Menampilkan respons fulfillment

Contoh berikut menunjukkan cara menampilkan respons fulfillment.

Catatan: Sebaiknya tetapkan parameter sesi, bukan respons fulfillment. Hal ini memungkinkan fulfillment agen mengontrol respons dinamis secara konsisten.

Go

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

Lihat Memulai cepat webhook.

Java

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

// TODO: Change class name to Example
// 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 BasicWebhook implements HttpFunction {
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    Gson gson = new GsonBuilder().create();
    JsonObject parsedRequest = gson.fromJson(request.getReader(), JsonObject.class);

    // For more information on the structure of this object https://cloud.google.com/dialogflow/cx/docs/reference/rest/v3/Fulfillment
    String requestTag = parsedRequest.getAsJsonObject("fulfillmentInfo")
        .getAsJsonPrimitive("tag").toString();
    JsonObject responseObject = null;
    String defaultIntent = "\"Default Welcome Intent\"";
    String secondIntent = "\"get-agent-name\"";
    String responseText = "";

    // Compares the Intent Tag to provide the correct response
    if (requestTag.equals(defaultIntent)) {
      responseText = "\"Hello from a Java GCF Webhook\"";
    } else if (requestTag.equals(secondIntent)) {
      responseText = "\"My name is Flowhook\"";
    } else {
      responseText = "\"Sorry I didn't get that\"";
    }

    // Constructing the response jsonObject
    responseObject =
        JsonParser
            .parseString(
                "{ \"fulfillment_response\": { \"messages\": [ { \"text\": { \"text\": ["
                    + responseText
                    + "] } } ] } }")
            .getAsJsonObject();
    BufferedWriter writer = response.getWriter();

    //Sends the responseObject
    writer.write(responseObject.toString());
  }
}

Node.js

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

functions.http('handleWebhook', (request, response) => {
  const tag = request.body.fulfillmentInfo.tag;
  let text = '';

  if (tag === 'Default Welcome Intent') {
    text = 'Hello from a GCF Webhook';
  } else if (tag === 'get-name') {
    text = 'My name is Flowhook';
  } else {
    text = `There are no fulfillment responses defined for "${tag}"" tag`;
  }

  const jsonResponse = {
    fulfillment_response: {
      messages: [
        {
          text: {
            //fulfillment text response to be sent to the agent
            text: [text],
          },
        },
      ],
    },
  };

  response.send(jsonResponse);
});

Python

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

import functions_framework

# TODO(developer): change entry point to handle_webhook in cloud function

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

    tag = req["fulfillmentInfo"]["tag"]

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

    # You can also use the google.cloud.dialogflowcx_v3.types.WebhookRequest protos instead of manually writing the json object
    # Please see https://googleapis.dev/python/dialogflow/latest/dialogflow_v2/types.html?highlight=webhookresponse#google.cloud.dialogflow_v2.types.WebhookResponse for an overview
    res = {"fulfillment_response": {"messages": [{"text": {"text": [text]}}]}}

    # Returns json
    return res

Tetapkan parameter formulir seperlunya

Contoh berikut menunjukkan cara menandai parameter sebagaimana diperlukan.

Java

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

// TODO: Change class name to Example
// TODO: Uncomment the line below 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.JsonArray;
import com.google.gson.JsonObject;
import java.io.BufferedWriter;

public class ConfigureWebhookToSetFormParametersAsOptionalOrRequired implements HttpFunction {
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject parameterObject = new JsonObject();
    parameterObject.addProperty("display_name", "order_number");
    parameterObject.addProperty("required", "true");
    parameterObject.addProperty("state", "VALID");

    JsonArray parameterInfoList = new JsonArray();
    parameterInfoList.add(parameterObject);

    JsonObject parameterInfoObject = new JsonObject();
    parameterInfoObject.add("parameter_info", parameterInfoList);

    JsonObject formInfo = new JsonObject();
    formInfo.add("form_info", parameterInfoObject);

    // Constructs the webhook response object
    JsonObject webhookResponse = new JsonObject();
    webhookResponse.add("page_info", formInfo);

    Gson gson = new GsonBuilder().setPrettyPrinting().create();
    String jsonResponseObject = gson.toJson(webhookResponse);

    /* {
     *   "page_info": {
     *     "form_info": {
     *       "parameter_info": [
     *         {
     *           "display_name": "order_number",
     *           "required": "true",
     *           "state": "VALID"
     *         }
     *       ]
     *     }
     *   }
     * }
     */

    BufferedWriter writer = response.getWriter();

    // Sends the responseObject
    writer.write(jsonResponseObject.toString());
  }
}

Node.js

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

functions.http('configureOptionalFormParam', (request, response) => {
  // The value of the parameter that the webhook will set as optional or required.
  // Note that the webhook cannot add or remove any form parameter

  const jsonResponse = {
    pageInfo: {
      formInfo: {
        parameterInfo: [
          {
            displayName: 'order-number',
            // if required: false, the agent will not reprompt for this parameter, even if the state is 'INVALID'
            required: true,
            state: 'VALID',
          },
        ],
      },
    },
  };

  // Info about form parameter that is sent in the webhook response:
  console.log(
    'Parameter Info: \n',
    jsonResponse.pageInfo.formInfo.parameterInfo[0]
  );

  response.send(jsonResponse);
});

Memvalidasi parameter formulir

Contoh berikut menunjukkan cara memvalidasi parameter formulir.

Java

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

// TODO: Change class name to Example
// TODO: Uncomment the line below 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.JsonArray;
import com.google.gson.JsonObject;
import java.io.BufferedWriter;

public class WebhookValidateFormParameter implements HttpFunction {
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject sessionInfo = new JsonObject();
    JsonObject sessionParameter = new JsonObject();

    sessionParameter.addProperty("order_number", "null");
    sessionInfo.add("parameters", sessionParameter);

    JsonObject parameterObject = new JsonObject();
    parameterObject.addProperty("display_name", "order_number");
    parameterObject.addProperty("required", "true");
    parameterObject.addProperty("state", "INVALID");
    parameterObject.addProperty("value", "123");

    JsonArray parameterInfoList = new JsonArray();
    parameterInfoList.add(parameterObject);

    JsonObject parameterInfoObject = new JsonObject();
    parameterInfoObject.add("parameter_info", parameterInfoList);

    JsonObject pageInfo = new JsonObject();
    pageInfo.add("form_info", parameterInfoObject);

    // Constructs the webhook response object
    JsonObject webhookResponse = new JsonObject();
    webhookResponse.add("page_info", pageInfo);
    webhookResponse.add("session_info", sessionInfo);

    Gson gson = new GsonBuilder().setPrettyPrinting().create();
    String jsonResponseObject = gson.toJson(webhookResponse);

    /**
     * { "page_info": { "form_info": { "parameter_info": [ { "display_name": "order_number",
     * "required": "true", "state": "INVALID", "value": "123" } ] } }, "session_info": {
     * "parameters": { "order_number": "null" } } }
     */
    BufferedWriter writer = response.getWriter();

    // Sends the responseObject
    writer.write(jsonResponseObject.toString());
  }
}

Node.js

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

functions.http('validateParameter', (request, response) => {
  // Webhook will validate or invalidate parameter based on logic configured by the user.
  // Access parameter values through the webhook request via `request.body.pageInfo.formInfo.parameterInfo[]`
  const jsonResponse = {
    page_info: {
      form_info: {
        parameter_info: [
          {
            displayName: 'orderNumber',
            required: true,
            state: 'INVALID',
            value: 123,
          },
        ],
      },
    },
    sessionInfo: {
      parameters: {
        // Set session parameter to null if the form parameter is 'INVALID' and your agent needs to reprompt the user
        orderNumber: null,
      },
    },
  };

  response.send(jsonResponse);
});

Python

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

import functions_framework

@functions_framework.http
def validate_parameter(request):
    """Webhook will validate or invalidate parameter based on logic configured by the user."""
    return {
        "page_info": {
            "form_info": {
                "parameter_info": [
                    {
                        "displayName": "orderNumber",
                        "required": True,
                        "state": "INVALID",
                        "value": 123,
                    },
                ],
            },
        },
        "sessionInfo": {
            "parameters": {
                # Set session parameter to None if the form parameter is 'INVALID' and your agent needs to reprompt the user
                "orderNumber": None,
            },
        },
    }

Catat ID sesi

Contoh berikut menunjukkan cara mencatat session ID ke dalam log dari permintaan webhook.

Python

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

import re

import functions_framework

@functions_framework.http
def log_session_id_for_troubleshooting(request):
    """Webhook will log session id corresponding to request."""

    req = request.get_json()
    # You can read more about SessionInfo at https://cloud.google.com/dialogflow/cx/docs/reference/rest/v3/SessionInfo
    # Use a regex pattern to get the session ID
    session_id_regex = r".+\/sessions\/(.+)"
    session = req["sessionInfo"]["session"]
    regex_match = re.search(session_id_regex, session)
    session_id = regex_match.group(1)

    # Instead of printing, use the logging tools available to you
    print(f"Debug Node: session ID = {session_id}")

    # Return a generic response
    res = {
        "fulfillment_response": {
            "messages": [{"text": {"text": [f"Request Session ID: {session_id}"]}}]
        }
    }

    # Returns json
    return res

Pemecahan masalah

Saat memecahkan masalah webhook, sebaiknya catat ID sesi dari webhook Anda. Kolom sessionInfo.session pada WebhookRequest berisi ID sesi. ID sesi harus unik untuk setiap percakapan, dan dapat membantu Anda membandingkan log agen dengan log webhook untuk permintaan menggunakan ID sesi yang sama. Bagian Mencatat log ID sesi di atas menunjukkan cara mencatat ID sesi dari webhook.

Selain itu, jika menghosting webhook di Cloud Functions atau opsi serverless Google Cloud yang serupa, Anda dapat menggunakan kolom trace dari entri log sebagai filter log. Satu eksekusi fungsi menghasilkan beberapa entri log dengan nilai trace yang sama.

Contoh di bawah ini menggunakan ID sesi dan nilai trace untuk mengaitkan log error agen Dialogflow tertentu dengan entri log webhook Cloud Functions yang sesuai. Contoh ini menggunakan Filter Cloud Logging untuk agen yang telah mengaktifkan Cloud Logging.

1. Memfilter log Dialogflow untuk log error agen tertentu

Gunakan filter Cloud logging berikut untuk memfilter log Dialogflow Anda untuk log error agen tertentu:

labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR

Entri error log webhook terlihat seperti berikut:

{
  "insertId": "-zi368ye1ie3r",
  "jsonPayload": {
    "message": "Webhook error: State: URL_UNREACHABLE, Reason: UNREACHABLE_5xx, HTTP status code: 500",
    "code": 14
  },
  "resource": {
    "type": "global",
    "labels": {
      "project_id": "PROJECT_ID"
    }
  },
  "timestamp": "2022-10-05T19:44:53.098938Z",
  "severity": "ERROR",
  "labels": {
    "session_id": "ec8781-f28-7e6-791-d7e992e8f",
    "location_id": "global",
    "agent_id": "807346f0-f501-42b5-9642-af59d5e98165"
  },
  "logName": "projects/PROJECT_ID/logs/dialogflow-runtime.googleapis.com%2Frequests",
  "receiveTimestamp": "2022-10-05T19:44:53.222552658Z"
}

Catat kolom labels.session_id, yang berisi ID sesi. Anda akan menggunakan ID sesi pada langkah berikutnya.

2. Filter log Cloud Function untuk ID sesi

Gunakan filter Cloud logging berikut guna memfilter log Cloud Function untuk ID sesi:

Catatan: Filter ini mengasumsikan bahwa Anda telah mencatat ID sesi ke dalam log menggunakan teks yang sama persis seperti contoh ID sesi log di atas.

resource.type = "cloud_function"
resource.labels.function_name = "CLOUD_FUNCTION_NAME"
resource.labels.region = "CLOUD_FUNCTION_REGION"
textPayload="Debug Node: session ID = SESSION_ID"

Log yang dihasilkan sesuai dengan log webhook yang dibuat selama sesi yang disediakan. Contoh:

{
  "textPayload": "Debug Node: session ID = ec8781-f28-7e6-791-d7e992e8f",
  "insertId": "632bdb2b000b7c6c77d0cc62",
  "resource": {
    "type": "cloud_function",
    "labels": {
      "project_id": "PROJECT_ID",
      "function_name": "webhook",
      "region": "us-central1"
    }
  },
  "timestamp": "2022-10-05T19:44:53.098938Z",
  "severity": "INFO",
  "labels": {
    "execution_id": "ozt5bnz50eeo",
    "instance_id": "00c61b117c1f116421aa5503bc80f9aa636b9ef117bb2722f3d54414085e62be6e55af0aa0250a63534262b31a3d3a14af8c940203f1915db8b25b"
  },
  "logName": "projects/PROJECT_ID/logs/cloudfunctions.googleapis.com%2Fcloud-functions",
  "trace": "projects/PROJECT_ID/traces/e41eefc1fac48665b442bfa400cc2f5e",
  "receiveTimestamp": "2022-10-05T19:44:53.222552658Z"
}

Perhatikan kolom trace yang digunakan di langkah berikutnya.

3. Memfilter log Cloud Function untuk trace tertentu

Gunakan filter Cloud Logging berikut untuk memfilter log Cloud Function untuk trace tertentu:

resource.type = "cloud_function"
resource.labels.function_name = "CLOUD_FUNCTION_NAME"
resource.labels.region = "CLOUD_FUNCTION_REGION"
trace="projects/PROJECT_ID/traces/TRACE_ID"

dengan TRACE_ID adalah segmen terakhir dari rekaman aktivitas. Misalnya, TRACE_ID untuk projects/PROJECT_ID/traces/e41eefc1fac48665b442bfa400cc2f5e adalah e41eefc1fac48665b442bfa400cc2f5e.

Log yang dihasilkan sesuai dengan semua log webhook yang dihasilkan selama eksekusi permintaan webhook yang terkait dengan ID sesi dari langkah 1 dan dengan rekaman aktivitas dari langkah 2.