Chatbot RestAPI Integration

Most Chatbots will require external integration to get or change information and perform actions. The Sedro Project provides 2 methods for external integration 1) Form based explicit REST API interactions 2) Action handler Forms (covered in a future blog).

In this Blog post we will cover how to integrate API calls to perform actions and provide you with a live example.

Adding a RestAPI Post to a Form

An http POST can be added as an input inline in any form. Common case would be to retrieve a users account information or retrieve records from an external Database. The format is

 <input name="get_account" type="post" data-resp-formname="account" data-posturl="http://api.sedro.xyz/api/1.0/test/testformgetpost"/>

The form will be POSTed to the URL that is defined when the form reaches this input line. A request with parameters will be sent to the server in JSON and a JSON request in a standard format will be expected in response.

Request Params

The standard params for every post include some high level information that will allow external servers to link the correct user and context when it is needed.

  • ctok – caller token passed into the wake
  • chid – channel id
  • chtype – channel type
  • type – ‘input’ in all posts
  • lang – the language of the chatbot

The input parameters will be all the inputs in the current form, or you can specify a different form to define those parameters if needed. with the following attribute in the definition.

data-req-formname=request_form

Response Params

data-resp-formname=account

Specify the name of the form that defines the data to retrieve from the post. This form will need to be defined with the correct information, see Object as Form section below.

For a well organized set of forms, having a single form to format output is helpful, it can be reused in any case that needs to display the information. Also using %iterator:xxx% notation allows labels to show single or a member of a set.

JSON Request Format

The form of the request is standard aside from the params listed, which come from the form.

The request elements are the params passed in they are taken from the request form defined for the post. The form under lists the forms elements that are being requested to be filled in and returned, these come from the response form defined for the post

 {
 "ctok": "TEST_TOKEN_SEDRO"
 "chid": "40caee93-66a4-44e7-b466-dd38494e30a3",
 "chtype": "chat",
 "persona": "jane",
 "type": "input",
 "lang": "english",
 "request": {
    "elements": [
       {
          "val": "849392",
          "name": "account number"
       }
    ],
    "name": "_getexternaccount_"
    },
    "form": {
       "elements": [
          {
              "name": "full name",
              "type": "input"
           },
           {
              "name": "address",
              "type": "input"
           },
           {
              "name": "home phone number",
              "type": "input"
           },
           {
              "name": "account number",
              "type": "input"
           }
       ],
       "name": "account",
       "id": 23
    }
 } 

JSON Response Format

The response format is mostly the same as the request, but with the values added for each param.

 {
 "chtype": "chat",
 "request": {
    "elements": [
        {
           "val": "849392",
           "name": "account number"
        }
    ],
    "name": "_getexternaccount_"
 },
 "form": {
    "elements": [
       {
            "val": "Bart Simpson",
            "name": "full name"
        },
        {
            "val": "123 N. Alphabet St., Los Angeles, Ca 97045",
            "name": "address"
        },
        {
            "val": "(555) 345-6789",
            "name": "home phone"
        },
        {
            "val": "849392",
           "name": "account number"
        }
    ],
    "name": "account",
    "id": 23
 },
 "type": "data",
 "chid": "3c5f5025-e560-42b7-b172-68456dcb8768"
 } 

Multiple form response for a list can include information for pagination as well.

{
 "chtype": "chat",
 "request": {
    "elements": [
        {
           "val": "849392",
           "name": "account number"
        }
    ],
    "name": "_getexternaccount_"
 },
 "forms": [
{
    "elements": [
       {
            "val": "Bart Simpson",
            "name": "full name"
        },
        {
            "val": "123 N. Alphabet St., Los Angeles, Ca 97045",
            "name": "address"
        },
        {
            "val": "(555) 345-6789",
            "name": "home phone"
        },
        {
            "val": "849392",
           "name": "account number"
        }
    ],
    "name": "account",
    "id": 1
 },
{
    "elements": [
       {
            "val": "Hommer Simpson",
            "name": "full name"
        },
        {
            "val": "123 N. Alphabet St., Los Angeles, Ca 97045",
            "name": "address"
        },
        {
            "val": "(555) 345-6789",
            "name": "home phone"
        },
        {
            "val": "849391",
           "name": "account number"
        }
    ],
    "name": "account",
    "id": 2
 }
],
 "type": "data",
 "count": "2",
 "start": "1",
 "end": "2",
 "chid": "3c5f5025-e560-42b7-b172-68456dcb8768"
 } 

