Check the full documentation with tutorials and references on https://wit.ai/docs
More and more app users want to express their intent with natural language, instead of clicking buttons, filling forms, or having to follow complex steps. They would like to just say or type what they want the app to perform.
Wit enables developers to add a modern natural language interface to their app or device with minimal effort. Precisely, Wit turns sentences into structured information that the app can use.
Developers donât need to worry about Natural Language Processing algorithms, configuration data, performance and tuning. Wit encapsulates all this and lets you focus on the core features of your apps and devices.
Known use cases include:
SMS-based information or remote control services
IM-based information or remote control services
âQuick addâ features a la Google Calendar (replacing a form with free text input)
Natural Language querying a la Facebook Graph Search (turning a sentence into a database query)
Personal Assistants a la Appleâs Siri
App voice control with natural commands as opposed to strict-syntax commands (using Wit on top of Androidâs voice recognition for instance)
Robot dialog interfaces
There are two ways to interact with Wit:
A web console (https://console.wit.ai) where you (the developer) configure what you want Wit to do for you
An API (https://api.wit.ai) that your app will call to send natural language sentences (text) and get structured information (JSON) in return.
â curl \
> -H 'Authorization: Bearer B2QHJX7UFGF74O4MHX7UC54SSI4NLM5P' \
> 'https://api.wit.ai/message?q=i%20need%20a%20bud%20right%20now%21'
{
"msg_id": "d953bd6c-c620-4dae-a3fc-7634b4330073",
"msg_body": "i need a bud right now!",
"outcome": {
"intent": "grab_me_something",
"entities": {
"object_to_grab": {
"value": "beer",
"start": 9,
"end": 12,
"body": "bud"
}
},
"confidence": 0.6310633902098893
}
}
Witâs first goal is to determine the user intent. An intent is âsomething the user wants to doâ, like:
Ask about the weather at a certain place
Ask about the result of a sports game
Create a reminder in their agenda
Ask about their schedule for a certain day
Order their house to turn on the lights
Ask how many friends posted a status update the day before
Say hello
In the context of your app, youâll focus on a finite list of possible user intents. You define this list. Typically, each intent corresponds to one action in your app.
Each intent may be expressed in an infinite number of ways by the end-user (actually, even with thousands of occurrences, itâs very rare to observe the exact same sentence twice). We call them expressions.
For instance, the intent Set Alarm
may have the following expressions:
âWake me up at 5 tomorrowâ
âSet the alarm at 6amâ
âIâd like you to wake me up by midnightâ
Given a user expression, Wit tries to determine the user intent.
Teaching by example
Wit learns from examples. So for each intent, you must provide Wit with a few expressions. Based on this (and on all the things Wit already know in the background), Wit will be able to determine if a never-seen-before expression maps to the same intent.
Click on an intent in the Intents screen to see or add expressions.
Once you have defined a few intents (if you only set one intent, Wit will map all expressions to this intent, so you must set at least two intents if you want to try) and a few expressions for each intent, you can check if Wit already understands never seen before expressions.
Type a test sentence in the âTry out sentenceâŠâ field in the top banner, press Enter and see the result.
Did Wit find the right intent?
If it did, great! Reward it by clicking âValidateâ. Wit will remember this expression as another example for the intent, which will improve its accuracy.
If itâs wrong, no worry! Wit needs to learn a few more examples. Select the right intent in the dropdown and validate, Wit will remember that.
Protip â Actually, you can even create a new intent right from the dropdown. Just type the new intent name and press Enter.
Youâll also notice a (normally) green dot in the top banner.
The color code is:
Green: Wit is âcleanâ, indicating that all the examples you provided have been taken into account.
Orange: Wit is âdirtyâ. The latest examples you provided will be taken into account in a few minutes (click on the dot to see exactly when). Donât be mad at Wit if it does not understand something until then.
So far, weâve had simple intents. In the real world, most intents bear some kind of additional information. Examples:
Expression | Intent | Entities |
---|---|---|
âSet the temperature to 68°â | Set Thermostat | temperature = 68 |
âWake me up tomorrow at 5amâ | Set Alarm | datetime = 2013-07-04T050000Z |
In addition to determining the user intent, Wit tries to capture and normalize this additional information for you.
When you create an intent, you explicitely indicate which entities you want to capture. Letâs say we have a Set Alarm
intent for which we want to capture the date/time the user wants to set the alarm at.
Type a sentence like âI need to wake up at midnightâ in the âTry outâŠâ field in the top banner. Press Enter.
Make sure to select (or create) an intent in the Intent dropdown.
Using your mouse cursor, select âat midnightâ in the sentence (the span that corresponds to the value of the entity you want to capture). Youâll see the list of built-in entities that Wit knows how to capture.
Type âdateâ to filter the list and click on âwit/datetimeâ.
Youâll notice that Wit should have properly resolved the date/time interval corresponding to âat midnightâ
Click âValidateâ.
Youâve just instructed Wit to try to capture a wit/datetime
entity when it recognizes a Set Alarm
intent. Note that, at the same time, you also provided a new expression for this intent.
If you provide a few more expressions, and once Wit is trained, youâll notice that when you try out âwake up next Thursday at noonâ Wit should automatically capture the wit/datetime
entity with the right value.
Entities are always bound to an intent. That means that if Wit has detected a date, for instance, it wonât assign it to an entity unless the expression is mapped to an intent that bears a wit/datetime
entity.
Whenever possible, always use built-in entities (prefixed by wit/). These entities are trained on large datasets and should perform better than you own entities, which are trained just on the expressions you provide.
Choose your entities carefully (donât hesitate to ask us if you are not sure). Read the documentation string in the right column. Here are the most important built-in entities:
Wit recognizes and resolves many date and time expressions, like:
âtodayâ
âtomorrow at 8amâ
ânext Mondayâ
âin ten days in the afternoonâ
â4 minutes agoâ
Wit works with intervals:
â9amâ is resolved as âfrom 09:00:00 to 10:00:00â
â9:00amâ is resolved as âfrom 09:00:00 to 09:01:00â
Our motivation is that when the user says 9:00, they really mean that precision is important. This is not the same as 9am alone. We donât want to drop this information.
If you donât agree with Witâs interpretation of the value of your datetime, you can change the value in the form and validate. As of this alpha version, Wit wonât use this information during automatic training. But weâll look at it manually and improve it. In a later version, this information will feed the training.
If some dates seem to be off by one day, please read the section about time zones and local dates.
Use this entity to capture a number or a quantity in an expression.
Example:
Currently, only integers are recognized. Decimal numbers are not recognized.
Use these entities to capture a raw string of characters from within an expression. Thatâs useful when you want to capture a message the user wants to write, a phrase they want to translate, an agenda entry text, etc.
Examples:
âTranslate I love you into Chineseâ => wit/phrase_to_translate = âI love youâ
âRemind me to buy the milk tomorrow at 8amâ => wit/reminder = âbuy the milkâ
Protip â These âfree textâ entities needs more examples than other entities to be trained properly, because there is not simple intrinsic patterns, like for dates or numbers, helping Wit to recognize the entity. Wit has to rely mostly on context (words and features before and after the span) in order to recognize these entities.
Examples:
We are currently working on the location type. Wit will not only recognize locations in your sentences, but also resolve them to precise geographical data you can leverage. If you plan to use Wit for a location-centric service, we would be glad to hear from you to better serve your requirements. Please get in touch with us!
In addition to the built-in entities, you can create your own entities. As of this alpha version, this is limited to enum-based entities.
Examples:
âpaint the cube in greenâ => color = âgreenâ
âdid the giants win?â => MLB_team = "SF Giantsâ
An enum-based entity is composed of values. For instance, the values of the MLB_teams
entity are the teams: SF Giants
, NY Mets
, etc.
The value SF Giants
corresponds to one or several expressions, which are different synonymical ways to refer to the value: âGiantsâ, âSF Giantsâ, âSan Francisco Giantsâ, etc.
When an enum-based entity is captured, its value is always one of the values, as opposed to an expression:
âdid the San Francisco Giants win?â => MLB_team = âSF Giantsâ
âdid the giants win?â => MLB_team = âSF Giantsâ
Letâs say you want to create a âGrab me somethingâ intent for your robot to bring you beer. For that, youâll need an enum-based entity corresponding to the list of things your robot can grab.
Type a first expression like âgrab me a beerâ in the try out field. Since your robot (and Wit) knows nothing about this intent yet, it thinks itâs a âSet Alarmâ intent (notice the info message though).
Letâs create our intent: type âGrab me somethingâ and press Enter in the intent dropdown.
Now we need to tell Wit about the entity. Select âbeerâ in the expression.
There is no built-in entity for object_to_grab
, so letâs just type this and press Enter.
It looks good! Click Validate. Your object_to_grab
entity has been created, and it has one value, beer
, with one expression, âbeerâ.
Letâs wait a minute until our instance gets trained. Once the status light is green again, type âgrab me a budâ in the try out field. Youâll realize that the Grab me something
intent has been recognized, but not the object_to_grab
entity. Because Wit doesnât know (yet) that bud is a beer (well, there could be a debate about that âfactâ, but thatâs out of the scope of this introduction).
Select the span âbudâ in the expression, and then object_to_grab
as the entity.
Now you have bud
as the value. If you want your robot to set just one canonical value beer
for all beers, select beer
in the dropdown. It means that a new expression âbudâ will be mapped to our existing value beer
.
Even if enum-based entities are based on a list of values, Wit can make some guesses and find ânewâ values. For instance, if you have a Set TV channel
intent that rely on a TV_channel
entity, you might have trained Wit with a few dozens well-known TV channel names like âCNNâ, âPBSâ, etc. But one day, a user says âI want to watch KXXXâ, and âKXXXâ is not in your list. If Wit has been trained with enough expressions, it should be able to guess that âKXXXâ is probably a TV channel. The API response will contain the right entity:
{
...
"entities": {
"TV_channel": {
"value": "KXXX",
"body": "KXXX",
"suggested": true
}
}
}
Please note the suggested: true
part. It means that Wit did not find âKXXXâ in its list of TV channels, but guessed it was probably one anyway. Whether you accept or not this suggestion, itâs your decision. For instance, you could ask the user to confirm their intent in this case.
Finally, if you find the expression âI want to watch KXXXâ in your Inbox and validate it, âKXXXâ will be added to the TV_channel
list. So next time, it wonât be âsuggestedâ, and Wit will be a little bit smarter.
We are currently working on developer-defined non-enum-based entities. Unlike enum-based entities, youâll be able to customize Witâs both recognition and resolution strategies for your entities.
If you need special entities right now, please get in touch with us.
Now that youâve trained your Wit instance, itâs time to integrate it into your app, get your feet wet and see how it behaves in the real world.
Check out the full API reference.
For now, if you just want to see the API in action:
Click on Settings in the nav bar on the left
Type a sentence and copy the curl command to your terminal
â curl \
> -H 'Authorization: Bearer B2QHJX7UFGF74O4MHX7UC54SSI4NLM5P' \
> 'https://api.wit.ai/message?q=i%20need%20a%20bud%20right%20now%21'
{
"msg_id": "d953bd6c-c620-4dae-a3fc-7634b4330073",
"msg_body": "i need a bud right now!",
"outcome": {
"intent": "grab_me_something",
"entities": {
"object_to_grab": {
"value": "beer",
"start": 9,
"end": 12,
"body": "bud"
}
},
"confidence": 0.6310633902098893
}
}
Wit works bottom-up. Let your end-users express their intents freely, and have your app learn from that and adapt. Not the other way around.
Here comes Witâs Inbox.
Each time Wit receives an API call and processes a sentence, it adds it in your inbox. You can read each item there as âHey, dear developer, I received this sentence and answered with this intent and these entities, was it right?â. As a developer and (in this context) educator, your job is to either reward (click Validate) or correct (edit the outcome, and Validate). Either way, Wit learns from your action.
Protip â If your inbox is empty and you want to see what it looks like, make a curl call to the API
This is the preferred way to improve your Wit configuration. Try to keep an empty Wit inbox. Actually you can even create intents and entities straight from your Inbox.
Sometimes, you may get irrelevant sentences in your inbox. Just click âDismissâ to make them disappear.
When Wit resolves certain wit/datetime
entities, it needs a local time. For instance at midnight UTC, âtodayâ wonât be resolved in the same way for a user based in UTC-01 and another based in UTC+01.
By default, Wit uses the time zone defined in your instance settings (click Settings in the nav bar in Wit console). If an API call comes without any additional information about time zone or local time, a local time is inferred from this default time zone (and the UTC time given by our server).
If you want to provide Wit with a specific time zone or local time for a given API call, use the context
field. Check out the full reference in the API documentation.