Chatbox API

Overview
Integration
2.1 BOTID and TOKEN
2.2 Encoding
Chatbot API Requests and Responses
3.1 API Requests     1. HTTP Method
    2. URL
    3. Example
    4. Parameters
3.2 API Responses
    1. Response Format
    2. Example
    3. Response Content
    4. More Instructions

1. Overview

This documents describes how to integrate with chat service APIs.

2. Integration

2.1 BOTID and TOKEN##

BOTID is the bot's identification number.
TOKEN is the bot's credential to use RSVP.ai's services, do not share with others.

2.2 Encoding

URL uses UTF-8 encoding
Responses also uses UTF-8 encoding.

3. Chatbot API Requests and Responses

3.1 API Requests

HTTP Method:

GET

URL:

http://[host]:[port]/[endpoint]/chat

Example:

https://api.rsvp.ai/sandbox/chat?botid=999001&token=rsvpai&uid=123459&q=howdy

Parameters

Key	Type	Note	Default
Parameters
uid	String	[REQUIRED], user id, e.g.:123456, contains user and session information
q	String	[REQUIRED], question for the chatbot, e.g. "Hi"
token	String	[REQUIRED], credentials for using the service, do not share it with others.
lang	String	[OPTIONAL], language for the current bot/skill, suports "cn" (for Chinese) and "en" (for English)	en
botid	String	[OPTIONAL], ID of the bot.
skillid	String	[OPTIONAL], ID of the skill your want to use.
stage	String	[REQUIRED], in which stage (test/release) you want to use your bot	test

3.2 API Responses

Response Format：

Content-Type: application/json;charset=utf-8

Example（Paired-Corpus):

{
  "params":{
     "skillId":"1003064",
     "tid":"981b05d6-d0d4-4ce4-a007-1fee5c573290"
  },
  "stage": [{
    "message": "YOUR ANSWER"
    "props": {
      "faq_info": {
        "candidates": [{
          "score": 1,
          "gid": "144617",
          "groupBusinessId":"",
          "question": "YOUR QUESTION",
          "answer": "YOUR ANSWER",
          "skillname":"faq_business",
          "labels": ["1"]
        },
        {
          "score": 0.9668123,
          "gid": "144618",
          "question": "YOUR OTHER QUESTION",
          "answer": "YOUR OTHER ANSWER",
          "skillname":"faq_business",
          "labels": ["2"]
        }],
        "skillname":"faq_business",
        "gid": "144617",
        "groupBusinessId":"",
        "labels": ["1"]
      }
    },
  }],
  "status": 0,
  "topic": "faq"
}

Example（Dialog):

{
   "params":{
      "skillId":"1001815",
      "intentSlots":{
         "location":[
            {
               "slotType":"system_location",
               "value":[
                  [
                     "0",
                     "Beijing",
                     "Beijing",
                     "China",
                     "Asia"
                  ]
               ],
               "key":"Beijing"
            }
         ]
      },
      "intentName":"Weather Forecast",
      "nluSkillId":"402881436cdddd17016cdde307b105a9",
      "intentCandidates":[
         {
            "sentence":"Beijing's Good",
            "skillid":"402881436cdddd17016cdde307b105a9",
            "score":1.0,
            "skilllevel":"open_m",
            "originalSkillid":"1001815",
            "name":"Weather Forecast",
            "intentid":"402881436cdddd17016cdde307da05af",
            "fulfillment":false,
            "done":true,
            "slotProperties":{
               "location":[
                  {
                     "slotType":"system_location",
                     "value":[
                        [
                           "0",
                           "Beijing",
                           "Beijing",
                           "China",
                           "Asia"
                        ]
                     ],
                     "key":"Beijing"
                  }
               ]
            }
         }
         {
             [OTHER RESPONSES]
         }
      ],
      "tid":"4f9a2671-2de8-469d-a12f-86509ab5f9f5"
   },
   "stage":[
      {
         "message":"Beijing's Good"
      }
   ],
   "status":0,
   "topic":"nlu_skill"
}

Response Content：

Key	Type	Note
status	int	Response status.（0 for success, -1 for failure)
topic	String	Catagory of the result.
stage	JSONArray	A list of responses

Response Content:

DialogStage Objects

Name	Type	Note
message	String	Response message
url	String	URL for media streams
image	String	URL for images
props	Map	`[OPTIONAL]` Contains FaqInfo when topic is "faq"
action	String	Instruction for robot (that are in hardware forms)

FaqInfo Objects

Name	Type	Note
gid	String	Answer's group id
skillname	String	Name of the skill
candidates	JSONArray	Candiates of all possible other outcomes

Candidate Objects

Name	Type	Note
gid	String	Answer's group id
skillname	String	Name of the skill
score	Double	A score indicating how likely the response is correct
question	String	Question asked
answer	String	Returned answer

More Instructions ：

Stage contains one or mre DialogStage;
Stage's elements come in specific orders;
DialogStage must contain at least one of "URL" or "message";
If both "URL" and "message" exist in DialogStage, "message" will be neglected.
DialogStage's action field can be neglected in non-RSVP hardware.

Version History

Version Number	Date	Update
1.0	2019-12-12	Translated version.