Chatbot API Common Use Cases

Owned by Akshay Viswanathan (Deactivated)
Last updated: Aug 05, 2020 by Nicolò Vendramin (Deactivated)
6 min read

The documentation for the endpoint can be found in redoc and swagger format.

In the swagger page it's possible to test all the endpoints after authorising with a correct set of username, password, client id and client password. 

For additional info contact us via email.

Instantiate and Interact with an Existing Bot

Instantiation of a Deployed Bot (snippet)

Instantiation of a Trained Bot (test session)

  • Identify the id of the chatbot and nlu to use in the test session
    GET /chatbot/object/ 
    will retrieve the list of all chatbots available to the user performing the request.
    The desired chatbot can be identified through its name (property 'content'). The id of the nlu
    to be used can be found in the 'nlu_instance' property of the chosen chatbot.
    The id of the chatbot can be found in the 'id' property.
  • Launch a training session
    GET /chatbot/instance/train/
    starts a new chat room and initialises the corresponding chatbot. Requires the
    properties 'chatbot', and 'nlu_instance' collected at the previous step.
    The chatbot will post a message in the room when the conversation is ready to 
    start. It returns the id of the room to post and poll messages.

Chat Interaction

  • Send a message
    POST /snippet/chat/  (POST /chatbot/message/ for test sessions)
    https://production.apis.dialoguesuite.com/api/v2/redoc/#operation/chat_snippet
    Sends a message to the chatbot. Messages need to be posted at the room id
    obtained here.
    Every room can be entered by 1) the chatbot, 2) the user, and 3) a customer support agents.
    The parameter 'destination' specifies the visibility of the message and can have the
    values: ['ALL', 'ADMIN', 'USER', 'CHATBOT'].
  • Poll messages for a room
    POST /snippet/read/  (GET /chatbot/instance/<id> for test sessions)
    https://production.apis.dialoguesuite.com/api/v2/redoc/#operation/read_snippet
    Polls the complete conversation history. Messages have integer IDs assigned in 
    ascending order to make it easy to identify seen and unseen messages.
    The room id is the one obtained here.


Accounts

Login 

  • Login functionaility (requirement 1)
    POST /oauth/token/
    Set grant_type to "password" in the payload together with 
    username and password set to the correct value. The post
    request should have basic authentication using the OAuth 
    app credentials (client_id and client_secret please contact us for these).
    This endpoint follows the standard Oauth2 password grant
    flow as described here.

User Management

