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, 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, intents and entities are automatically detected in every text message that someone sends.
Once Messenger's built-in NLP is enabled for your Facebook Page, it automatically detects meaning and intent in text messages before it is sent to your Messenger experience. The message will be relayed to you as usual, along with any entities detected in the body. See Handling a Message With Entities.
By default, Messenger's built-in NLP detects the following information:
Information | Entity or Trait |
---|---|
Greetings (English only) |
|
Thanks (English only) |
|
Bye (English only) |
|
Date/Time |
|
Amount of money |
|
Phone number |
|
Email address |
|
Distance |
|
Quantity |
|
Temperature |
|
Volume |
|
Location |
|
Duration |
|
URL |
|
Sentiment |
|
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.
By default, Built-in NLP supports the following languages. For other languages, check Customizing NLP via Wit.ai.
Language | Language Code | Graph API model |
---|---|---|
Arabic | ar | ARABIC |
Chinese (simplified & traditional) | zh, zh-Hans, zh-Hant | CHINESE |
Croatian | hr | CROATIAN |
Danish | da | DANISH |
Dutch | nl | DUTCH |
English | en | ENGLISH |
French | fr | FRENCH_STANDARD |
Georgian | ka | GEORGIAN |
German | de | GERMAN_STANDARD |
Greek | el | GREEK |
Irish | ga | IRISH |
Italian | it | ITALIAN_STANDARD |
Hebrew (modern) | he | HEBREW |
Hungarian | hu | HUNGARIAN |
Korean | ko | KOREAN |
Norwegian Bokmål | nb | NORWEGIAN_BOKMAL |
Polish | pl | POLISH |
Portuguese | pt | PORTUGUESE |
Romanian | ro | ROMANIAN |
Spanish | es | SPANISH |
Swedish | sv | SWEDISH |
Vietnamese | vi | VIETNAMESE |
To enable Built-in NLP, do the following:
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:
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/v7.0/me/nlp_configs?nlp_enabled=$NLP_ENABLED"
You must append the nlp_enabled
parameter which will either enable or disable NLP for that Page.
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 4pm" would include the following information:
{...,
"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
}
]
}
For each message, the Messenger Platform 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, 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
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 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
}
}
Replicate this logic for other entities and traits, and you will be on your way to using Built-in NLP!
Language identification enables you to handle multiple languages. Language identification is automatically enabled with built-in NLP. The nlp
key in the request sent to your
message
webhook will return the top detected locales for the message. For example, the message “bonjour les amis” would include:
{
...,
"detected_locales": [
{
"locale": "fr_XX",
"confidence": 0.9986
},
{
"locale": "ar_AR",
"confidence": 0.0014
}
]
}
confidence level between 0 and 1.
You can then use this information to gracefully handle the incoming requests.
You can assign a different Wit.ai app (using either a Default Model for the supported languages, or a Custom one) 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.
You can customize Messenger'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:
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"
The following query parameters are supported:
Property | Type | Description |
---|---|---|
| Boolean | Optional. Specifies whether NLP is enabled for the Page. |
| Enum | Optional. Specifies the NLP model to use. Either a default model, or "CUSTOM". |
| String | Optional. Wit.ai server token for integrating a custom model. |
| String | Optional. Specifies which Wit API version to use. |
| Integer | Optional. The maximum number of intents, traits and detected locales to return, in descending order of confidence. Minimum 1. Maximum 8. Defaults to 1. |
| JSON | Optional. Specifies the language support mapping to use. Accepts a JSON object of valid ISO 639-1 language code mapped to object in the form of {"model": Enum, ?"token": string}. Model is either "default" or "custom", and "token" is required when "custom" is specified. Example: {"en": {"model": "default"}, "zh: {"model": "custom", "token": $TOKEN}}. Overrides the previous value.. |
The Built-in NLP integration with the Page inbox lets you create a Wit.ai app automatically and bootstrap it with past conversations from your Page directly from the Facebook app console settings. These samples that are compiled into your Wit.ai app are based on real conversations your Page has had with your users.
To try the Built-in NLP Page Inbox feature with your Messenger experience, do the following:
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.