Built-in NLP in Workplace

Overview

Natural Language Processing (NLP) allows you to understand and extract meaningful information (intents, entities and traits) out of the messages people send. You can then use this information to identify intent, automate some of your replies, route the conversation to a human via livechat, or any other requirement your chat experience needs.

If you are currently leveraging an NLP API, you have to make an extra call when you receive the user message, which adds latency and complexity (example: async, troubleshooting, etc.) With Built-in NLP, intents and entities are automatically detected in every text message that someone sends.

Built-in NLP

Powered by Wit.ai, Built-in NLP is a simple way for you to incorporate NLP into your bot. This feature is integrated within the Workplace Platform, and automatically detects meaning and information in the text of messages that a user sends before it gets passed to the bot.

Built-in NLP detects many entities and traits from a list of defaults (such as greetings, distance, and duration) that are supported in several languages. To view the most updated list, please click here.

Contents

• Default NLP
• Entities and Traits
  • Language Support
• Enabling Built-in NLP
• Handling a Message With NLP
• Customizing NLP via Wit.ai
• Page Inbox Integration

Default NLP

Once Workplace's built-in NLP is enabled for your Custom integration, it automatically detects meaning and intent in every text message before it is sent to your bot. The message will be relayed to your bot as usual, along with any meaningful information detected in the body. See Handling a Message With NLP.

Entities and Traits

By default, Workplace's Built-in NLP detects the same entities and traits supported by the Messenger Platform.

Dates and times are automatically localized based on the locale sent in the user's profile.

For example, if someone sends the message, “tomorrow at 2pm” or “2 days before Xmas,” you will get the actual timestamp with the message.

Language Support

By default, Workplace's Built-in NLP detects the languages supported by the Messenger Platform.

Enabling Built-in NLP

To enable Built-in NLP, do the following:

1. Go to your Custom Integration details in the Admin Panel > Integrations.
2. Make sure your custom integration has the Message any member permission
3. Toggle the "on off" switch to enable/disable Built-in NLP for your integration.

Advanced Settings

Built-in NLP also supports the following advanced settings that let you further customize the nlp object included in messages webhook events. To enable/disable these settings, click the 'Advanced Settings` button:

• Versioning: Sets the Wit API version to use.
• N-best: Returns the n-best intents and traits as opposed to only the top one.

Enabling Built-in NLP with the Graph API

You can also use the graph API to enable built-in NLP programmatically:

curl -i -X POST \
  "https://graph.facebook.com/v2.8/me/nlp_configs?nlp_enabled=true"
  -H 'Authorization: Bearer $token' \

You can disable NLP using nlp_enabled=false on the request above.

Handling a Message With NLP

Once Built-in NLP is enabled, you will see an nlp key in the request sent to your message webhook.

For example, the message, "see you tomorrow at 2pm" would include the following information:

{...,
    "entities": {
    "wit$datetime:datetime": [
      {
        "id": "340464963587159",
        "name": "wit$datetime",
        "role": "datetime",
        "start": 8,
        "end": 23,
        "body": "tomorrow at 2pm",
        "confidence": 0.9648,
        "entities": [],
        "type": "value",
        "grain": "hour",
        "value": "2020-06-16T14:00:00.000-07:00",
        "values": [
          {
            "type": "value",
            "grain": "hour",
            "value": "2020-06-16T14:00:00.000-07:00"
          }
        ]
      }
    ]
  },
  "traits": {
    "wit$sentiment": [
      {
        "id": "5ac2b50a-44e4-466e-9d49-bad6bd40092c",
        "value": "neutral",
        "confidence": 0.6162
      }
    ]
  }

}

For each message, the Workplace will return a mapping of the entities and traits that were captured alongside their structured data. The key pieces of information here are the confidence and the value for each entity or trait.

confidence is a value between 0 and 1 that indicates the probability the parser thinks its recognition is correct.

value is the parser output. For example, 2pm can be converted to an ISO string you can use in your bot, like "2017-05-10T14:00:00.000-07:00".

You can learn more about the JSON structure of all the entities and traits in the Wit.ai docs

Example Usage

In your messages webhook, you can update the logic used to respond to messages by taking advantage of Default NLP. For example, if you have a handleMessage() function in your webhook that responds to each message received, you can use the wit$greetings trait to send an appropriate response:

function firstTrait(nlp, name) {
  return nlp && nlp.traits && nlp.entities[name] && nlp.traits[name][0];
}

function handleMessage(message) {
  // check greeting is here and is confident
  const greeting = firstTrait(message.nlp, 'wit$greetings');
  if (greeting && greeting.confidence > 0.8) {
    sendResponse('Hi there!');
  } else { 
    // default logic
  }
}

Replicate this logic for other entities and traits, and you will be on your way to using Built-in NLP!

Customizing NLP via Wit.ai

You can customize Workplace's Built-in NLP to detect additional intents, entities and traits in English, as well as in the 132 languages supported by Wit.ai.

To customize NLP with Wit.ai, do the following:

1. Go to your Custom Integration details in the Admin Panel > Integrations.
2. Make sure your custom integration has the Message any member permission
3. Toggle the "on off" switch to enable/disable Built-in NLP for your integration.
4. In the Language Model Selection, select the 'Custom Model'.
5. Select 'Create a new Wit app'. You will be prompted to Login into Wit.ai, using either a Facebook or GitHub account.
6. Name your Wit app and select its language. Click 'Continue'.
7. Save your settings.

Updating NLP Settings with the Graph API

You can also update your NLP settings programmatically using the Graph API.