Server Response

The server called in the post must respond with the JSON format expected, the data in the response should be in the format of the ‘form’ passed in. Each value should be set as expected. If more that one form are filled out by the server a list of forms should be returned in the response.

Objects as Forms

For integration, managing API params, retrieved data and saved data a form may be created to represent an Object. It simply has a set of inputs with names to represent the params or fields of data.

 <form name='account' data-type='dataform' data-link='caller=possesses'>
 <input name="full name" data-type="input" data-alias='full name, account holder, account holder name'/>
 <input name="address" data-type="input" data-alias='home address, address, mailing address'/>
 <input name="home phone" data-type="input" data-alias='home phone number, home phone, phone number'/>
 <input name="account number" data-type="input" data-alias='acctnum' data-fmt='^[0-9]{6}$'/>
 </form> 

This form can then be used to as the Request Param and Response Param Form. This would get back a completed form with all the values filed in, which could be saved and referenced.

The name of each input is important, it must be in english and specify what the datum is, as this is interpreted by Sedro NLU so that it can learn the information, the alias= allows for additional names that this datum may be called to be added for better learning. For instance in the above example name=address and data-alias=home address, mailing address, this allows the Persona to know that this is the callers address, home address, and mailing address.

Attribute data-fmt is optional, on an input it is used to validate the value is ok, it is in standard regx. If there is a specific format to the datum, it is recommended that you add it.

Typing Message

While waiting for the post response a message may be sent to the caller, a typing message is most useful. Adding a wake message to the post will have it sent to the caller before the post. setting data-msg-event=’typing‘ will send a typing message, also add a pre-wait to ensure it is show.

<label for="get_account" state='wake' data-msg-event='typing' data-pre-wait='5'>Getting Account...</label>

Full Example

This example gets an account number from the caller, then gets the callers account information from the external server and allows the caller to view it.

 <form name='_getexternaccount_' data-type='form'>
 <input name="account number" data-type="input" data-seq="X:%any%:(lx_number):sz[large]" data-fmt='^[0-9]{6}$'/>
 <label for="account number" state='wake'>What is your account number?</label>
 <label for="account number" state='incomplete'>Account number is 6 digits</label>
 <label for="account number" state='verify'>Is %account number% correct?</label>
 <label for="account number" state='complete'>Retrieving account information...</label>
  
   <input name="get_account" data-type="post" data-resp-formname="account" data-posturl="http://api.sedro.xyz/api/1.0/test/testformgetpost"/>
<label for="get_account" state='wake' data-msg-event='typing' data-pre-wait='5'>Adding Account...</label>
 <label for="get_account" state='incomplete'>Still waiting for account information</label>
 
 <input name="account holder" data-type="content" />
 <label for="account holder" state='wake'>Account Holder: %current:account/full name%</label> 
 
 <input name="account addr" data-type="content" />
 <label for="account addr" state='wake'>Address: %current:account/address%</label> 
 
 <input name="account phone" data-type="content" />
 <label for="account phone" state='wake'>Phone: %current:account/home phone%</label> 
 </form> 

The information is also learned by the Persona, allowing it to answer many questions about the information on its own.

The Other Method

In the next blog post we will cover a bit about the command and action forms and integration. These perform operations similar to what other services do with intent.

To Be Continued…

In the next blog on Forms we will focus on Action forms

One Reply to “Chatbot RestAPI Integration”

Comments are closed.