Dialogflow phone gateway

The Dialogflow phone gateway feature provides a telephone interface to your agent. It is used to build conversational IVR (interactive voice response) solutions that integrate with the rest of your call center network. Currently, you can select a telephone number hosted by Google.

For phone gateway pricing and quota information, see the Pricing and Quotas and Limits pages.

Limitations

Language support

This integration only supports use of one language per agent.

If enhanced speech models is enabled for the agent, this integration only supports the following languages:

  • English (en)
  • English - US (en-US)

If enhanced speech models is disabled for the agent, see the Phone column on the Language reference page for the list of supported languages.

Phone number support

Only US phone numbers are supported, both for incoming calls and for call transfers.

Before you begin

You should do the following before reading this guide:

  1. Read Dialogflow basics.
  2. Perform setup steps.

Create an agent

If you have not already created an agent, create one now:

  1. Go to the Dialogflow ES Console.
  2. If requested, sign in to the Dialogflow Console. See Dialogflow console overview for more information.
  3. Click Create Agent in the left sidebar menu. (If you already have other agents, click the agent name, scroll to the bottom and click Create new agent.)
  4. Enter your agent's name, default language, and default time zone.
  5. If you have already created a project, enter that project. If you want to allow the Dialogflow Console to create the project, select Create a new Google project.
  6. Click the Create button.

Import the example file to your agent

The steps in this guide make assumptions about your agent, so you need to import an agent prepared for this guide. When importing, these steps use the restore option, which overwrites all agent settings, intents, and entities.

To import the file, follow these steps:

  1. Download the telephony-bot.zip file.
  2. Go to the Dialogflow ES Console.
  3. Select your agent.
  4. Click the settings button next to the agent name.
  5. Select the Export and Import tab.
  6. Select Restore From Zip and follow instructions to restore the zip file that you downloaded.

Enable beta features

Ensure that beta features are enabled:

  1. Go to the Dialogflow ES Console.
  2. Select an agent.
  3. Click the settings button next to the agent's name.
  4. Scroll down while on the General tab and ensure that Beta Features is enabled.
  5. If you have made changes, click Save.

Set up a phone gateway

To set up your gateway, follow these steps:

  1. Select a provider:
    1. Go to the Dialogflow ES Console.
    2. Select your agent.
    3. Click Integrations.
    4. Click Dialogflow Phone Gateway.
  2. Configure Phone Gateway:
    1. Select the language.
    2. Select the country code for the telephone number.
    3. Optional. Select preferred area codes.
    4. Click Next.
  3. Select a number:
    1. Choose a telephone number from the list.
    2. Click Create.
  4. Completion:
    1. The gateway is now active.
    2. Optionally change the environment.
    3. Save the displayed telephone number and close the dialog window. You can click the Dialogflow Phone Gateway integrations button again to retrieve this information.

Call the telephone number

You can now call the number and follow the simple voice prompts. The interactions are defined in your agent.

Examine the intents

Now that you have a working phone gateway agent, let's look at the intents you imported. This will help you understand how to build your own phone gateway agents.

Welcome the caller

When you called the number, the agent greeted you and provided a list of options. Follow these steps to see how this was configured:

  1. Go to the Dialogflow ES Console.
  2. Select your agent.
  3. Click Intents.
  4. Click Default Welcome Intent.
  5. Scroll down to the Events section. Notice that both Welcome (WELCOME) and Telephony Welcome (TELEPHONY_WELCOME) events are present, which means that all types of welcome events will trigger this intent. As an alternative, you could create separate intents, each dedicated to a specific welcome event.
  6. Scroll down to the Responses section and click the DIALOGFLOW PHONE GATEWAY tab.
  7. Notice that the Synthesize speech response contains the welcome message you heard when calling the number.

Response to test command

After you responded with "test", the agent presented a new list of options. Follow these steps to see how this was configured:

  1. Click Intents.
  2. Click Test Telephony Intent.
  3. Scroll down to the Responses section and click the DIALOGFLOW PHONE GATEWAY tab.
  4. Note that the Synthesize speech response contains the response you heard after you said "test".

Setting context

After saying "test", there are two possible commands you can make: "transfer" or "terminate". This is not a limitation of phone gateway agents; it is just how this intent is defined. The intents associated with these commands are provided with context. Follow these steps to see how this was configured:

  1. Scroll to the Context section at the top.
  2. Notice the TestTelephonyIntent-followup output context.
  3. Click Intents.
  4. Click the expansion button next to Test Telephony Intent.
  5. Click Test Telephony Intent - Terminate
  6. Scroll to the Context section at the top.
  7. Notice the TestTelephonyIntent-followup input context.

Terminate the call

When you responded with "terminate", the agent said "goodbye" and terminated the call. Follow these steps to see how this was configured:

  1. Scroll down to the Training phrases section and note the phrases used to terminate the call.
  2. Scroll down to the Responses section and click the DIALOGFLOW PHONE GATEWAY tab.
  3. Notice that the Synthesize speech response contains "goodbye".
  4. Notice that Set this intent as end of conversation is enabled. If this is enabled, Dialogflow terminates the phone call after playing all other audio prompts.

Phone gateway rich response messages

The intents for this example use rich response messages for phone gateway responses. These are the types that you can use:

  • Play audio: Plays the supplied audio file. Specify the URI to a Cloud Storage object containing the audio to play. For example, 'gs://bucket/object'. The object must contain a single channel (mono) of linear PCM audio (2 bytes / sample) at 8kHz.
  • Synthesize speech: Synthesizes the supplied text to audio and plays it. Alternatively, you can enable Use response from the DEFAULT tab as the first response, which will use the default response to synthesize a speech response. If you only define default responses, and you do not enable Use response from the DEFAULT tab as the first response, only the text populated in QueryResult.fulfillment_text (populated with a randomly selected text response), is synthesized to audio.
  • Transfer call: Transfers the caller to another number. The time duration spent on the transferred call is included in the total call duration, and Dialogflow charges are applied until the call is ended.

Agent settings

You can control various aspects of speech synthesis. See the agent speech settings.

Use the Dialogflow simulator

When testing or experimenting with a phone gateway agent, you don't need to make a phone call. You can interact with the agent and receive audio responses via the Dialogflow simulator:

  1. Type "hello" and press the return key
  2. Change Default Response to DIALOGFLOW PHONE GATEWAY
  3. Click the Play Audio button to hear the agent response
  4. Continue the conversation with the agent

Toll-free numbers

You can request a phone number with an 833 area code. Note that toll-free numbers are priced higher.

Events

The following events are invoked by this integration:

Event
Description
TELEPHONY_WELCOME Triggered when someone calls the phone number associated with your Dialogflow agent.

Agent warmup

When an end-user calls a Dialogflow Phone Gateway agent, Dialogflow starts by loading the agent for a quick response to the initial end-user utterance. While the agent is loading, the phone keeps ringing. Dialogflow accomplishes this by sending a detect intent request to your agent. The text of this request is TELEPHONY_WARMUP.

Retrieve caller phone number

You can retrieve the caller_id value from the OriginalDetectIntentRequest.payload field in the webhook request if you use the Dialogflow Essentials edition. In the Dialogflow Trial edition, the caller_id value is redacted.