Automate Dialogflow CX Virtual Agent Creation with API Calls and Twilio

July 17, 2024
Written by
Reviewed by
Paul Kamp
Twilion

Automate Dialogflow CX Virtual Agent Creation with API Calls and Twilio

Twilio’s current documented approach to create a Virtual Agent Connector for Dialogflow CX is to use Google’s ‘One Click’ connector process. This process allows a developer to create a Twilio Virtual Agent Connector by clicking through a series of options on the Google Dialogflow CX and Twilio web consoles.

This process works well for creating one or two virtual agent bots. However, this process also needs to be automated to scale for Twilio’s large ISV customers, who will need to create large numbers of these virtual agents. Also, automation is necessary for ISVs who need to rapidly and programmatically automate the creation of virtual agents when a new customer signs up for their software need an automated solution.

This blog post describes the steps to create a single Google Dialogflow CX Agent and use the Twilio APIs to automatically create multiple instances of the Twilio Virtual Agent Connector (pointing back to a single Dialogflow CX Agent). Longer term, our ISV customers can automatically create the entire solution for their customers.

High Level Process Flow

This diagram shows an overview of the (automate-able/API-based) process to get Twilio and Google’s part of the solution working together. You’ll first create a Google Dialogflow CX Agent, then use API calls to create multiple Twilio Virtual Agent Connector instances all pointing back to that original Dialogflow CX Agent, like this:

Diagram of an automated Dialogflow CX API flow with Twilio.

This architecture will be incredibly useful for ISVs or other customers that need to scale their bots quickly in an automated way. For one good example, consider a Point-of-Sale software vendor that recruits a new chain of restaurants and needs to build menu-reading, order-taking, and hours/directions-giving bots for each restaurant location in the chain.

Prerequisites

Before you begin the tutorial, you’ll need to complete a few steps and sign up for a few accounts (if you haven’t yet!).

Create Virtual Agents with API calls

In the following step, we’ll walk you through creating a Dialogflow CX Agent to expand upon or clone. Then, we’ll create any number of Virtual Agent Connectors through Twilio API calls, finally connecting them back to the original agent.

Let’s get started.

Create the Dialogflow CX Agent

If a Dialogflow CX Agent hasn’t already been created, create one via the Dialogflow Console or via the Dialogflow CX API .

Note the Google Cloud Project where the Agent is located, you’ll need to use it in one of the next steps.

Configure Twilio’s Access to the Dialogflow CX Agent

You will need to provide Twilio's production service account permission to run your Dialogflow agent:

  • Log in to your Google Cloud console
  • Select the Google Project in which you configured your Dialogflow CX Agent
  • Navigate to IAM & Admin > IAM from the left navigation
  • Click +Grant Access near the top of the page
  • Under "New Principals", add virtualagent-ccai-prod@dialogflow-prod-env.iam.gserviceaccount.com as a member with the following roles:
  • Dialogflow API Reader
  • Dialogflow API Client
  • Click Save
This can also be done directly via the Google Cloud API .

Create the Google Conversation Profile ID

A Conversation Profile ID will need to be created in Google Agent-Assist. This Conversation Profile ID is used to directly access a specific Dialogflow CX Agent and most of the settings in the Agent Assist Conversation Profile are not used.

To do this, you will need to:

  • Log in to your Google Cloud Agent Assist Console
  • Navigate to “Conversation Profiles” on the left side of the page.
  • Select the Google Project in which you configured your Dialogflow CX Agent.
  • Select the Location in which your Dialogflow CX Agent is located.
  • Click +Create near the top of the page
  • Enter a value for the Display Name
  • Click the Enable Virtual Agent toggle button
  • Select the Dialogflow CX Agent that was recently created
  • Click the Create button to save the Conversation Profile
  • Copy the Integration ID value of the newly created Conversation Profile.
This can also be done directly via the Agent Assist API .

Invoke the API to create additional Virtual Agent Connectors

Invoke the Twilio Add-On Management API to create a new instance of the Virtual Agent Connector. This can be done on a Twilio Parent or Subaccount using the appropriate AccountSID. The parameters for the API are defined in the API documentation and below:

Parameter

Description

UNIQUE_NAME

This is the unique name value that will be used to invoke the Virtual Agent Connector from other Twilio Locations (Twiml/Twiml Bins/Studio Flows/etc)

AVAILABLE_ADD_ON_SID

Twilio defined static value for the Virtual Agent Connector Add On

GCP_AGENT_CONVERSATION_ID

Agent Assist Conversation ID value created during the One-Click process.

GCP_PROJECT_ID

Google Cloud Project ID

