Chat API

Updated 5 months ago by Matthew Clementson

Request

URL Parameters:

ParameterPositionTypeDescription
{botId}PathUUIDThe bot id.
qQueryStringThe question to send to the bot.
chatIdQueryUUIDThe id of the chat session. The first request should send this parameter empty, and the response will return a newly generated id, which should then be included with all subsequent requests

Optional Headers:

Any unique headers starting with X-Hutoma-Var- will be used to build a dictionary of client variables that can be passed along to web hooks.

Any variable names should be in ASCII character range, and all values should be URL encoded. For example:

X-Hutoma-Var-Timezone PST%2C%20%2D8
          
          X-Hutoma-Var-Country  USA
          
          

Any duplicate headers are discarded.

X-Hutoma-Var-Duplicate value 1
          
          X-Hutoma-Var-Duplicate value 2

Response

  • Success
    • HTTP Result Code: 200 - OK
      Content:
{
              "chatId": string,           // chat session id 
              "timestamp": number,        // unix timestamp
          
              // Chat Result object
              "result": {
                  "query": string,        // question asked
                  "answer": string,       // answer to the question
                  "score": number,        // response score (between 0.0 and 1.0).
                  "elapsedTime": number   // request completion time (in seconds)
              },
          
              // API Response Status object
              "status": {
                  "code": number,         // HTTP code
                  "info": string          // Textual information
              }
          }

Note:
A higher score indicates better quality answer, however this there are several things to consider about this score:
1/ It does not use a linear scale, so: a score of 0.4 is not twice "as good" as 0.2.

2/ It does not indicate a statistic likelihood that the answer is perceived as being correct by the chatting user, so: 0.3 does not indicate 30% confidence in the result.

3/ This number is subject to change as we improve the platform.
CodeErrorDescription

404Not FoundRequest for a non-existing bot id

400Bad RequestThis bot is not ready to chat. It needs to train and/or be linked to other bots.

500Internal Server ErrorSomething unexpected has happened.


Content

{
              // API Response Status object
              "status": {
                  "code": number,     // HTTP code
                  "info": string      // Textual information
              }
          }
          


Sample: 

{
              // API Response Status object
              "status": {
                  "code": number,     // HTTP code
                  "info": string      // Textual information
              }
          }
          

Response

{
               "chatId": "003a6ae6-b9fa-4bc9-952a-d37971036722",
               "timestamp": 1497029246768,
               "result": {
                   "score": 0.3,
                   "query": "Hello",
                   "answer": "Hello, how are you?",
                   "history": "Hello, how are you?",
                   "elapsedTime": 0.262
               },
               "status": {
                   "code": 200,
                   "info": "OK"
               }
          }

    How did we do?