Nl Escalation Adapter


The purpose of this adapter is to confirm a user's intent to escalate, and call an intent in a Chatbot instance to gather the data needed to escalate.

Once the user completes the form, the intent executes a js_callback: escalate. This triggers the escalateToAgent action on the Chatbot SDK. At this point, the second adapter is subscribed to the escalate action, to retrieve the information and initiate the live chat.

You must configure several linguistic settings in your Backstage instance to trigger the escalation.

Adapter code and public Github repository

This adapter can be found in the Inbenta Github adapters repository.

Click here to see the adapter code

Important note about the order of elements in the array

Make sure that you respect the order of the elements in the adapters array: because of the callback adapter system, to avoid any conflict, the first element of the adapter array must be the escalation adapter, and the next one the external chat adapter. Do not alter the order, or the subscriptions may not execute the callback as expected. This can cause the chatbot to malfunction or show unexpected behavior.

Internal Adapter

This adapter is included in the Chatbot SDK to facilitate the steps to integrate Hyperchat and the escalation.

To use an internal adapter, you must set the adapters array like this:

adapters: [
    SDKlaunchNLEsclationForm(checkAgents,'ChatWithLiveAgentContactForm',rejectedEscalation, noAgentsAvailable, 2)

Note: The SDK at the beginning of the function name is what forces the SDK to use the internal adapter.

If this adapter meets your requirements, you can use it as explained above. If you need to modify its behaviour, copy the code at the end of this page to a new Javascript file and import it into your configuration. Remember that if you do this you must change the name of the function to launchNLEsclationForm.

Escalation conditions

When the user asks a question, the adapter detects if the Inbenta API returns an escalate flag. If it does, the escalation starts:

  • The bot asks the user if they want to speak with a human. This shows as a systemMessage carrying the label escalate-chat. You can modify this in the configuration.

    • User rejects the escalation: rejectedEscalation is displayed (see below for more information).

    • User accepts the escalation:

      • If there are agents available, a message is sent to the API with the second parameter of the configuration. This must be a conversational form with js_callback=escalateToAgent.

      • If there are no agents available, noAgentsAvailable value is displayed (see below for more information).
  • The chatbot displays n times in a row a "no results" message (the default threshold is three). This also triggers an escalation, but the bot first checks whether agents are available, and only start the form if this is the case.

Configuration parameters

The launchNLEsclationForm function creates the adapter. These are the entry parameters:

  • External checkAgents function: This must be a function. It comes from the external chat adapter and checks if there are available Agents. If you use the code samples below, make sure to replace checkAgents with the appropriate function name from your chosen product.

  • ChatWithLiveAgentContactForm: This String is the string sent to the API. It must match the form that will ask for the userInformation, and use the js_callback to trigger the escalateToAgent action.

  • rejectedEscalation: An object that defines what to display when the user rejects the escalation. There are two options:

    • action: IntentMatch: Sends the value parameter to the API, and should match with an intent.
    • action: displayChatbotMessage creates an answer directly with the given value.
    • value: Message that is either sent to the API or displayed as a chatbotMessage.
  • noAgentsAvailable: An object that defines what to display when there are no agents available and the client has tried to speak with a human. There are two options:

    • action: IntentMatch: Sends the value parameter to the API, and should match with an intent.
    • action: displayChatbotMessage creates an answer directly with the given value.
    • value: Message that is either sent to the API or displayed as a chatbotMessage.
  • No-results (default 3): number of times in a row the chatbot will display a no-results message before trigger the escalation.

  • hideEscalateIntentMessage: (default true): When set to true, it will ignore the message given in the intent that triggers the escalate systemMessage

RejectedEscalation and noAgentsAvailable can be configured in order to either show the value as a chatbotMessage if the action is displayChatbotMessage, or it can be sent to the InbentaAPI in order to retrieve the answer from an Intent.

In the example below, we show the value of the rejectedEscalation as a chatbotAnswer, and do a linguistic match in the NoAgentsAvailable to show the content of the intent.

Tracking events

From version 1.16 and above the adapter now tracks the user interaction with the escalation. We track 3 different situations:

  • Contact attended: The conversation has been escalated to an agent.
  • Contact unattended: There were no agents available at the moment of the conversation
  • Contact rejected: The user rejected the escalation.

The tracking is performed by the track method Link to the dashboards configuration.


//Rejected escalation will display "What else can I do for you?" as a `chatbotMessage`
var rejectedEscalation={
  value:'What else can I do for you?'

//NoAgentsAvailable will send `NoAgentsAvailable` to the API, and should match an intent, which answer will be displayed as a chatbotMessage.
var noAgentsAvailable={

var authorization = {
InbentaChatbotSDK.buildWithDomainCredentials(authorization, {
adapters: [

This is the systemMessage that offers the escalation. If you want to modify the displayed message, modify the label in the configuration.


The following message appears when there are no agents available. In this case, since the noAgentsAvailable action is intentMatch, it does a linguistic match with an intent in the Backstage to display the answer:


The last message appears when the user rejects the escalation. Since we define the rejectedEscalation action to displayChatbotMessage, the value is directly displayed as a chatbotMessage.