GCP_AGENT_LOCATION

Dialogflow Google Cloud Agent Location

TWILIO_ACCOUNT_SID

Twilio Account SID

TWILIO_AUTH_TOKEN

Twilio Auth Token

language

Dialogflow CX Agent Language

sentimentAnalysis

Boolean, True = Enable Sentiment Analysis, False = Disable

welcomeIntent

Dialogflow CX Agent Intent that will be invoked when a call is connected.

voiceName

String, Voice Name from Google’s Text to Speech or ‘Default’

Following is an example of calling the API using curl from the command line, along with a response from the API.

Bash Curl Example

UNIQUE_NAME=MyDialogflowCXUniqueName
AVAILABLE_ADD_ON_SID=XB1f158cacea38a5621ecf00f2196994a4
GCP_AGENT_CONVERSATION_ID=xxxxx
GCP_PROJECT_ID=gcp-test-project
GCP_AGENT_LOCATION=us-east1
TWILIO_ACCOUNT_SID=xxxxx
TWILIO_AUTH_TOKEN=xxxxx
CONFIGURATION=$(cat << EOF
{
  "projectId" : "$GCP_PROJECT_ID",
  "language" : "en-us",
  "sentimentAnalysis" : true,
  "welcomeIntent" : "WELCOME",
  "voiceName" : "DEFAULT",
  "agentLocation" : "$GCP_AGENT_LOCATION",
  "credentialObject" : {
    "conversationProfileId" : "$GCP_AGENT_CONVERSATION_ID"
  }
}
EOF
)

curl -X POST "https://preview.twilio.com/marketplace/InstalledAddOns" \
--data-urlencode "Configuration=$CONFIGURATION" \
--data-urlencode "AvailableAddOnSid=$AVAILABLE_ADD_ON_SID" \
--data-urlencode "UniqueName=$UNIQUE_NAME" \
--data-urlencode "AcceptTermsOfService=True" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

API JSON Response Example

The returned JSON payload example below shows a successfully created Virtual Agent Connector with the Unique Name MyDialogflowCXUniqueName.

{
  "unique_name": "MyDialogflowCXUniqueName",
  "description": "Dialogflow CX is a natural language understanding based virtual agent that understands the nuances of human language and handles concurrent conversations with your end-users similar to a human call center agent.",
  "date_updated": "2023-10-24T22:35:25Z",
  "friendly_name": "Dialogflow CX Connector",
  "account_sid": "xxxxx",
  "url": "https://preview.twilio.com/marketplace/InstalledAddOns/xxxxx",
  "sid": "xxxxx",
  "date_created": "2023-10-24T22:35:25Z",
  "configuration": {
    "voiceName": "DEFAULT",
    "agentLocation": "us-east1",
    "language": "en-us",
    "sentimentAnalysis": true,
    "projectId": "ccai-test-customer",
    "credentialSid": "xxxxx",
    "welcomeIntent": "WELCOME"
  },
  "links": {
    "extensions": "https://preview.twilio.com/marketplace/InstalledAddOns/xxxxx/Extensions",
    "available_add_on": "https://preview.twilio.com/marketplace/AvailableAddOns/xxxxx"
  }
}

Testing, debugging, and running

One common pitfall to avoid is “not using a unique name.”

Otherwise, the process to confirm and test your setup is relatively straightforward: make sure that the curl request doesn't return an error. A successful response payload as a reference is in the example above.

You can also check your Twilio console Add-Ons section to make sure you see the Dialogflow CX Connector module is shown. Then finish your testing with the “acid test” of placing a call to invoke the virtual agent.

Conclusion

You’ve now seen how to automate building Virtual Agents and Connectors as you may need, using API calls. Next, while you build yourself some ‘bots, check out:

And additionally, or first, don’t forget to try out our Dialogflow onboarding guide . We can’t wait to see what you’ll build!

Brent Bailey is a Solutions Architect at Twilio and has been writing voice applications since he was too cheap to pay for voice calls on his first Motorola cell phone and instead wrote a J2ME application to outpulse DTMF numbers to auto dial from any phone he could find. He has matured slightly and is now responsible for three kids and loves helping large companies with AI/ML based automation.

Russ Kahan is the Principal Product Manager for Speech Recognition, Dialogflow Virtual Agents, Media Streams and SIPREC at Twilio. He’s enjoyed programming voice apps and conversing with robots since sometime back in the late nineties – when and this stuff was still called “CTI,” for “Computer Telephony Integration” – but he also enjoys real-world pursuits like Scouting, skiing, swimming, and mountain biking with his kids. Reach him at rkahan [at] twilio.com