GetNumber

Get a spoken numeric response from the user. Will play an optional prompt from a sound file and then interpret the natural language response from the user as a numeric value.

Accepts non-negative integers or sequences of digits, eg. “forty four” and “four four” will both be parsed as “44”.

Properties

Property	Type	Description
Required Properties
on_done	string	Callback URL to be sent an HTTP POST request when finished. See Get number callback for details.
Optional Properties
timeout_seconds	integer	Time, in seconds, to wait for the user to say a number. When the timeout expires, will send an empty string to the on_done callback and move on to the next command in the routine.
prompt_url	string	URL of the .wav or .mp3 file to play at the start of the command. Normally used to communicate instructions to the end user.

Example

{
    "name": "GetNumber",
    "on_done": "http://myserver.com/gotnumber",
    "timeout_seconds": 15,
    "prompt_url": "http://myserver.com/how_many.wav"
}

Get number callback

HTTP request sent when a GetNumber command finishes.

Request

method:POST content-type:application/json

The request body contains a JSON object with the following properties:

Property	Type	Description
account_id	string	The ID of your Sift API account.
connection_id	string	ID of the Connection that handled the command.
value	string	The numeric response that was spoken by the end user as a string of digits, or null if no valid response was detected.
Optional Properties
error	string	Either “timeout” or “invalid”. Only present if value is null.

Note

The value property is provided as a string instead of an integer to allow the user to say sequences of digits as well as natural numbers. This allows results like “0000”, when the user said “zero zero zero zero”, which cannot be accurately represented as an integer. You may wish to use your language’s string to integer function if you are only expecting numbers.

Warning

English can be ambigious when describing sequences of large numbers. For instance, if a user says “two thousand five hundred”, this could be interpreted as a single number (2500) or two numbers (2000 and 500). The GetNumber command will interpret phrases as a single number whenever it makes sense to do so. In the above example, the result field would contain the string “2500”. To avoid ambiguous responses, never ask the end user for multiple numbers larger than 100 in a single prompt.

Example

{
    "account_id": "372718353dcf4d16",
    "connection_id": "6f5704748865267a",
    "value": "128"
}

Response

content-type:application/json

The response body may optionally contain a JSON object with the following properties.

Property	Type	Description
Optional Properties
routine	list	A new routine list to run on the connection referenced by the connection_id property of the request.