HTTP API Reference

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
parameter possible values
encoding signed-integer, unsigned-integer, floating-point, mu-law, a-law, ima-adpcm, ms-adpcm or gsm-full-rate
bits 8, 16, or 32
rate an integer value like 8000 or 8k
endian big or little (usually little, cf. this Wikipedia article)

Example:
'content-type': 'audio/raw;encoding=unsigned-integer;bits=16;rate=8000;endian=big'

For now Wit.ai is only able to process mono so you must make sure to send mono and not stereo to the API.

Arguments

The request’s URL can contain the following optional fields:

name required type doc
context optional context object (JSON) Context (deprecated)
msg_id optional string A specific Id you want to assign to the message that will be processed. If not set, Wit.ai will auto generate one for you
thread_id optional string A specific Id that will let you group requests per conversation
n optional integer The number of n-best outcomes you want to get back. default is 1

Body

Put your binary data (file or stream) in the body.

Streaming audio

We accept chunked data, which is a good way to reduce latency. In addition to the Content-type header, you must set a Transfer-encoding header to chunked

Audio stream shouldn’t exceed 10s of audio time.

Response Format

Please refer to GET /message for information about the response format.

Error codes

http code reason
200 success, business as usual
400 missing body (code: body) or missing content-type (code: content-type) or unknown content-type (code: unknown-content-type) or speech recognition failed (code: speech-rec) or invalid parameters (code: invalid-params)
401 missing or wrong auth token (code: auth)
408 request timed out, client was to slow to send data (code: timeout)
500 something went wrong on our side, our experts are probably fixing it. (code: wit)
503 something is very wrong on our side, our experts are probably being yelled at

Notes

You can use SoX to record WAV files from the command line. The following options will create a Wit-ready WAV file (press Ctrl+C to stop recording):

  sox -d -b 16 -c 1 -r 16k sample.wav

Use the file command to check your file types.

  $ file sample.wav
  sample.wav: RIFF (little-endian) data, WAVE audio, Microsoft PCM, 16 bit, mono 16000 Hz

Definition

  POST https://api.wit.ai/speech

Example request

  $ curl -XPOST 'https://api.wit.ai/speech?v=20170307' \
   -i -L \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: audio/wav" \
   --data-binary "@sample.wav"

The response format is the same as in GET /message

Get your bot’s next step

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:
* msg means that you need to execute the send 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 send might alter the context: make sure to call /converse with the updated context!

Arguments

name required type doc
session_id required string Unique ID to group messages from the same user request/conversation. See below
q optional string A message from the user. Length must be > 0 and < 256. This should only be set at the first call until you get type=”stop”
context optional JSON The object representing the session state. You can pass the context either as a URL param or in the body of your POST.
reset optional boolean Whether to reset the last turn, i.e. all previous API calls up to the last user input included.

session_id

The session_id is a unique ID you generate on your side to group messages from the same user request/conversation.
When you start a new conversation, you should generate a new one. You should generate a new one, even when the user is the same.

reset

Sometimes, your bot might receive multiple messages before the first message is fully processed.
Less often, an API call might fail in the middle of the sequence of actions, due to transient network issues.
When this happens, you can start over the sequence of actions by setting this parameter to true.
Note: Your actions might get executed twice.

Response Format

name type doc
type string The type of the bot response. Either msg (the bot has something to send), action (the bot has something to do) or stop (the bot is waiting to proceed).
msg ?string The answer of your bot, when applicable.
quickreplies ?array The array of quick replies 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).

Definition

  POST https://api.wit.ai/converse

Example of Sequence of requests

1st request with a message

  $ curl -XPOST 'https://api.wit.ai/converse?v=20170307&session_id=123abc&q=weather%20in%20Brussels' \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H 'Authorization: Bearer $TOKEN'

Response:

  {
    "type": "action",
    "action": "merge",
    "entities": {"location": [{"body": "Brussels",
                               "value": {"type": "value",
                                         "value": "Brussels",
                                         "suggested": true},
                               "start": 11,
                               "end": 19,
                               "entity": "location"}]},
    "confidence": 1
  }

Follow-up request with a context in the body

$ curl -XPOST 'https://api.wit.ai/converse?v=20170307&session_id=123abc' \
      -d '{"loc":"Brussels"}' \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H 'Authorization: Bearer $TOKEN'

Response:

  {
    "type": "action",
    "action": "fetch-forecast",
    "confidence": 0.9963
  }

Follow-up request:

  $ curl -XPOST 'https://api.wit.ai/converse?v=20170307&session_id=123abc' \
      -d '{"loc":"Brussels","forecast":"sunny"}' \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H 'Authorization: Bearer $TOKEN'

