Natural Language Processing for Messenger Platform

Natural Language Processing (NLP) allows you to understand and extract meaningful information (dates, time, and more) from messages that your business receives. You can use this information to identify intent to implement the messaging experience needed for the conversation.

Using Meta's Built-in NLP reduces API calls that count against messaging rate limits.

How It Works

Before a message is delivered to your business, Meta's Built-in NLP first parses the messages to help detect meaning and extract information using Wit.ai from Meta as well as a confidence level that indicates the probability the parser is correct. The message will then be relayed to your business as usual, along with any meaningful information, entities and traits, detected in the message. For example, if a message contains a phrase like “hello, tomorrow at 2pm”, you will get a trait that includes the greeting and an entity that includes the actual timestamp.

Language identification is automatically enabled with built-in NLP, and the date and time are automatically localized based on the locale in the person's profile.

Wit.ai

The Wit.ai is the app that parses the message and creates the entities from a person's message. You can use the default Wit.ai for supported languages or create your own Wit.ai app for each language you want to support. When Messenger Platform receives a message, it will first find the top detected language, and use the associated Wit.ai app for extracting the entities. If there isn't a Wit.ai app linked to the top detected language, the default language model will be used.

Visit our Wit.ai documentation for more information about Wit.ai apps and creating and testing your own custom Wit.ai app as well as a list of supported languages .

Add NLP to Your Page

There are two ways to add NLP to your business Page, using the Meta App Dashboard or programmatically.

App Dashboard

To add Built-in NLP using the App Dashboard , under Products navigate to Messenger > Settings and scrolldown to the Built-in NLP section. Select the Facebook Page from the dropdown menu and toggle to ON. Then select the Language Model, which includes an option to add multiple languages. Advanced settings allow you to select the NLP version, the verbose flag to get more information about entities, and n-best values for each intent and trait you want to receive. This setting also determines the number of detected locales returned.

Random samples from your past conversations in the Page inbox will be compiled, and will show in a newly created Wit app. The samples will be available for tagging in your Wit.ai app immediately.

Programmatically

To add NLP programmatically, you will need:

• A Page access token requested from a person who can perform the MESSAGING task on the Page
• The Page ID
• The pages_messaging and pages_manage_metadata permissions

Send a POST request to the /PAGE-ID/nlp_configs endpoint with the nlp_enabled parameter set to true to enable NLP for the Page. You can also include the model parameter to set a language other than the default, English.

View the Page NLP reference for more information.

Sample Request

curl -i -X POST "https://graph.facebook.com/LATEST-GRAPH-API-VERSION/me/nlp_configs
      ?nlp_enabled=true
      &model=PORTUGUESE 
      &access_token=PAGE-ACCESS-TOKEN"

You can use the custom_token parameter to use your custom Wit.ai app, and update NLP parameters with POST requests. To disable NLP, send a POST request with the nlp_enabled parameter set to false.

Webhook Notification

If Built-in NLP is enabled, the pertinent NLP entities and traits will be included in the message webhooks notification for each message object.

Entities and Traits

The Messenger Platform returns the following entities by default.

Built-in Traits

The Messenger Platform returns the following traits by default.

Visit our Wit.ia documentation to learn more about available entities, traits, and more.

Example Notification

The following example is for a message that includes the phrase "see you tomorrow at 4pm" and would include the wit$datetime and wit$sentiment entities after parsing:

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

Parse an NLP Message

In your messages Webhooks, you can respond to a message by taking advantage of Default NLP. For example, if you have a handleMessage() function that responds to each message received, you can use the greetings entity to send an appropriate response:

function firstTrait(nlp, name) {
  return nlp && nlp.entities && nlp.traits[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
  }
}