Step 6: Integrate into Freshdesk Messaging Bot

You can also use your Yext Search experience to seamlessly power your Freshdesk Messaging Bot. This is a lightweight implementation that doesn’t require you to build a frontend in Yext, just configure your backend!

While each bot flow is unique we below is a boilerplate option for powering your bot with Yext AI Search. Be sure to touch base with your Freshdesk account team for more bespoke integrations with Yext’s technology.

Define an Input

The first step of integrating Yext AI Search into your Bot will be to define which value, or question, from the consumer will serve as the search query.

Create a new message in your flow to provoke a question. Click “Get Response” and select the define the input option as “Text Field”. Following that message, add an action “Set Property”.

Action Type: Set property
Save in: Conversation
Property name: Input
Preoperty value: Insert > Dialogues > the previous dialogue

Create a New API Call

Now we’ve defined how we want to capture our visitor query. Let’s define the API call that we’ll make to Yext to retrieve results to display.

Within Flows, select Configure (next to Build). Select API library and create a new API. Give your new API a name, something like “Call Yext”. The Method will be “GET”. The base structure of the URL is as follows:

https://liveapi.yext.com/v2/accounts/me/answers/query?v=[[the_date]]&experienceKey=[[experienceKey]]&version=PRODUCTION&locale=[[locale]]&api_key=[[apiKey]]&input=[[input]]

You can add further parameters if you like such as context, referrerPageUrl or Limit for example.

light bulb
Tip
Note: Freshdesk Bot Builder already URL encodes all API calls. This means that if you’re including a limit parameter from any ‘Query’ endpoint, you do not need to preemptively encode the value. For example, &limit={"help_articles" : "5"} will run successfully.

Make sure to use the variables specific to your search experience. You’ll find all of the required variables within the ‘Experience Details’ tab of your chosen Search Experience.

Importantly, for input insert (found on bottom right of input box) the dialog value set in the previous step. This means that you’re passing the customer response (saved as a value) to the Search API call as the query.

Once you’ve input this variable, in the Test API section below you can define a user input and test the structure and content of the results returned by Yext.

Save your API and now navigate back over to the ‘Build’ tab of the builder.

Call your API

Let’s call the API you just created. Add a “Trigger an API” action within your flow and select the Yext API you just created.

Conditional Checks

Once you call the Yext API there are possible outcomes, each requiring a unique flow:

  1. A direct answer was given
  2. Universal results were returned as expected
  3. No results returned

Check for Direct Answer

One of the key benefits of using Yext is the ability to retrieve direct answers from unstructured content to answer more complex queries. To take advantage of instances where the Yext API is able to return a direct answer check if response.directAnswer object in the API response is present. In a private dialogue create a conditional check to see If the condition is true by clicking on the two arrows in the top right of the text box. If response.directAnswer is greater than zero redirect to a new portion of the flow that maps this value. Create a new dialog announcing your direct answer. In the dialog click “+ Get Response” and select “Article” type. In Article Title insert APIs and select response.directAnswer within the Body subheader.

Your conditional logic will redirect to a new portion of the flow if a direct answer is not present.

Check for No Results

If there is no direct answer your bot should next check if there was no response returned at all. Similar to the conditional check for response.directAnswer, create another private dialogue with a conditional check to see if response.modles is greater than zero. If not, redirect to a new portion of the flow gracefully handling no results. Perhaps ask the user to ask their question in a new way, or redirect to a live agent. If response.modules is greater than zero map the fields returned from the API to your your bot frontend.

Map your Results

With the results returned from the Yext API, you’ll now map you’ll map the results returned from the Yext API. Data structure will vary depending on how you’ve structured your Yext Knowledge Graph, but you’ll likely want to leverage response.modules.results.data.name, and …data.landingPageUrl to at least return the entity name and landing page.

You should also consider creative ways to display information on the frontend. For example, if you’re returning help articles you could consider adding the externalArticleUpdateDate or category to the frontend mappings in the bot.

Once you’ve returned results from Yext you can continue to build out the flow as you see appropriate! We suggest adding a step asking if the results answered the question. If not, offer them a way to ask a question a different way, or redirect them to an agent. Up to you!

light bulb
Tip
Note: While you’ll be able to capture all query analytics, Freshdesk Bot does not have the ability to writeback click events. If a consumer clicks on one of the results returned from Yext, this will not appear in your Yext analytics, only their initial question will.