Response:

  {
    "type": "msg",
    "msg": "It's gonna be sunny in Brussels.",
    "confidence": 0.9963
  }

Follow-up request:

  $ curl -XPOST 'https://api.wit.ai/converse?v=20170307&session_id=123abc' \
      -d '{"loc":"Brussels","forecast":"sunny"}' \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H 'Authorization: Bearer $TOKEN'

Response:

  {
    "type": "stop",
    "confidence": 0.9963
  }

Create a new entity

Creates a new entity with the given attributes.

Arguments

The request body must contain a JSON object with the given fields:

name required type doc
id required string ID or name of the requested entity
doc optional string Short sentence describing this entity
values optional array Possible values for this entity
lookups optional array Currently only supporting “trait” or “keywords” Search Strategy. If not provided, it will default to “keywords”.Traits are only available for new Bot Engine apps

Definition

  POST https://api.wit.ai/entities

Example request

  $ curl -XPOST 'https://api.wit.ai/entities?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"doc":"A city that I like",
       "id":"favorite_city",
       "values":[{"value":"Paris",
                  "expressions":["Paris",
                                 "City of Light",
                                 "Capital of France"]}]}'

Example response

  {
    "name" : "favorite_city",
    "lang" : "en",
    "lookups" : [ "keywords" ],
    "builtin" : false,
    "doc" : "A city that I like",
    "id" : "5418abc7-cc68-4073-ae9e-3a5c3c81d965"
  }

We don’t return the values anymore in the response. See GET /entities/:entity-id below.

Example “trait” request (for new Bot Engine apps)

  $ curl -XPOST 'https://api.wit.ai/entities?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"doc":"Detect the type of action",
       "lookups":["trait"],
       "id":"action_type",
       "values":[{"value":"booking",
                  "expressions":["I want to book at flight",
                                 "I need to buy a ticket",
                                 "need to book a cab"]}]}'

Example response

{
  "name" : "action_type",
  "builtin" : false,
  "doc" : "Detect the type of action",
  "id" : "573f78bc-c89c-4ea3-8a58-f26c8ad32483",
  "lang" : "en",
  "lookups" : [ "trait" ],
}

We don’t return the values anymore in the response. Check GET /entities/:entity-id to see the values.

Add new values to an entity

Add a possible value into the list of values for the entity.

Arguments

The request body must contain a JSON object with the given fields:

name required type doc
value required string Canonical value of the entity
expressions optional array of string Ways of expressing this canonical value
metadata optional string Metadata you want to attach to this value, will be sent back in runtime.

Definition

  POST https://api.wit.ai/entities/$ENTITY_ID/values

Example request

  $ curl -XPOST 'https://api.wit.ai/entities/favorite_city/values?v=20170307' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"value":"London",
       "expressions":["London"],
       "metadata":"CITY_1234"}'

Example response

{
  "builtin" : false,
  "doc" : "These are cities worth going to",
  "exotic" : false,
  "id" : "57475251-ba5a-412b-85ec-3ab6f778d6fa",
  "lang" : "en",
  "lookups" : [ "keywords" ],
  "name" : "favorite_city"
}

Example request for “trait” entity (only for new Bot Engine apps)

$ curl -XPOST 'https://api.wit.ai/entities/action_type/values?v=20170307' \
-H 'Authorization: Bearer $TOKEN' \
-H 'Content-Type: application/json' \
-d '{"value":"cancellation",
     "expressions":["can you help me cancel my reservation",
        "I want to cancel my taxi",
        "need to cancel my table"]}'

Example response

{
  "builtin" : false,
  "doc" : "Detect the type of action",
  "exotic" : false,
  "id" : "5747a309-ff28-4683-a8cf-fd5b9896a0a6",
  "lang" : "en",
  "lookups" : [ "trait" ],
  "name" : "action_type"
}

The response doesn’t return the updated values. Check GET /entities/:entity-id to see the values.

Create a new expression for an entity

Create a new expression of the canonical value of the entity. This API is limited to expressions shorter than 256 characters.

Arguments

The request body must be a JSON object with the given fields:

name required type doc
expression required string new expression for the canonical value of the entity. Must be shorter than 256 characters.

Definition

  POST https://api.wit.ai/entities/$ENTITY_ID/values/$ENTITY_VALUE/expressions

Example request

  $ curl -XPOST 'https://api.wit.ai/entities/favorite_city/values/Paris/expressions?v=20170307' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"expression":"Camembert city"}'

Example response

{
  "builtin" : false,
  "doc" : "These are cities worth going to",
  "exotic" : false,
  "id" : "57475251-ba5a-412b-85ec-3ab6f778d6fa",
  "lang" : "en",
  "lookups" : [ "keywords" ],
  "name" : "favorite_city"
}

