SAS Conversation Designer: interacting with APIs

By making requests through API calls you can expand the functionality of the bots you make with SAS Conversation Designer; allowing your bots to query external sources for up-to-date information, score a model, and many other possibilities. This is very beneficial as SAS Conversation Designer is included in many offerings of the modernized SAS Viya platform, meaning you can easily create bots that are integrated with the other services of the SAS Viya platform or third-party services.

For instance, if you are making a bot that takes feedback from a user you can use sentiment analysis on the feedback to help determine the next appropriate action. The feedback could also be classified by using a model and depending on the classification a new dialogue could start to help the user if they are encountering an issue. Other uses could be calling a model for a loan approval process using information from a user, answering questions about flights by querying current flight statuses, or inform the user how their order is progressing by checking the status of a transaction. All of these are potential applications of using APIs with SAS Conversation Designer.

To interact with APIs, we will be using the Web Service Data Provider node. With it, your bot can execute HTTP methods to access RESTful services. Requests can also be made through SAS Code nodes, but we will focus on the Web Service Data Provider node.

The Web Service Data Provider Node

In case you are new to working with APIs let's describe what a call looks like. A REST API call is delivered to a resource via a URL and is composed of a Method that declares what action will be taken on the resource, a Body which is the data that will be sent to the resource, and Headers which are a list of HTTP header keys and their associated values. Headers provide a simple means of passing additional information with the request and are often used for functions like authentication.
You can find the Web Service Data Provider Node under the Run Code tab:

Here are the Web Service Data Provider Node's properties as per the documentation:

Name - specifies the name for this node. A value must be specified for this property.
URL - specifies a URL. A value must be specified for this property.
Method - specifies the method to use with the URL that is provided. A value must be specified for this property. The options include the following:
- DELETE - deletes a resource
- GET - retrieves a representation of a resource
- POST - creates a new resource
- PUT - updates a resource
Body - provides the HTTP body code that this node should run and send as part of the request when it is activated in a dialogue flow. This is honored only on POST and PUT actions. Click Show Full Code Editor to open the Body window. Next, enter the code that you want the node to run when it is activated. Finally, click OK to save your changes.
Headers - specifies any HTTP header keys and their associated values that the call might need.
Output name - specifies a label for whatever is retrieved from the server call when the Web Service Data Provider node is run.

For a more detailed look, read the documentation. Let's go through an example that uses both the GET and POST to see how to use this in practice.

Example: Iris Identification Bot

This bot helps identify the species of an iris flower and provides some basic information about them. It helps identify the species by asking the user for measurements about the iris' petal width and length and then using this knowledge to score a model. It provides information about the species by performing a REST call to the Wikipedia page on that specific species.

Aligning with this bot’s two goals we'll focus on two dialogues, one for scoring the model, and one for querying Wikipedia.

Score Model Dialogue

Note on the Model: The model is a decision tree trained on the iris flower data set and published to SAS Micro Analytic Service (MAS) with the name dtree_iris.

To acquire the data for the model prediction we use multiple HTML Response nodes followed by Text Input nodes. To keep things simple, we won't be verifying the inputs, though for real applications Logic Nodes and clever use of Apache Velocity will help make the experience more user friendly. Once the input data has been acquired, we can run the node to score the model. By omitting the first part of the URL (the hostname) SAS Conversation Designer will use the same host that it's already running on which lets it handle authorization for us.

These are the parameters of the web service data provider node used to score the model:
Web Service Data Provider

Name: Score Model
URL: /microanalyticScore/modules/dtree_iris/steps/score
Method: Post
Body:

{"inputs": [
{
"name": "petal_length",
"value": $petal_length
},
{
"name": "petal_width",
"value": $petal_width
}
]}

Headers:

Accept - application/json; application/vnd.sas.microanalytic.module.step.output+json
Content-Type - application/json; application/vnd.sas.microanalytic.module.step.input+json

Output name: score_out

With the model prediction done all that is left is to share it with the user. The results of the call are stored in the variable we chose to name $score_out, though you can choose whatever naming scheme makes the most sense when creating your own bots. The format of $score_out is a JSON file, so we'll use a Modify Context Data Provider node to create a variable named $species by extracting the prediction:
Modify Context Data Provider

Name: Set Species
Template: $JsonTool.parse($score_out).outputs.get(0).value.root()
Output names: species

The output has a space and quotations marks we don't need so we'll use one last Modify Context Data Provider node to clean that up:

Modify Context Data Provider

Name: Clean Species String
Template: $species.replace(" ", "").replace('"', "")
Output names: species

With all preparation completed we can simply use an HTML Response node that displays the model prediction:
HTML Response

Name: Model Results
HTML: It appears that your iris is a $species.

Which will render in the chat as:

Wiki Retrieval Dialogue

This part will use Wikipedia as a source for getting more information about the predicted species. Wikipedia has an API to interact with many of its features. For a given page we can use the GET method to retrieve just the extract. We will not require either headers or a body for this request, which also means you can copy and paste the URL used into your browser to take a look at the exact JSON it will return.

Conversation Designer lets you use variables within the URLs of a Web Service Data Provider node, allowing us to have one flow for all three species. To allow the user to choose which species they want to learn about we'll use a Button node followed by Text Input Node, this sets the page_title according to the predefined button choices. On the buttons node under Label is what the user will see, and Display Text is what will be passed to the Text Input node.

These are the parameters of the web service data provider node used for the query:
Web Service Data Provider

Name: Wiki Retrieval
URL: https://en.wikipedia.org/w/api.php?format=json&action=query&prop=extracts&exintro&explaintext&redirects=1&titles=$page_title
Method: GET
Body: N/A
Headers: N/A
Output name: wiki

With the query completed, we can display the results. The JSON that's returned has a slightly odd structure, so you'll see a bit of code using Apache Velocity to extract the pageId.

HTML Response

Name: Display Wiki Results
HTML:

#foreach($key in $wiki.get("query").get("pages").keySet())
#set($pageId = $key)
#end
 
According to Wikipedia:
 
$wiki.get("query").get("pages").get($pageId).get("extract")

Which renders as such:

Summary

This shows how to interact with REST APIs using SAS Conversation Designer. There are many possible use cases involving REST calls, so hopefully, this example helped spark some ideas for other use cases.

For the call that queries Wikipedia, a similar setup could be used for an FAQ bot that not only shares a link to a resource or documentation but also retrieves the relevant information and shares it within the chat. A solution like this helps leverage pre-existing work and has the potential to save time because when the resource is updated so will the bot's response.

Similarly, being able to interact with the whole of Viya's APIs opens up many more opportunities for integrating resources besides scoring models, like being able to trigger a decision flow in SAS Intelligent Decisioning.

Thank you for reading. Any feedback or questions are welcome!