Skip to main content

$nlp.match

The method classifies the text in the context of the specified state.

Syntax​

The method accepts the arguments:

  1. The request text.
  2. The full path to the theme or state where the classification must be performed.
$nlp.match("bye", "/");

Return value​

{
    "parseTree": {…},
    "targetState": "/Order",
    "pattern": "how to (make|create) an order *",
    "effectivePattern": "how to make an order *",
    "score": "1.0",
    "nBest": […],
    "nluResults": {…},
    "entities": […]
}

The method returns an object that contains the fields:

  • parseTree is the parse tree for the request.
  • targetState is the state triggered by the request.
  • pattern is the full pattern triggered by the request. null if an intent is triggered.
  • effectivePattern is the pattern part that matched the request. null if an intent is triggered.
  • score is the pattern or intent weight. From 0 to 1.0.
  • nBest is the array of the activation rules with the highest probability.
  • nluResults is the nluResults object.
  • intent is the information about the triggered intent. The field is missing if a pattern is triggered.
  • entities is the array of the entities recognized in the request.
info

By default, the nBest, nluResults, intent, and entities fields contain the same data as $context.nBest, $context.nluResults, $context.intent, and $entities. Differences are possible if you use slot filling or reorder the activation rules.

If the classification has no results, the method returns null.

$nlp.match and slot filling​

If the user request matches an intent with slot filling and the bot asks clarifying questions:

  • The objects in the $entities array have an additional slot property. The property contains the name of the slot matched by the entity.
  • The $context.intent object does not have a priority field.

However, if you process the same request via $nlp.match, entities and intent in the method response does not reproduce these changes.

$nlp.match and activation rules​

When you use the $nlp.match method, the activation rules always trigger in the following order: patterns first, then intents.

If you reorder the rules via the selectNLUResult handler, it does not affect nBest and nluResults in the $nlp.match response.

How to use​

The $nlp.match method can be used to manage the order in which phrases are classified in specific contexts.

For example, there is a script in which the bot informs clients about ongoing promotions. Information about promotions is stored in a third-party service.

state: Promos || modal = true
    # Display the promotion names
    a: {{$session.promos.join(", ")}}
    a: Which of our promotions would you like to know more about?

    state: Get
        event: noMatch
        script:
            $temp.match = $nlp.matchExamples($parseTree.text, $session.promos);
        # If the promotion name is found in the request, save it and switch to the /PromoDetails state
        if: $temp.match && $temp.match.weight >= 0.2
            script:
                $session.promoSelected = $temp.match.example;
            go!: /PromoDetails
        # If not, search for the matches in other states
        script:
            $temp.match = $nlp.match($parseTree.text, "/");
        # If a match with another state is found, move there
        if: $temp.match && $temp.match.score >= 0.2
            script:
                $parseTree = $temp.match.parseTree;
            go!: {{$temp.match.targetState}}
        # If the request still isn’t recognized, display the following message:
        a: I don’t understand you. What promotion would you like to know about?

Let’s create a Promos state where the list of promotions is displayed to the client. To stay in the context of this state until the client’s request is processed, set the modal flag to true.

As mentioned before, information about promotions is stored in a third-party service, not in the bot script. Therefore, using patterns to obtain this information can be inefficient. Instead, we use the Get state with the noMatch event that is triggered on unrecognized client requests.

Since we still want to recognize the client’s phrase to tell them about promotions, we use the $nlp.matchExamples method to determine the requested promotion and redirect the dialog to the right state. If the received request could not find the corresponding promotion name, then use the $nlp.match method to recognize the whole phrase. If the corresponding state still wasn’t found, display the following message:

I don’t understand you. What promotion would you like to know about?
caution
If the modal = true flag is specified in the state passed as an argument to $nlp.match, then only its nested states are matched by the method.
Is this page useful?