Example request for a “trait” entity (only for new Bot Engine apps)

  $ curl -XPOST 'https://api.wit.ai/entities/action_type/values/cancellation/expressions?v=20170307' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"expression":"can you please cancel this reservation for me"}'

Example response

{
  "builtin" : false,
  "doc" : "Detect the type of action",
  "exotic" : false,
  "id" : "5747a309-ff28-4683-a8cf-fd5b9896a0a6",
  "lang" : "en",
  "lookups" : [ "trait" ],
  "name" : "action_type"
}

The response doesn’t return the updated value. Check GET /entities/:entity-id to see the expressions.

Train your app

Validate samples (sentence + entities annotations) to train your app programmatically.


Arguments

The request body contains a JSON array of Samples

Sample

name required type doc
text required string The text (sentence) you want your app to understand
entities required array The list of entities appearing in this sentence, that you want your app to extract once it is trained.

SampleEntity

name required type doc
entity required string The entity name. This can be the name of an entity you created, or a builtin entity. i.e food or wit$on_off.

Note
his entity must have been created previously. You can use POST /entities
value required string Canonical value of the entity or the text span
start optional integer If your entity appears in the text, the starting index within the text
end optional integer If your entity appears in the text, the ending index within the text

Definition

  POST https://api.wit.ai/samples

Example request

  $ curl -XPOST 'https://api.wit.ai/samples?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{
        "text": "I want to fly to sfo",
        "entities": [
          {
            "entity": "intent",
            "value": "flight_request"
          },
          {
            "entity": "wit$location",
            "start": 17,
            "end": 20,
            "value": "sfo"
          }
        ]
      }]'

Example response

{
  "sent" : true,
  "n" : 1
}

Create a new app

Creates a new app for an existing user.


Arguments

The request body contains a JSON object with the fields below

name required type doc
name required string Name of the new app
lang required string Language code (ISO alpha-2 code). Supported languages
private required string Private if “true”
desc optional string Short sentence describing your app

Definition

  POST https://api.wit.ai/apps

Example request

  $ curl -XPOST 'https://api.wit.ai/apps?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My_New_App",
       "lang":"en",
       "private":"false"}'

Example response

{
  "access_token" : "NEW_ACCESS_TOKEN",
  "app_id" : "NEW_APP_ID"
}

Create a new intent

DEPRECATED As of April 13th 2016, intents have changed, please refer to Categorize user intent to learn more.


Currently the API only accepts expressions without entities.

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

  GET https://api.wit.ai/intents

Example request

  $ curl -XPOST 'https://api.wit.ai/intents?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"flight_request",
       "doc":"detect flight request",
       "expressions":[{
          "body" : "fly from incheon to sfo"
        }, {
          "body" : "I want to fly from london to sfo"
        },{
          "body" : "need a flight from paris to tokyo"
        }]}'

Example response

{
  "intents" : [ {
    "id" : "8bbd17dc-b383-4f19-802e-dfc86d57cb23",
    "name" : "flight_request"
  }]
}

Example request with an array of intents

  $ curl -XPOST 'https://api.wit.ai/intents?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"name":"car_request",
       "doc":"detect car request",
       "expressions":[{
          "body" : "book a rental car in London"
        }, {
          "body" : "need to get a car in paris"
        }]},
        {"name":"uber_request",
       "doc":"detect uber request",
       "expressions":[{
          "body" : "find a uber in London"
        }]}]'

Example response with an array of intents

{
  "intents" : [ {
    "id" : "fbe55d5b-a98b-4b56-a39b-00040679511a",
    "name" : "car_request"
  }, {
    "id" : "a0b8621b-01a7-4ba1-b7d6-cc5032bf8e5b",
    "name" : "uber_request"
  } ]
}

Add new expressions to an intent

DEPRECATED As of April 13th 2016, intents have changed, please refer to Categorize user intent to learn more.


Add validated expressions to a given intent. Currently the API only accepts expressions without entities.

Arguments

The request body must be an array with the given object:

name required type doc
body required string Expression for this intent. Currently the API only accepts expressions without entities.

Definition

  POST https://api.wit.ai/intents/$INTENT_ID/expressions

Example request

  $ curl -XPOST 'https://api.wit.ai/intents/flight_request/expressions?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '[{
          "body" : "I\u0027d like to fly from NY to Chicago"
        },{
          "body" : "fly to LA from Miami"
        }]'

Example response

  [ {
    "intent_id" : "8bbd17dc-b383-4f19-802e-dfc86d57cb23",
    "body" : "I'd like to fly from NY to Chicago"
  }, {
    "intent_id" : "8bbd17dc-b383-4f19-802e-dfc86d57cb23",
    "body" : "fly to LA from Miami"
  } ]

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