Example request

where $TOKEN is your app token, which can be found under Settings in the Wit console.

Versioning

Every request requires a version parameter either in the URL or in the headers.

This parameter is a date that represents the “version” of the Wit API. We’ll try to minimize backwards-incompatible changes we make to the API, but when we do make these changes, this parameter will allow you to continue to use the API as before and give you time to transition to the new implementation if you want.

As of June 1st, 2014, requests that do not include a version parameter will be rejected.
Inspired by Foursquare API versioning

This request gives you the guarantee that any changes that may have occurred after April 1st, 2014 won’t impact you. Although both requests are equivalent, passing the version parameter in the URL is the preferred method.

Cross-domain requests

It is possible to use Wit from your website.

If you need to use other parts of the API, the browser won’t let you contact Wit from your domain. To work-around this, the only solution for the moment is to use JSONP as shown in the example on the right.

Using JSONP with jQuery

$.ajax({url:'https://api.wit.ai/message',data:{'q':'set an alarm in 10min','access_token':'MY_WIT_TOKEN'},dataType:'jsonp',method:'GET',success:function(response){console.log("success!",response);}});

Context object

Context is key in natural language. For instance, at the same absolute instant, “today” will be resolved to a different value depending on the timezone of the user.

The optional URL-encoded field context captures contextual and state information.

Name

Value

stateoptional

State name or array of state names. If provided, intents that were defined for this or these state(s) will be matched with high priority. That’s useful to create stateful dialogs, for instance to match “yes” or “no” after you asked a question to the end-user.Example: "yes_or_no" or ["yes_or_no", "cancel"]

reference_timeoptional

Local date and time of the user, ISO8601 format. Make sure you don’t send a UTC time, which would defeat the goal of this field. Example: "2014-10-30T12:18:45-07:00"

timezoneoptional

Local timezone of the user. Must be a canonical ID. timezone is used only if you don’t provide a reference_time. In this case, we will calculate reference_time from timezone and the UTC time of the API server. If neither reference_time or timezone are provided (or a fortiori if no context at all is provided), we’ll use the default timezone of your app, which you can set in Settings in the web console. Example: "America/Los_Angeles"

entitiesoptional

List of entities that need to be augmented for this request. This object should respect the format defined in Entities Post. For instance if you need to add dynamically the list of rooms for a specific user.

locationoptional

GPS location in order to have a more accurate result for entities like Location. Example: {"latitude":37.42, "longitude":-122.15}

Example request with single outcome

Example response

{"msg_id":"387b8515-0c1d-42a9-aa80-e68b66b66c27","_text":"how many people between Tuesday and Friday","outcomes":[{"_text":"how many people between Tuesday and Friday","intent":"query_metrics","entities":{"metric":[{"metadata":"{'code' : 324}","value":"metric_visitor"}],"datetime":[{"value":{"from":"2014-07-01T00:00:00.000-07:00","to":"2014-07-02T00:00:00.000-07:00"}},{"value":{"from":"2014-07-04T00:00:00.000-07:00","to":"2014-07-05T00:00:00.000-07:00"}}]},"confidence":0.621}]}

Example request to get the best three outcomes

Example response

{"msg_id":"646d94fb-fe61-4304-a5ba-168cb2e17169","_text":"how many people between Tuesday and Friday","outcomes":[{"_text":"how many people between Tuesday and Friday","intent":"query_metrics","entities":{"metric":[{"metadata":"{'code' : 324}","value":"metric_visitor"}],"datetime":[{"value":{"from":"2014-07-01T00:00:00.000-07:00","to":"2014-07-02T00:00:00.000-07:00"}},{"value":{"from":"2014-07-04T00:00:00.000-07:00","to":"2014-07-05T00:00:00.000-07:00"}}]},"confidence":0.621},{"_text":"how many people between Tuesday and Friday","intent":"grab_me_something","entities":{},"confidence":0.001},{"_text":"how many people between Tuesday and Friday","intent":"play","entities":{"artist":[{"suggested":true,"value":"Friday"}]},"confidence":0.001}]}

Retrieve the meaning of an audio wave

Returns the meaning extracted from an audio file or stream. We do recommend you to stream the audio input as it will reduce the latency, hence improve the user experience.

Headers

In addition to the authorization header, you must set a Content-type header to:

audio/wav if you are sending a WAV file. We support RIFF WAVE (linear, little-endian).

audio/mpeg3 for mp3 file or stream

audio/ulaw for G.711 u-law file or stream. Sampling rate must be 8khz

audio/raw. For this content-type, the following parameters are mandatory

Create a new intent

Arguments

The request body can contain
- a JSON object with the fields below
- an array of JSON objects with the fields below

name

required

type

doc

name

required

string

Name of the new intent

doc

optional

string

Short sentence describing this intent

metadata

optional

string

String containing additional info for this intent

expressions

optional

array

Possible expressions for this intent. Currently the API only accepts expressions without entities.

meta

optional

json

