Alterations – A Hidden Gem In QnA Maker

Qna Maker is a great and easy tool. It can help you to build, in a matter of minutes, a mini chatbot. A chatbot that will replace your boring FAQ page.Since the last releases, a lot of cool features have been added.

  • Active Learning – a built in function to let your users help you with suggesting the correct answer to their question.
  • Multi Turn Questions – in some cases you will need to ask the user multiple questions to get to the correct answers. Ex. ‘I am looking for a school.’ Then you might ask the user first: ‘What school are you looking for?’ with some suggestions like ‘Music School’, ‘Primary School’, … With multi turn this is a possibility without any extra coding in your bot.
  • Publish bot – before this option you had to built your own chatbot with the SDK that calls the Qna Maker service. Now you can create a new chatbot within the Qna Maker Portal.

But there is one feature that was there from the beginning. But it is hidden within the Qna Maker API. 

Alterations – less training with synonyms

A gift equalts to a present. The words mean the same

Alterations can be compared to synonyms. Its a list of words that mean the same thing. For example the word ‘gift’ can be swapped by the word ‘present’. Or you might even use it for abbreviations. ‘GDPR’ for example is a widely used term, but some people might call it AVG (Dutch term)But why would I call this a hidden gem? First of all I am not a native English speaker and I don’t live in an English speaking country. So I built bots in other languages than English. Why is this an important fact? Well the Qna Maker has been pre-trained with a lot of synonyms in English and some other big languages. And you guessed well, its not done in the language I need (not at the moment at least).When you add a list of well chosen alterations, you will make your QnA Maker smarter in a short time. Since you need to add less alternative questions in your knowledge base.Enough talking. I said it’s a hidden gem. Because you can do this within the Qna Maker portal. You need to use the API for it.

How its done!

Lets start by open your favorite REST API Client (Ex. Postman)

So the API has 2 function for the alterations.

The first one is getting a list of all the alterations that have been stored. The second one is to override your current list.

Get current alterations

Call the REST API

  • GET {Endpoint}/qnamaker/v4.0/alterations

Endpoint is for example in the headers of your request the Ocp-Apim-Subscription-Key which is equal to the Key you can find in the Azure Portal.

You can find the endpoint and key for your cognitive service in the Azure Portal

In Postman it would look like this:

An example of how the REST API can be called in Postman

If you have never used alterations then the first time you execute this, you will receive an empty array:{“wordAlterations”: []}

Add alterations

Now let us add some alterations. To do this we need to call the REST API

  • PUT {Endpoint}/qnamaker/v4.0/alterations

At this point Endpoint is the same as to get the alterations. And we also need to add the Ocp-Apim-Subscription-Key to the header.On top of that we need to add some alterations too. So in the body of our request we can add something like this:{    “wordAlterations”: [        {            “alterations”: [“auto”,“wagen”]        },        {            “alterations”: [“gebruiker”,“medewerker”]        },        {            “alterations”: [“wachtwoord”,“paswoord”]        }    ]}So the structure exists out of the ‘wordAlterations’ object that is an array of different ‘alterations’. An ‘alterations’ object again is an array of a list of words that are synonyms.

An example of how adding alterations to the Qna Maker service can be done

Now read this carefully.

  1. This function replaces all your alterations that were already stored in your Qna Maker service
  2. Alterations are added for all the knowledge bases within your QnA Maker service.


Sadly enough alterations are not built in into the Qna Maker portal. But do not forget them while you are building a knowledge base. They can really help you to improve the quality of your knowledge base and will save you time in training it. So less training with synonyms.More detailed information about the alteration function can be found here:

[Intially posted here]


Stay tuned.