Dialogflow

The dialogflow Function streams the caller's audio to a Google Dialogflow agent and plays the agent's spoken replies back to the caller. Three agent types are supported, selected by the model parameter:

Warning

Agents built in the Conversational Agents console (Google markets it under the "Customer Engagement Suite" umbrella) speak the CX API — use model: "cx" for them, not ces.

Examples

Connecting to a Dialogflow ES agent:

{
  "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"
}

Connecting to a Dialogflow CX (Playbook) agent with client-side tools:

{
  "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"
}

The agent value is the uuid from the agent's resource name (projects/my-gcp-project/locations/us-central1/agents/99e7b4c8-...), shown in the Conversational Agents console URL.

Parameters

The service account key in JSON string form (i.e. JSON.stringify the key file's contents). The service account needs the Dialogflow API Client role (roles/dialogflow.client).

Language for speech recognition, e.g. en-US.

The GCP project ID hosting the agent, e.g. my-gcp-project.

A webhook invoked when the operation completes.
See below for specified request parameters.

The Dialogflow agent ID (uuid), e.g. 99e7b4c8-259c-4de4-b9da-cb44dc42b792. Required when model is cx or ces.

If true, kill playback immediately when the user begins speaking.

The Dialogflow CX environment to use, e.g. production. Omit to use the draft environment.

A webhook to invoke when a Dialogflow event occurs, such as an intent being detected or a speech transcription being returned.
The response to the event hook may contain a new Wipple CPaaS application to execute.

Which event types to receive on the eventHook, e.g. ["intent", "transcription", "tool-calls"]. Defaults to all supported events for the selected model. See the event list.

The agent type: es (default) | cx | ces. See the table above.

Name of the Dialogflow event to send in query when no input timeout expires. Default: actions_intent_NO_INPUT.

Number of seconds of no speech detected after which to reprompt. Default: 20.

If true, pass user DTMF entries as text inputs to the Dialogflow bot.

The GCP region hosting the agent, e.g. us-central1 (the default for CX/CES). The matching regional API endpoint (us-central1-dialogflow.googleapis.com) is used automatically — a CX agent created in a region is not reachable via the global endpoint.

A URL to a .wav or .mp3 file to play as filler music while the Dialogflow back-end is executing.

A webhook invoked when a Dialogflow CX agent requests a client-side tool call, e.g. /dialogflow-tool. Respond with the tool result to resume the conversation. See Client-side tool calls.

If provided, audio prompts will be played using text-to-speech rather than the Dialogflow-provided audio clips.

(Google only) MALE, FEMALE, or NEUTRAL.

Language code to use.

Speech vendor to use: Google, AWS (alias: Polly), or default (for application default).

Voice to use. Note that the voice list differs depending on whether you are using AWS or Google. Defaults to application setting, if provided.

An event to send to Dialogflow when first connecting; e.g., to trigger a welcome prompt. The agent must define a handler for this event — Playbook agents typically do not (sending one returns a Google "No handler is defined for the event" error); they respond to the caller's first spoken turn instead.

An object containing parameters to send with the welcome event, e.g. {"customer_tier": "gold"}.

actionHook properties

The actionHook webhook will contain the following additional parameters:

• dialogflowResult: the completion reason:
• redirect - a new application was returned from an event webhook
• completed - an intent with end interaction set to true was received from dialogflow
• caller hungup - the caller hung up

eventHook properties

The eventHook webhook contains two parameters: event (the event name) and data (the event payload). Supported events:

• intent: dialogflow detected an intent
• transcription: a speech transcription was returned from dialogflow
• dtmf: a dtmf key was pressed by the caller
• start-play: an audio segment returned from dialogflow started to play
• stop-play: an audio segment returned from dialogflow completed playing
• no-input: the no input timer elapsed with no input detected from the caller
• tool-calls: the agent requested one or more client-side tool calls (CX/CES; informational — use toolHook to answer them)

A transcription event (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"
    }
  }
}

A start-play event (the path is the agent audio Wipple CPaaS is playing):

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

Client-side tool calls (Dialogflow CX)

Dialogflow CX agents (including generative Playbook agents) can define client-side Function tools — tools with no server backend, where your application executes the action and returns the result. When the agent needs one, it stops speaking and waits. Wipple CPaaS handles the round trip through the toolHook.

Tip

A tool's description must not be empty in the Dialogflow console. Dialogflow passes the description to the model as that action's documentation — with no description the tool is never offered to the model, and the agent silently escalates instead of calling it.

1. The agent requests a tool. Wipple CPaaS POSTs to your toolHook:

{
  "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 carries the arguments the agent gathered from the conversation. For example, a flight-search tool called after the caller has given a destination and date arrives populated:

{
  "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. Your application executes the tool and responds to the webhook with the result — a raw JSON object, not a list of Functions:

{
  "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}
    ]
  }
}

or, to report a failure so the agent can react gracefully:

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

3. Wipple CPaaS returns the result to Dialogflow and the agent resumes speaking — e.g. "I have two flights for you: flight CA101 leaves JFK at 8:30... which of these flights would you like to book?"

A complete toolHook handler:

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}'`});
  }
});

Notes:

• A reliable sign a tool call is pending: an intent event arrives with a tool_call response message and no audio is played — the agent produced no speech because it is waiting on you.
• Without a toolHook, tool calls are surfaced via the tool-calls event only (informational) and the conversation waits for caller input.
• Timing measured on a live agent: caller stops speaking → tool call ≈ 2-3s; tool result → agent resumes speaking ≈ 2-4s.

call transfer in Dialogflow

Call transfer from a dialogflow bot is achieved by responding to an eventHook with event intent by returning a new Wipple CPaaS application containing a dial Function. Of course, this should only be done if the intent is signaling a request for a call transfer.

Indicating a desire to transfer the call to a live agent can be done in a couple of different ways in the dialogflow editor:

1. By adding a Dialogflow Phone Gateway Response to the intent, with a Transfer Call action.
2. By adding a custom payload in a response to the intent, with arbitrary JSON content that you define and which should include the telephone number (or registered user, or sip endpoint) to transfer to.

Note: option 1 only works when transferring to a US number, because the dialogflow editor only accepts US destinations. To transfer to non-US destinations, use option 2.

In either case, your application is responsible for having an eventHook that parses the intent (found in the data property of the webhook content) in order to check if call transfer is being requested, and if so responding with a new Wipple CPaaS application.

For instance, when the Dialogflow Phone Gateway Response is used (option 1 above), the code snippet below shows where to find the transfer number in the intent data provided in the 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
    }
}