Integration of Power Virtual Agent (with Ask Adaptive Card) with Third-Party API via Custom Connector and Dynamic 365 CE through Power Automate

[ShanmugaRaja]

Integration of Power Virtual Agent (with Ask Adaptive Card) with Third-Party API via Custom Connector and Dynamic 365 CE through Power Automate

In my earlier article Power Virtual Agent Integration With Dynamic 365 CRM Using Power Automate, I show how when a customer requests a new connection, the bot swiftly presents a question to gather essential information from the customer. To achieve this, I structured the bot to include an “Ask a question” node that captured customer details. Furthermore, I established corresponding variables to store their responses in dedicated variables for further use.

This question node is designed to showcase non-interactive cards that provide information. This can lead to challenges in discerning between mandatory and optional questions. In situations where customers attempt to skip or don’t respond to necessary questions, the bot responds by prompting the question once, and twice if needed, aiming to obtain a suitable answer from the customer. However, this strategy becomes intricate when seeking more comprehensive information from customers.

Adaptive Cards play a crucial role within Power Virtual Agents, providing a versatile and interactive method for user engagement. They server to present diverse content, gather user inputs, and deliver dynamic interfaces that adapt according to user interactions. Through the utilization of the Ask with Adaptive Card feature, developers can craft chatbot experiences that are both more captivating and interactive, ultimately enhancing user contentment and elevating the overall effectiveness of the chatbot.

Working Principle:
Our main objective is to gather essential customer information, pinpoint the address location on a map, and validate it with the customer. Ultimately, this process results in the creation of lead records in Dynamics 365 containing the customer’s details.

Let’s Start!!!

Creating the Adaptive Card:
There are two methods to access the Adaptive Designer portal:

• Through the website https://adaptivecards.io/designer/
• In Power Virtual Agent, by clicking the plus symbol for the new node and selecting “Ask with Adaptive Card”. This action opens the Adaptive Card Node properties on the right side. The Adaptive Card property window provides a link to open the Adaptive Card designer at https://adaptivecards.io/designer/

#1 Design Lead Form:
For the purpose of this article, I will intentionally opt for an application login sample adaptive card, which closely aligns with our needs.

We’ll modify it by substituting “username” with “First Name” and introducing new input fields for “Last Name”, “Mobile Number”, “Email”, and “Address”. Additionally, we’ll eliminate the password input text from the card.

Whenever new elements are introduced, elements are removed, or element properties are updated within the card, the corresponding JSON is generated in the card payload editor.

#2 Static Map Gallery Adaptive Card:

Based on our situation, our requirement involves showing a static map that marks the address, and the location is emphasized with a marker to receive customer confirmation. To achieve this, I’ve introduced an image element within the container. Additionally, a toggle button has been integrated to confirm the highlighting of the location on the static map image.

Creating Custom Connector:

Since I required access to a Third-Party API, I embarked on a bit of online research to find a solution, leading me to discover Geoapify, a valuable resource for requesting latitude and longitude by configuring the base parameter in the request. Geoapify offers a range of services including maps, address and location search, route optimization, reachability analysis, and geodata access. It provides core maps APIs, Auxiliary APIs, and data services.

The Power Platform empowers developers to easily craft custom connectors in just five steps. If you're interested in learning about custom connectors, I invite you to explore my article, Integrating Dynamic 365 CRM with Third-party API via Custom Connector using Power Automate Part 1. This article offers a comprehensive description of creating Custom Connectors in Power Automate for third-party systems, providing a clearer understanding of custom connectors and their functionality.

Step #1: General Details
I have updated the host to reflect the address for the latitude and longitude API. The connector relies on this API host and the base URL to determine the method of calling the API.

Step#2: Specify Authentication Type
The Get Latitude Longitude APIs use API key authentication. Under API key section, update a parameter label, name, and location details.

Step #3: Create the connector definition.
Under the “General” section, include a summary, description, and operation ID for this action.

opt for "import from sample" to provide the required details for API connection. The verb list displays a standard range of API request types (GET, POST, PUT, DELETE PATCH, HEAD, OPTIONS). In our scenario, we've chosen the "GET" method and defined the request URL (https://api.geoapify.com/v1/geocode/search?text=address&format=json) before proceeding with the import.
When importing the sample URL, its query parameters become visible in the request section. Each of these parameters needs to be configured.
Within the response area, relevant information is presented in accordance with the HTTP response of the actions. Choose to “default” button.
Simply input a sample of the response JSON into the body section and then click on “import” button.
The validation section exhibits any identified issues within the API definition.

Step#4: Code (preview)
This step is not mandatory, So I’ve skipped it and am proceeding directly to step 5: Test.

Step#5: Perform a test on the custom connector.
Upon successfully creating and authenticating the custom connector by entering the API key, the connector becomes prepared to make API calls. This allows us to examine the response, which includes the latitude and longitude for the provided address.

Our Custom connector is now ready for use!

Creating Power Automate Flow:

According to our needs, we need to develop two flows:

Flow #1: Get latitude and longitude.
The objective behind establishing this flow is to receive an address from the bot, forward it as a request parameter to the GetLatitudeLongitude API (custom connector), and obtain the corresponding latitude and longitude as a response for the given address.

