Dialogflow

dialogflow Function は、発信者の音声を Google Dialogflow エージェントにストリーミングし、 エージェントの音声応答を発信者に再生します。model パラメータで選択できる 3種類のエージェントタイプに対応しています。

警告

Conversational Agents コンソール(Google は「Customer Engagement Suite」の 名称で提供しています)で作成したエージェントは CX API を使用します。これらには ces ではなく model: "cx" を指定してください。

例

Dialogflow ES エージェントへの接続:

{
  "verb": "dialogflow",
  "project": "my-gcp-project",
  "lang": "en-US",
  "credentials": "{\"type\":\"service_account\",\"project_id\":\"my-gcp-project\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\"}",
  "welcomeEvent": "welcome",
  "eventHook": "/dialogflow-event",
  "actionHook": "/dialogflow-action"
}

クライアントサイドツールを持つ Dialogflow CX (Playbook) エージェントへの接続:

{
  "verb": "dialogflow",
  "model": "cx",
  "project": "my-gcp-project",
  "agent": "99e7b4c8-259c-4de4-b9da-cb44dc42b792",
  "region": "us-central1",
  "lang": "en-US",
  "credentials": "{\"type\":\"service_account\",\"project_id\":\"my-gcp-project\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\"}",
  "events": ["intent", "transcription", "tool-calls", "start-play", "stop-play"],
  "eventHook": "/dialogflow-event",
  "toolHook": "/dialogflow-tool",
  "actionHook": "/dialogflow-action"
}

agent の値は、エージェントのリソース名 (projects/my-gcp-project/locations/us-central1/agents/99e7b4c8-...)に含まれる uuid で、 Conversational Agents コンソールの URL に表示されます。

パラメータ

サービスアカウントキーを JSON 文字列形式にしたもの(キーファイルの内容を JSON.stringify したもの)。サービスアカウントには Dialogflow API Client ロール(roles/dialogflow.client)が必要です。

音声認識に使用する言語。例: en-US。

エージェントをホストしている GCP プロジェクト ID。例: my-gcp-project。

操作の完了時に呼び出される Webhook。
送信されるリクエストパラメータについては後述を参照してください。

Dialogflow エージェント ID (uuid)。例: 99e7b4c8-259c-4de4-b9da-cb44dc42b792。model が cx または ces の場合は 必須です。

true の場合、ユーザーが話し始めた時点で直ちに再生を停止します。

使用する Dialogflow CX の環境。例: production。省略した場合は ドラフト環境が使用されます。

インテントの検出や音声の文字起こし結果の返却など、Dialogflow のイベントが発生したときに呼び出す Webhook。
イベントフックへのレスポンスには、実行する新しい Wipple CPaaS アプリケーションを含めることができます。

eventHook で受け取るイベントタイプ。例: ["intent", "transcription", "tool-calls"]。デフォルトは、選択したモデルで サポートされるすべてのイベントです。イベント一覧を参照してください。

エージェントのタイプ: es (デフォルト) | cx | ces。上の表を参照してください。

無入力タイムアウトが満了したときにクエリで送信する Dialogflow イベントの名前。 デフォルト: actions_intent_NO_INPUT。

音声が検出されない状態がこの秒数続いた後に再プロンプトします。 デフォルト: 20。

true の場合、ユーザーの DTMF 入力をテキスト入力として Dialogflow ボットに渡します。

エージェントをホストしている GCP リージョン。例: us-central1 (CX/CES の デフォルト)。対応するリージョン API エンドポイント (us-central1-dialogflow.googleapis.com)が自動的に使用されます。リージョン内に 作成した CX エージェントには、グローバルエンドポイントからはアクセスできません。

Dialogflow のバックエンドが処理を実行している間、つなぎの音楽として再生する .wav または .mp3 ファイルの URL。

Dialogflow CX エージェントがクライアントサイドのツール呼び出しを要求したときに 呼び出される Webhook。例: /dialogflow-tool。ツールの実行結果を返すと会話が 再開されます。クライアントサイドのツール呼び出しを参照してください。

