Integrations basics

Integration is anything which enables chatbot to connect with outside world. It could be initiated by the chatbot using step on certain point in the chatbot tree or in the opposite by some external system by triggering some of bot APIs.

Integration step

Integration step could be added to any place of chatbot tree and is triggered in the moment when any user is passing given point in the conversation. It can call any of supported APIs, pass parameters inside (static or dynamic based on data we already know about the user using variables) and store results for further usage.

Use-cases

• Fetching some data from system to show (in mesage, carousel, ...) or use for further decisions in the bot flow (for example show available job positions) - examples of use:
  • Show carousel of available job positions in ATS system
  • Show carousel of recommended products in eshop
  • Get maximum loan value based on values entered by the user
• Storing some data from bot to external system (add new candidate to selected position using data user entered)
  • Store candidate application to ATS system with all gathered information (name, email, phone, position ID)
  • Order some selected product in e-commerce platform
  • Create support ticked based on gathered clues in servicedesk systems like Jira 
• Triggering some action in external system (trigger remote modem restart in internet connection helpdesk bot)

Architecture

Every integration step type consists of two parts. First of them is JSON schema which describes what input parameters of which types are expected, which of them are required and what output structure should be expected. Second part is the code itself which implements:

• How is bot authenticated (in the most cases using some predefined token stored in the bot settings)
• How are parameters transformed and attached to the call
• How are output data transformed before saved into output variable
• Error handling
  • show fatal bot error to the user and stop conversation
  • trigger some predefined dialog
  • just log error and save some flag to user data variable so some decision could be made in the tree based on it

In ideal case, integration step performs just a single API call but in some advanced scenarios it is often needed to perform multiple calls and combine input/output data to fulfill desired goal.

Advanced topics

Timing

Integration step could behave in three different ways from the point of view of timing and performance.

• Synchronous call
  • User needs to wait for completion of API call during conversation
  • All data returned from API could be saved and used further 
  • Data are not stored in bot database so filtering/searching should be performed on target system and just required subset of data should be returned
  • System should be stable and response should be fast (max. few seconds) to not let user wait too long 
• Asynchronous call
  • Fire the request but do not wait for the result and continue immediatelly
  • Can be used to trigger some not-critical action where we do not need to know the result
  • For example track event into some analytics system
• Call on background
  • Data could be downloaded on background and stored into bot's database
  • They are later accessed locally by integration step during conversation quickly without need of any other system
  • Bot needs to filter/search data by itself which has limited performance (max. thousands of rows) and features (only filter by by tags or by locality radius)
  • Works also fine for slow and unstable data sources
  • There could be several ways how to trigger background data update
    • Periodical pull (reliable but consumes an unnecessarily large amount of resources)
    • Push (external server pushes data to the bot when some change occurs - always all of them or incrementally)
    • Pull on change (external server just signals bot that there is some change and bot do the same as during periodical pull)

Level of abstraction

It is very important to consider which level of abstraction use during the process of integration step design. For example imagine that we have some system called "MyCRM" with a lot of modules with REST API which can perform insert/update/delete operations on any of them when every module has different set of fields. Goal of prepared integration is just to add customer with given name and email. Now we have at least three levels of abstraction to choose from:

• Action level
  • The most specific, single purpose, very easy usage, need to change the code during every change of logic
  • Integraton called mycrm-add-contract 
  • Parameters name=... and email=... 
  • Returns id=... which could be used directly
• Protocol level
  • The most generic, versatile, difficult usage, do not need to change the code when logic changes, API needs to support such generic format
  • Integration called rest 
  • Parameters endpoint=mycrm.com/api/v1/customers, method=post, body={"name":"...","email":"..."} 
  • Returns {"response": {"body": {"id":"...", ...}, ...}, ...} which needs to be parsed
  • For such purposes, there is already an integration step called HTTP GET/POST request
• Service level
  • Balance between two levels above
  • Integraton called mycrm 
  • Parameters module=customers, action=add, body={"name":"...","email":"..."} 
  • Returns {"id":"...", ...} which needs some simple parsing

It could not be said in a generic way which of these levels is correct. It always depends on given use-case, specs of used API and plans for future modifications of logic by non-programmers.

Channels

Channel is used to transfer messages from bot the user and back. We have some channel integrations built in the product itself, but it is possible to integrate any custom chat channel with proper API. There are three ways how to do it:

• Feedyou will implement connector to present API of the new channel
• Channel will implement connection to generic Microsoft Bot REST API which is already supported (more info here)
• Channel will be part of some channel-aggregation platform which is already supported by Feedyou such as MS Bot Service or Mluvii

Some chat channels also support transferring events during the same "pipe" which is used for messages. Example could be WebChat component which allows:

• during initialization of chat component on the web page, any data we know about the user (such as email, selected page, auth token, ...) could be passed in and then can be further used in the chatbot tree for decision or passed into other integrations (for example auth token passed from the web page could be used for API authentication with user-scoped access permissions)
• when any event happens for page (for example user clicks some element, fill form field, etc.), webchat can send event to the bot to save some user data, start selected dialog and so on
• in the opposite when user reaches some point in the tree, it is possible to send event from bot to the webchat component and trigger predefined listener to perform any code in the page (for example close chat, reload page, ...)

Dialog trigger

External system can trigger selected dialog for given user by calling Trigger API which has following parameters:

• Selected user address (probably previously stored in some output integration, some segmentation filter could be also available in the future instead of single ID)
• Dialog ID to trigger
• Optionally list of user data to preset before triggering dialog

You can read more in Trigger API documentation.

User data export

There is an API exposed by every running chatbot which could be used to retrieve all stored data for every user. This API is mainly used for analytic purposes (such as how many users have passed certain point in the tree - and thus have given storage filled) but also could be used for anything else. There are available basic parameters that could be used to filter out only given subset of users.

You can read more in Export API documentation.

Preset integrations

There is already a lot of integrations already implemented in Feedbot Designer. You can check this spreadsheet to find out more. It is important that every system could be integrated in large number of different ways with different options so it is needed to consider given use-case carefully. 

API automation platforms

Not all integrations needs to be programmed directly in the bot's code. Different kinds of automation/integration platforms or tools could be used to connect different services including bot to implement needed logic. Good examples of these platforms could be:

• Integromat
• Zapier
• Microsoft Azure Logic App
• ... and many others

Adding new integrations

Following list tells what is often needed to have to allow new integration to be implemented:

• Well described use-case incl. the way how integration should be used in the chatbot tree such as input/output variables and how they will be used on other parts of the tree
• API specification incl. authentication (if target system currently do not have any and is going to prepare some just for the chatbot, take a look at the example how we think this API should look like)
• Example credentials to be able to test integration during implementation against real system