Flow #2: Create Lead
The objective of this process is to gather customer information from the bot and create a Lead record within Dynamics 365 CE.

It’s time to build the Power Virtual Agent!!

We will create the bot to gather lead information when a customer requests a New Internet Connection. When the user initiates the conversation with greetings such as Hi, Hello, or Good Morning, the Power Virtual Agent will promptly guide the user to choose from the following options:

• Need a New Connection
• Broadband Related Queries
  
  

New Internet Connection Process Branch:

In the context of a Power Virtual Agent, it's necessary to prompt customers for specific information, including:

• Enter First Name
• Enter Last Name
• Enter Mobile Number
• Enter Email
• Enter Address
• Enter Comments

In a previous article, I manually created six variables corresponding to these questions (Enter First Name, Last Name, Mobile, Email, Address, and Comments). I also incorporated six "Ask a question" nodes to capture customer details, saving their responses in the respective variables for later use. However, this approach becomes complex when gathering more extensive information from customers.

Introducing a new feature, Power Virtual Agent now includes an "Ask with Adaptive Cards" node. This functionality allows you to incorporate text, graphics, and buttons, enhancing conversational capabilities within your bot.

Step#1: Incorporate an Adaptive Card node to accommodate the Lead Form
Click on the “Add node (+)” option, then choose “Ask with Adaptive Card” you can access the property pane for the node by selecting the card icon.

Alternatively, choose the Node Menu ( : ), and then opt for properties.

In the “Edit JSON” area, input the JSON code for our card. To access a more extensive view of the JSON editor, click on the “Expand” icon. I’ve included the Lead Form JSON code within the editor. Click anywhere outside the editor to proceed.

Based on the inputs detected in the card, Power Virtual Agents automatically create output variables.

Note: Card must contain at least one submit button, as it must be an interactive card that allows a user to submit information back to the bot. If it does not and is only intended to show information to the bot user, we should add card as an attachment to a Message node.

Step #4: To trigger a custom connector via Flow.

An action node has been included and choose the “Get latitude and longitude” flow from the available options. This specific flow is designed to take an address as input and provide latitude and longitude as two separate outputs.

The Getlatitudelongitude API (custom connector) is called based on the address as input, which returns the longitude and latitude for the address. This return values are stored in variables (latitude and longitude) for further process.

Step#5:

To render the map according to the provided latitude and longitude, I intend to utilize the pre-designed static Map gallery adaptive card. I have incorporated the “Ask with Adaptive Card” node and pasted the JSON of the prepared Static Map gallery adaptive card.

Geoapify provides an API that enables us to retrieve a static map image by utilizing latitude and longitude coordinates.

"https://maps.geoapify.com/v1/staticmap?style=osm-carto&width=800&height=600&center=lonlat:<lat_valu...

As per our requirement we need to plugin latitude and longitude variables within adaptive card. This can achieve by using Power FX to make our adaptive card dynamic.

Select the Edit JSON button, then choose Formula. This automatically converts any card the JSON has already presented into Power Fx.

Below is a JSON of a Map gallery card and the resulting Power Fx, where two variables Topic.latitude and Topic.longitude are used instead of a hard-coded value.

Ultimately, the Geoapify API URL (with latitude and longitude values dynamically included) is assigned to the URL of the Map gallery image element. This setup aims to showcase a static map image reflecting the customer’s provider address within the lead form.

Toggle element is added, which allows customers to verify and confirm the location, which is indicated by a highlighted marker in Map.

Step#6:
A conditional node is implemented to determine whether the customer had confirmed the location or not.

Step#7:
An action node has been included and choose the “Lead Creation” flow from the available options. This specific flow is designed to take the customer details, along with the associated latitude and longitude coordinates.

Step#8:
A Message node is integrated to exhibit the statement “Our technical team will be in touch shortly”. and lastly, an End node is incorporated to conclude the chat session.

Test your Bot:

To examine the changes made in Power Virtual Agents, access the Test Bot pane and ensure that “Track between topics” is enabled. The bot will initiate the conversation by displaying message “Hello, I’m internet broadband Company!”.

When the user initiates the conversation with greetings such as Hi, Hello, or Good Morning, the Power Virtual Agent will promptly guide the user to choose from the following options:

• Need a New Connection
• Broadband Related Queries

When the customer chooses the “Need a New Connection” option, the bot will immediately display an adaptive card (“Lead form”). This approach facilitates the gathering of all customer information with a single form, along with the validation of responses and storage of answers in dedicated variables.

The bot exhibits an adaptive card with a map showing the area designated by the provided address. The location is marked with a highlighted marker. Customers can verify the location by using the “confirm the location” toggle button and submitting their confirmation.

Upon confirmation, a lead record is created in the backend by using the customer's details and along with the latitude and longitude coordinates.

After confirmation, a lead record created using the customer’s information, along with the associated latitude and longitude coordinates.

Finally, an email is sent to the customer, notifying them that the technical team will be in touch shortly.

Concluding the technical article, it’s evident that integration of Power Virtual Agent (with Ask Adaptive Card) with external APIs via Custom Connectors and Dynamic 365 CE through Power Automate significantly enhances the capabilities of automated interaction. This integration empowers businesses to engage users more intelligently and efficiently, facilitating seamless data flow and streamlined processes.

Happy Learning and Happy Sharing. Cheers!!