Automate Dialogflow CX Virtual Agent Creation with API Calls and Twilio
Time to read: 5 minutes
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. Diagram of an automated Dialogflow CX API flow with Twilio.](/content/dam/twilio-com/global/en/blog/importer-images/a-c/automate-dialogflow-cx-virtual-agent-creation-api-calls/media1/_jcr_content/renditions/compressed-original.webp)
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!).
- If you haven’t yet, sign up for a Twilio Account .
- Purchase a phone number(s) for the bot(s) to receive calls on
- Try out our Dialogflow onboarding guide to get an idea of how to (by hand) build a single, basic fully functional bot, and link it to your Twilio account and phone number. You’ll need a Google Cloud account and will need to set up Dialogflow CX (if you haven’t yet) during the process.
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
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.
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
API JSON Response Example
The returned JSON payload example below shows a successfully created Virtual Agent Connector with the Unique Name MyDialogflowCXUniqueName
.
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:
- Twilio Developer Education's basics video on how to build a functioning bot
- Twilio’s best practices for building the Virtual Agents themselves
- Google’s new Generative AI features for Dialogflow – Generators, Generative Fallback, and entire Generative Agents (playbooks) with uploaded data.
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
Related Posts
Related Resources
Twilio Docs
From APIs to SDKs to sample apps
API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
Resource Center
The latest ebooks, industry reports, and webinars
Learn from customer engagement experts to improve your own communication.
Ahoy
Twilio's developer community hub
Best practices, code samples, and inspiration to build communications and digital engagement experiences.