指定した場合、Dialogflow が提供する音声クリップの代わりに音声合成を使用して音声プロンプトを再生します。

(Google のみ) MALE、FEMALE、または NEUTRAL。

使用する言語コード。

使用する音声ベンダー: Google、AWS (別名: Polly)、または default (アプリケーションのデフォルトを使用)。

使用する音声。音声の一覧は AWS と Google のどちらを使用するかによって異なることに注意してください。指定があればアプリケーション設定がデフォルトになります。

最初の接続時に Dialogflow へ送信するイベント。例えば、ウェルカムプロンプトを トリガーするために使用します。エージェント側でこのイベントのハンドラを定義しておく 必要があります。Playbook エージェントには通常ハンドラがなく(送信すると Google の "No handler is defined for the event" エラーが返されます)、代わりに発信者の最初の 発話に応答します。

ウェルカムイベントと共に送信するパラメータを含むオブジェクト。例: {"customer_tier": "gold"}。

actionHook のプロパティ

actionHook の Webhook には、次の追加パラメータが含まれます。

• dialogflowResult: 完了理由:
• redirect - イベント Webhook から新しいアプリケーションが返された
• completed - end interaction が true に設定されたインテントを Dialogflow から受信した
• caller hungup - 発信者が切断した

eventHook のプロパティ

eventHook の Webhook には、event (イベント名)と data (イベントのペイロード)の 2つのパラメータが含まれます。サポートされるイベント:

• intent: Dialogflow がインテントを検出した
• transcription: Dialogflow から音声の文字起こし結果が返された
• dtmf: 発信者が DTMF キーを押した
• start-play: Dialogflow から返された音声セグメントの再生が開始された
• stop-play: Dialogflow から返された音声セグメントの再生が完了した
• no-input: 発信者からの入力が検出されないまま無入力タイマーが満了した
• tool-calls: エージェントが1つ以上のクライアントサイドのツール呼び出しを要求した(CX/CES。情報提供のみ。応答するには toolHook を使用します)

transcription イベント (CX):

{
  "event": "transcription",
  "data": {
    "recognition_result": {
      "message_type": "TRANSCRIPT",
      "transcript": "hi, I need a flight",
      "is_final": true,
      "confidence": 0.98,
      "language_code": "en-us"
    }
  }
}

start-play イベント(path は Wipple CPaaS が再生しているエージェント音声です):

{
  "event": "start-play",
  "data": {"path": "/tmp/4f3a2b1c-..._3.wav"}
}

クライアントサイドのツール呼び出し (Dialogflow CX)

Dialogflow CX エージェント(生成型 Playbook エージェントを含む)では、クライアントサイドの Function ツールを定義できます。これはサーバーバックエンドを持たないツールで、 お客様のアプリケーションがアクションを実行し、その結果を返します。エージェントが このツールを必要とすると、発話を停止して待機します。Wipple CPaaS は toolHook を通じて この往復処理を行います。

ヒント

Dialogflow コンソールで、ツールの説明 (description) を空にしないでください。 Dialogflow はその説明をアクションのドキュメントとしてモデルに渡します。説明がないと そのツールはモデルに提示されず、エージェントはツールを呼び出す代わりに黙って エスカレーションしてしまいます。

1. エージェントがツールを要求します。Wipple CPaaS は toolHook に POST します:

{
  "event": "tool-call",
  "tool_call": {
    "tool": "projects/my-gcp-project/locations/us-central1/agents/99e7b4c8-.../tools/4f58a625-...",
    "action": "getGeolocation",
    "input_parameters": {}
  },
  "call_sid": "df01a-...",
  "direction": "inbound",
  "from": "+815099990007",
  "to": "+815099990013"
}

input_parameters には、エージェントが会話から収集した引数が含まれます。例えば、 発信者が目的地と日付を伝えた後に呼び出されるフライト検索ツールには、次のように 値が入った状態で届きます:

{
  "event": "tool-call",
  "tool_call": {
    "tool": "projects/.../tools/e85ff4ee-...",
    "action": "getFlights",
    "input_parameters": {
      "origin_airport_code": "JFK",
      "destination_airport_code": "CDG",
      "destination_city_name": "Paris",
      "travel_date": "2026-12-05",
      "timezone_difference_minutes": 360,
      "flight_duration_minutes": 450
    }
  }
}

