Facebook Built-in NLP

Natural Language Processing (NLP) allows you to understand and extract meaningful information (called entities) out of the messages people send. You can then use these entities to identify intent, automate some of your replies, route the conversation to a human via livechat, and collect audience data.
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, entities are automatically detected in every text message that someone sends.

Contents

1. How It Works
2. Enabling Built-in NLP
3. Handling a Message With Entities
4. Customizing NLP via Wit.ai

How It works

Once Messenger's built-in NLP is enabled for your Facebook Page, 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 entities detected in the body. See Handling a Message With Entities.

Default NLP

By default, Messenger's built-in NLP detects the following entities in English only:

• Greetings
• Thanks
• Bye

It also detects information like date, time, location, amount of money, phone number and email. For example, if someone sends the message, “tomorrow at 2pm” or “2 days before Xmas,” you will get the actual timestamp with the message.
For other languages, check Customizing NLP via Wit.ai.

Enabling Built-in NLP

To enable built-in NLP, do the following:

1. Go to your app's 'Messenger Settings' page.
2. Toggle the "on off" switch to enable/disable built-in NLP for your app.

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 \
  -d "access_token=$PAGE_APP_ACCESS_TOKEN" \
  "https://graph.facebook.com/v2.8/me/nlp_configs?nlp_enabled=$NLP_ENABLED"

You must append the nlp_enabled parameter which will either enable or disable NLP for that Page.

Handling a Message With Entities

Once built-in NLP is enabled, you will see an nlp key in the request sent to your message webhook.
For example, the message, "bye, see you tomorrow at 4pm" would include the following entities:

{...,
  entities: {
    "datetime": [
      {
        "confidence": 0.97249440664957,
        "values": ["..."],
        "value": "2017-05-10T14:00:00.000-07:00",
        "grain": "hour","type": "value"
        }
      ],
    "greetings": [
      {
        "confidence": 1,
        "value": "true"
      }
    ]
  }
}

For each message, the Messenger Platform will return a mapping of the entities that were captured alongside their structured data. The key pieces of information here are the confidence and the value for each entity.
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 app, like "2017-05-10T14:00:00.000-07:00".
You can learn more about the JSON structure of all the entities in the Wit.ai docs

Example Usage

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

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

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

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

Customizing NLP via Wit.ai

You can customize Messenger's built-in NLP to detect additional entities in English, as well as entities in the 57 languages supported by Wit.ai.
To customize NLP with Wit.ai, do the following:

1. Go to your app's 'Messenger Settings' page.
2. In the 'Built-in NLP' section, select one of your subscribed Pages.
3. Add your Wit Server access token. You can find your access token in the Wit App settings.
4. Save your settings.

Updating NLP Settings with the Graph API

You can also update your NLP settings programmatically with a POST request to the Graph API:

curl -i -X POST \
  -d "access_token=$PAGE_APP_ACCESS_TOKEN" \
  "https://graph.facebook.com/v2.8/me/nlp_configs?nlp_enabled=$NLP_ENABLED&&custom_token=$CUSTOM_TOKEN"

You must provide an nlp_enabled option which will either enable NLP or disable NLP for that Page. You can optionally provide a custom_token option, which lets you set a server access token from Wit.