Need a “states” field that contains an array of states associated with this intent (see notes below)

Notes

To add states to your intent, use the field meta. If any, the intent won’t be activated for stateless queries. See more.
For example:

{"name":"email_answer","doc":"to detect the preference between email or sms","metadata":"answer_id=1122","meta":{"states":["email_or_text","another_state"]},"expressions":[{"body":"email"},{"body":"text"},{"body":"sms"}]}

Definition

Example requests

Example response

{"expressions":[{"body":"need a flight from paris to tokyo","id":"54e66797-4c28-40d3-a7f6-4d6c7828bf31"},{"body":"I want to fly from london to sfo","id":"54e66797-b7ff-4029-9b81-82bc266953b8"},{"body":"fly from incheon to sfo","id":"54e66797-e575-49a9-bd21-30a0ee59643f"}],"entities":[],"id":"8bbd17dc-b383-4f19-802e-dfc86d57cb23","name":"flight_request","doc":"detect flight request"}

Example response with entities

{"expressions":[{"entities":[{"wisp":"535a80ff-6399-4653-8b2a-c770dd014965","value":"sfo","start":9,"end":12}],"body":"hotel in sfo","id":"54e66865-1509-4e65-b257-5f573945f1bc"},{"entities":[{"wisp":"535a80ff-6399-4653-8b2a-c770dd014965","value":"paris","start":25,"end":30}],"body":"I want to book a room in paris","id":"54e66866-6516-42c7-99aa-12affe5064d9"}],"id":"19586508-bd73-42a3-a804-682fc542e7af","name":"hotel_request","doc":"detect hotel request","metadata":"some metadata"}

The $INTENT_ID parameter can be either the intent id or the intent name.

Update intent attributes

Update the intent attributes but not its expressions. If you need to add or remove expressions, use Create/Destroy Intent Expression

Example response

{"lang":"en","closed":false,"exotic":false,"values":[{"expressions":["Paris"],"value":"Paris"}],"builtin":false,"doc":"A city that I like","name":"favorite_city","id":"5418abc7-cc68-4073-ae9e-3a5c3c81d965"}

Example response

{"lang":"en","closed":false,"exotic":false,"values":[{"expressions":["Paris"],"value":"Paris"}],"builtin":false,"doc":"A city that I like","name":"favorite_city","id":"5418abc7-cc68-4073-ae9e-3a5c3c81d965"}

Example response

{"lang":"en","closed":false,"exotic":false,"values":[{"expressions":["City of Light","Paris","Capital of France"],"metadata":"CITY_1234","value":"Paris"}],"builtin":false,"doc":"A city that I like","name":"favorite_city","id":"5418abc7-cc68-4073-ae9e-3a5c3c81d965"}

Definition

Example request

Example response

{"msg_id":"387b8515-0c1d-42a9-aa80-e68b66b66c27","_text":"how many people between Tuesday and Friday","outcomes":[{"_text":"how many people between Tuesday and Friday","intent":"query_metrics","intent_id":"bc178849-0527-4a31-a0b0-fe84f8f8b9e4","entities":{"metric":[{"metadata":"{'code' : 324}","end":15,"start":9,"value":"metric_visitor","body":"people"}],"datetime":[{"end":31,"start":24,"value":{"from":"2014-07-01T00:00:00.000-07:00","to":"2014-07-02T00:00:00.000-07:00"},"body":"Tuesday"},{"end":42,"start":36,"value":{"from":"2014-07-04T00:00:00.000-07:00","to":"2014-07-05T00:00:00.000-07:00"},"body":"Friday"}]},"confidence":0.621}]}

Get your bot’s next step

DEPRECATED As of July 27th 2017, Wit no longer supports this end point. To migrate, please refer to our blog post

Returns what your bot should do next. The next step can be either answering to the user, performing an action, or waiting for further requests.

To retrieve the whole sequence of actions, you need to successively call /converse until the type is stop. See example on the right.
In the initial call, you would set q to the user message. In the following calls, you should leave it null (don’t set it).
The type field in the response defines what you need to do:
* merge means that you need to execute the merge action;
* msg means that you need to execute the say action;
* action means that you need to execute the action whose name is specified in the action field;
* stop means that the bot is done: there is nothing left to do until the next user message.
All actions but say might alter the context: make sure to call /converse with the updated context!

Arguments

name

required

type

doc

session_id

required

string

A specific ID of your choosing representing the session your query belongs to

q

optional

string

A message from the user. This should only be set at the first step

context

optional

JSON

The object representing the session state

Response Format

name

type

doc

type

string

The type of the bot response. Either merge (first bot action after a user message), msg (the bot has something to say), action (the bot has something to do) or stop (the bot is waiting to proceed).

msg

?string

The answer of your bot, when applicable.

action

?string

The action to execute, when applicable.

entities

?object

Object of entities, when applicable. Each entity is an array of values (even when there is only one value).

confidence

number

Represents the confidence level of the next step, between 0 (low) and 1 (high).