(requirement 5) (requires CHATBOT ADMIN clearance)

  • Get employees
    GET /accounts/employee/
  • Create a new employee
    POST /accounts/employee/
    If the username exists already the creation will return an error code
  • Get user information after login (e.g.: for checking user's permissions)
    GET /accounts/user/{username}/
    The clearance levels assigned to the user will be found inside the 
    object employee_to_clearance_mappings in the employee object found
    in the response
  • Manage permissions (clearance)
    • Get available clearance levels
      GET /accounts/clearance/level/
    • Assign a certain clearance level to an employee
      POST /accounts/clearance/mapping/
    • Revoke a specific permission
      DELETE /accounts/clearance/mapping/{id}/


Chatbot Construction (w.i.p.)

Creation

  • Creation of a Bot (requirement 6)
    The creation of a chatbot object
    POST /chatbot/topic/ *
    Creation from Existing Bot (requirement 7)
    POST /chatbot/topic/ *
    this time passing the seed input as the ID of the chatbot-topic to duplicate
  • Creation of a cross-language chatbot (requirement 27)
    POST /chatbot/topic/
    This time passing the topic input as the ID of the topic for the chatbot-topic 
    to use as shared model

Skill Setup

  • Skill Configuration (requirement 8)
    • Configuration of a functionality of a chatbot. 
      CRUD for skills
      POST /core/skill/
      • Setup of skill triggers (requirement 9)
        • Get available types of trigger
          GET /core/trigger/type
        • Create an intent-based skill trigger
          • Edit Trigger Data Items (requirement 43)
            CRUD for intent types
            POST /annotation/intent-type/
            CRUD for intents (trigger examples) 
            POST /annotation/intent/  
          • Create intent trigger
            POST /core/trigger/intent/
      • Configure skill flow (requirement 20)
        • Get available block types
          GET /core/block/type/
        • Create blocks for a skill 
          • Create an api block 
            POST /core/block/api/
          • Create a variable collection block
            POST /core/block/collected-variable/
          • Create a simple output block
            POST /core/block/string/
        • Assign the starting block to the skill
          POST /core/skill-starting-block-mapping/
        • Configure in-skill flow
          • Get scheduling rule types
            GET /core/scheduling-rule/type/ 
          • build simple scheduling rule
            POST /core/scheduling-rule/simple/
          • build conditional scheduling rule (requirement 50)
            • create a conditional scheduling rule
              POST /core/scheduling-rule/conditional/
            • add triggering conditions
              • Get condition types
                GET /core/scheduling-rule/condition/type/
              • Build a equal condition
                POST /core/scheduling-rule/condition/equals/
              • Build a string similarity condition
                POST /core/scheduling-rule/condition/string-similarity/ 
      • Add follow ups 
        • Get follow up types
          GET /core/follow-up/type/
        • Create skill follow up (requirement 30)
          POST /core/follow-up/skill
    Placeholder for indentation

Resources

Resources (text/media used as output messages by the Bot) can be attached 
to any object that has a placeholder object. 

  • Produce Output Messages (requirement 44)
    Get available resource types
    GET /core/resource/type/
    Create a text resource
    POST /core/resource/text/
    Lookup the available resource for a certain placeholder
    GET /core/resource/placeholder/{id)/

Variables Setup

Variables need to be configured in order for the Bot to be able to correctly collect
and use them in conversation. To build a variable multiple steps are required.

  • Creation, Labelling and Usage of Variables
    Get all variables
    GET /core/variable/object/
    Create a new collected variable (requirement 48)
    • Manage entity types
      • Get available entity type types
        GET /annotation/entity-type/type *
      • Get already defined or pre-defined entity types (requirement 12)
        GET /annotation/entity-type/
      • Create a trainable entity-type (requirement 11)
        POST /annotation/entity-type/
      • Add example entities 
        POST /annotation/entity/
    • Create a variable slot
      • Get available slot types
        GET /core/variable/type/
      • Create a slot
        POST /core/variable/collected/
    • Setup Collection of Variables (requirement 47)
      • CRUD for variable collection segments
        POST /core/variable/collection-segment/
      • to label the inform intent (found in the default_intent_type 
        a variable collection segment object) check here
      • To append output messages for ask and acks check here
      • Configure the fallback for failed collection (requirement 49) by
        posting a resources on the placeholder with ID found in the 
        fallback_placeholder property of the object
    Create a new computed variable (requirement 45)
    • Create an Action as specified here
    • ApiOutputs will automatically appear as computed variables
    For using variables in skills check here

Api Setup

Api objects need to be configured in order for the Bot to be able to correctly use them in conversation.
To build an action multiple steps are required.

  • Api object configuration
    • Create an Authentication Api object
      • Get the supported authentication types (basic, oauth2)
        GET /core/block/api/auth/type/
      • Create the Api Auth object 
        POST /core/block/api/auth/{type}/
    • Get the request types (GET, POST, DELETE, PUT)
      GET /core/block/api/request-type/
    • Create an Api Object
      POST /core/block/api/object/
    • Configure inputs of the API
      • Get the supported request parameters (query, header, body)
        GET /core/block/api/request-parameter-type/
      • Get the supported Api Input types (static, collected-variable-based)
        GET /core/block/api/input/type/
      • Create an Api Input object
        POST /core/block/api/input/{type}
      • Map the Api Input object with the Api object
        • IF the Api Input object is of type "collected_variable_based"
          POST /core/block/api/api-input-collected-variable-mapping/
        • IF the Api input object is of type "static"
          POST /core/block/api/api-input-mapping/
    • Configure outputs of the API 
      • Create the Computed Variable object (Api Output)
        POST /core/block/api/computed-variable/
        The path parameter is a string that illustrate how to parse
        the desired result out of the JSON response of the API
        The syntax includes for the path includes:
        • "/" as symbol to split different keys
        • "[" "]" around a key if it has to be interpreted as a numeric key
          or list index 
        E.g: path="results/extended/cities/[0]/id" will extract the id of the first object
        in the cities array found in the extended property of the results object of
        the response
      • Map the Computed Variable object with the Api Object
        POST /core/block/api/computed-variable-mapping/
  • For using actions in skills check here

Keyword Based Intent Disambiguation (wip)

This functionality implements requirement number 10 (requirement 10) and allows the user to
"tag" the skills with some labels and specify a set of keyword aliases for those labels.

  •  Manage Keywords
    • Retrieve all keyword objects
      GET /core/trigger/keyword/object/
    • Create a new keyword object
      GET /core/trigger/keyword/object/
      The keyword does not have Aliases yet
    • Manage aliases
      • Attach an alias
        POST         /core/trigger/keyword/alias/
      • Delete an alias
        DELETE /core/trigger/keyword/alias/{id}
  • Associate keywords and skills
    • To attach a keyword to a skill
      POST /core/trigger/keyword/
  • Customise disambiguation message
    • To customise the default disambiguation message (keyword-independent)
      Just attach resources (to see how check here) to the placeholder with
      id disambiguation_message found in the JSON object for a chatbot
    • To have a custom disambiguation message specific for a keyword
      Just attach resources (to see how check here) to the placeholder with
      id message_placeholder found in the JSON object for a keyword

Small Talk 

  •  Manage small talks (requirement 17)
    • Get available small talks types
      GET /core/small-talk/type
    • Get the small talks objects of a chatbot
      GET /chatbot/topic/{id}/
      You will find the objects in the small_talk property of the JSON response
    • To label the intent related to the small talk object check here
    • To append resources as responses of the bot in that small talk situation check here

Other Settings

File Uploads

  • Upload a file for labelling suggestions and word embedding fine tuning (requirement 28)
    POST /annotation/conv-file/

NLU Operations

  • Get NLU from data (train)
    POST /nlu/instance/
  • Load Previously saved NLU (reload)
    POST /nlu/instance/
    This time use the persisted_nlu parameter in the call
  • *Repeatedly check when the NLU is ready (health_state should be 'RUNNING (code 14)')
    GET /nlu/instance/{id}
  • Save an NLU (persist)
    POST /nlu/persist/
  • *Repeatedly check when the NLU has been saved (health_state should be 'HEALTHY (code 13)')
    GET /nlu/persist/{version}
  • Use an NLU to analyse a message (predict)
    POST /nlu/message/

Chatbot Operations 

  • Get Chatbot Instance from data (build)
    POST /chatbot/instance/
  • Load Previously saved Chatbot Instance (reload)
    POST /chatbot/instance/
    This time use the persisted_chatbot parameter in the call
  • *Repeatedly check when the chatbot is ready (health_state should be 'RUNNING (code 14)')
    The chat interactions will only start after the chatbot has posted the welcome message in the room.
    GET /chatbot/instance/{id}
  • Save a Chatbot Instance (persist)
    POST /nlu/persist/
  • *Repeatedly check when the chatbot has been saved (health_state should be 'HEALTHY (code 13)')
    GET /nlu/persist/{version}
  • Send a message to the room (requirement 32)
    POST /chatbot/message/
  • *Repeatedly check for new messages in the room
    GET /chatbot/instance/{id}

End-to-end Chatbot Instance Training *

This use case applies to the scenario in which we are developing a chatbot and we wanna try it within the tool for development purposes.

  • Build your chatbot (see Chatbot Construction) 
  • Train the Chatbot 
    POST /nlu/instance/
    • *You can repeatedly check when the chatbot is ready (health_state should be 'RUNNING (code 14)')
      GET /chatbot/instance/{id}
  • Build the Chatbot Instance
    POST /chatbot/instance/
    • *You can repeatedly check when the chatbot is ready (health_state should be 'RUNNING (code 14)')
      GET /chatbot/instance/{id}
  • if you wanna be able to deploy the chatbot
    • Save the NLU 
      POST /nlu/persist/
      • *You can repeatedly check when the chatbot has been saved (health_state should be 'HEALTHY (code 13)')
        GET /nlu/persist/{version}
    • Save the Chatbot Configuration
      POST /chatbot/persist/
      • *You can repeatedly check when the chatbot has been saved (health_state should be 'HEALTHY (code 13)')
        GET /nlu/persist/{version}

End-to-end Chatbot Instantiation *

This use case applies to the scenario in which we wanna use an already developed and saved chatbot.

  • Load your saved NLU 
    POST /nlu/instance/
  • Load your Chatbot Configuration
    POST /chatbot/instance/

Run a Chat for an Anonymous Users *

This use case applies to the scenario in which we want an end user (possibly anonymous) to use an already developed and saved chatbot.

  • Register the user on the fly using  
    POST /accounts/chat-user/
  • Start the bot instance using 
    POST /snippet/start/
  • Pull the room messages using
    POST /snippet/read/
  • Message the chatbot
    POST /snippet/chat/

Live monitoring functionalities *

This use case applies to setup live monitoring of running conversations

  • Grant admin authorisation to a user
    GET /chatbot/chat-authorization/
    with permission field to 'ADMIN'
  • Get all running sessions (the active ones will have health_state : 'RUNNING (code 14)')
    GET /chatbot/instance/
  • Pull the messages of a single session (requires admin authorisation)
    GET /chatbot/instance/{id}
  • Post a message in the room (requires admin authorisation)
    POST /chatbot/message/
  • Send handover command
    POST /chatbot/message/
    message request parameter set to 'HANDOVER'
  • Interrupt handover
    POST /chatbot/message/
    message request parameter set to 'HANDOVER-END'