Nl Escalation Adapter 2


The purpose of this adapter is to check for the availability of agents, set the agents_available variable so the automatic transitions are applied correctly and track the escalation information.

The adapter does the following actions:

  • It checks if any shown chatbot message has the directCall attribute set to escalationOffer. This intent is usually the start of the escalation dialog where the user gets asked if they want to speak with an agent. Its directCall attribute is escalationOffer. While it processes the messages of the escalation dialog, the SDK checks if there are agents available in the background. It sets the agents_available variable accordingly.
  • It detects if an escalationStart action is called. This is usually set as an intent callback. When an intent callback has a function name escalationStart, it calls the chatbot action that the adapter is subscribed to. It does the following actions:
    • Empties the answers (to prevent from showing an end-form direct Answer)
    • Checks the agents availability and sets the agents_available variable accordingly.
    • Sends a directCall to escalationStart. Usually the intent with this directCall is the one that starts the escalation process. This makes it possible to redirect from any intent with an escalationStart action to the escalation start intent.
  • The intent with the escalation form must have an action with a callback function name escalateToAgent. This triggers the escalateToAgent action. The second chat adapter is subscribed to the escalateToAgent actio. It retrieves the information sent by the callback and initiates the live chat.
  • Finally, the adapter is subscribed to onSetExternalInfo. Inbenta HyperChat triggers onSetExternalInfo when escalation occurs. It uses this subscription to receive data from the chat system and track any information provided.

For more information about the required escalation dialog and intents, see Default Contents For Live Chat Escalation (This link redirects you to the Help Center).

This link contains the default intents to make the escalation process work out of the box. You can modify the dialog and intents to meet your desired purposes. Some examples are:

  • Separate the "Offer Escalation" and the "Start Escalation" parts of the dialog to insert custom actions in between.
  • Update the "no agents available" intent to add a form and send the data to an external system via a webhook for later processing.
  • Update the "rejected escalation" intent to offer the user the possibility to do a custom action.

Proceed at your own risk when you update the default dialog and intents. Test your desired functionality thoroughly before you deploy the solution into production.

Adapter code and public Github repository

You can find this adapter in the Inbenta Github adapters repository.

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 escalation adapter must precede the external chat adapter within the adapter array. 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 behaviour. For example:

adapters: [

Internal Adapter

This adapter is included in the Chatbot SDK to facilitate the steps to integrate Hyperchat and the escalation from version 1.31.0

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

adapters: [

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 from the github 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 NLEscalation2.

Escalation conditions

The agents_available variable must exists in your instance, as this is where the system stores the detection of agents availability.

There are different ways you can perform the escalation, but by default, the adapter looks for the following two conditions in the intents:

escalationStart callback : When the system detects an intent with this callback function name, it expects the user to be redirected directly to the escalation. Your instance must contain an intent with the directCall escalationStart, and the API then performs the automatic transition depending on the agents_available variable.

escalationOffer directCall: This directCall must be in the parent node of the escalation dialog. It serves to check for agents and set the variable before asking if the user wants to chat with a human.

Configuration parameters

The NLEscalation2 function creates the adapter. The entry parameters are the following:

  • 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.


const checkAgents = () => Promise.resolve(true);

Tracking events

Because most of the events are now tracked automatically in the API (TRACKING attribute), the adapter only does one tracking event. It triggers when the escalation is done and sends the required information to the API.