2. アプリケーションがツールを実行し、その結果を Webhook のレスポンスとして返します。 これは Function のリストではなく、生の JSON オブジェクトです:

{
  "outputParameters": {
    "flights": [
      {"flight_number": "CA101", "origin": "JFK", "destination": "CDG",
       "departure_time": "08:30", "arrival_time": "21:45", "price_usd": 640},
      {"flight_number": "CA205", "origin": "JFK", "destination": "CDG",
       "departure_time": "17:10", "arrival_time": "06:25", "price_usd": 545}
    ]
  }
}

または、エージェントが適切に対処できるように失敗を報告する場合:

{"error": "flight search service unavailable"}

3. Wipple CPaaS が結果を Dialogflow に返し、エージェントが発話を再開します。 例: "I have two flights for you: flight CA101 leaves JFK at 8:30... which of these flights would you like to book?"

toolHook ハンドラの完全な例:

app.post('/dialogflow-tool', (req, res) => {
  const {tool_call} = req.body;
  switch (tool_call.action) {
    case 'getGeolocation':
      // no input_parameters: return the caller's location
      return res.json({
        outputParameters: {city: 'New York', country_code: 'us', postcode: '10001'}
      });
    case 'getFlights': {
      const {origin_airport_code, destination_airport_code, travel_date} = tool_call.input_parameters;
      const flights = searchFlights(origin_airport_code, destination_airport_code, travel_date);
      return res.json({outputParameters: {flights}});
    }
    default:
      return res.json({error: `no handler for tool '${tool_call.action}'`});
  }
});

注意:

• ツール呼び出しが保留中であることを示す確実なサインは、tool_call レスポンスメッセージを 含む intent イベントが届き、かつ音声が再生されないことです。エージェントは お客様の応答を待っているため、発話を生成していません。
• toolHook がない場合、ツール呼び出しは tool-calls イベント(情報提供のみ)としてのみ 通知され、会話は発信者の入力を待ちます。
• 稼働中のエージェントで計測したタイミング: 発信者の発話終了 → ツール呼び出しまで約2〜3秒、 ツール結果 → エージェントの発話再開まで約2〜4秒。

Dialogflow での通話転送

Dialogflow ボットからの通話転送は、イベント intent の eventHook に対して、dial Function を含む新しい Wipple CPaaS アプリケーションを返すことで実現します。もちろん、これはインテントが通話転送の要求を示している場合にのみ行うべきです。

有人オペレーターへの通話転送の意図は、Dialogflow エディタで次のいずれかの方法で示すことができます。

1. インテントに Dialogflow Phone Gateway Response を追加し、Transfer Call アクションを設定する。
2. インテントへのレスポンスにカスタムペイロードを追加する。内容はお客様が定義する任意の JSON で、転送先の電話番号(または登録済みユーザー、SIP エンドポイント)を含めます。

注意: 方法 1 は米国の番号への転送でのみ機能します。Dialogflow エディタは米国の転送先しか受け付けないためです。米国以外の転送先に転送するには、方法 2 を使用してください。

いずれの場合も、お客様のアプリケーションは eventHook を用意し、インテント(Webhook の内容の data プロパティにあります)を解析して通話転送が要求されているかどうかを確認し、要求されていれば新しい Wipple CPaaS アプリケーションを返す責任があります。

例えば、Dialogflow Phone Gateway Response を使用する場合(上記の方法 1)、以下のコードスニペットは eventHook で提供されるインテントデータのどこに転送先番号があるかを示しています。

const evt = req.body; 
if (evt.event === 'intent') {
    const qo = evt.data.query_result;
    const transfer = qo.fulfillment_messages.find((fm) => {
      return fm.platform === 'TELEPHONY' && fm.telephony_transfer_call;
    });
    if (transfer) {
        // a transfer has been requested
        // transfer.telephony_transfer_call.phone_number has the phone number to transfer to
    }
}