API

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

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:

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.

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:

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:

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

Dialog trigger

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

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:

Adding new integrations

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

Export API

Base URL for export API is bot-specific https://feedbot-${BotId}.azurewebsites.net. Please use the ?code=...query param or x-functions-key: ... HTTP header to perform token based authentication.

Get users data

Calling this endpoint without timestamp filters can return very large amount of data and affect bot performance. Regular daily fetching of data from the past day is recommended approach.

GET /api/management/export/userData

Returns list of objects containing all user-scoped data which bot persists. Optional filters parameters:

userId
timestamp
... all storages in camelCase ... 
Examples

Get users data snapshot

This API method is available since bot hosting version v1.7.474

GET /api/management/export/userDataSnapshot

Returns list of objects containing all user-scoped data snapshots (generated by the "clear user data" action) which bot persists. Usage and all params are the same as in "Get users data" API. 

userId
timestamp
... all storages in camelCase ... 

Get NLP logs

This API method is available since bot hosting version v1.7.474

GET /api/management/export/nlpLog

Returns list of objects containing all inputs entered by the user which was not possible to process using conversation tree. Desired time range could be specified using fromTimestamp and toTimestamp second-based UNIX timestamp.

userId
timestamp
dialogId
stepId
stepType
query
modelId
intent
result
processed

Get outgoing emails

This API method is available since bot hosting version v1.7.474

GET /api/management/export/outgoingEmail

Returns list of objects containing all emails sent by the chatbot incl. recipient, subject, body. Desired time range could be specified using fromTimestamp and toTimestamp second-based UNIX timestamp.

userId
timestamp
body
from
recipients
replyTo
stepId
subject

Get outgoing SMS

This API method is available since bot hosting version v1.7.474

GET /api/management/export/outgoingSms

Returns list of objects containing all SMS messages sent by the chatbot. Desired time range could be specified using fromTimestamp and toTimestamp second-based UNIX timestamp.

userId
timestamp
channel
link
message
provider
recipients

Get fuzzy question answers log

This API method is available since bot hosting version v1.7.474

GET /api/management/export/fuzzyQuestionAnswerLog

Returns list of objects containing all utterances processed by the fuzzy question answer plugin. Desired time range could be specified using fromTimestamp and toTimestamp second-based UNIX timestamp.

userId
timestamp
intent
score
text
stepId
dialogId
matched
otherClassifications

Get integration log

This API method is available since bot hosting version v1.7.474

GET /api/management/export/integrationLog

Returns list of objects containing all integration invocations. Desired time range could be specified using fromTimestamp and toTimestamp second-based UNIX timestamp.

userId
timestamp
url
method
requestBody
requestHeaders
responseStatus
responseBody
duration

 

Get URL tracker

This API method is available since bot hosting version v1.7.474

GET /api/management/export/urlTracker

Returns list of objects containing row for every click on URL button in bot by every user including target URL and domain. Desired time range could be specified using fromTimestamp and toTimestamp second-based UNIX timestamp.

userId
timestamp
domain
url

 

Trigger API

Pro vyvolání určitého dialogu pro vybraného uživatele ve virtuálním asistentovi iniciované externím systémem je možné využít Trigger API.

Každý bot běží na své doméně (většinou ve formátu  https://feedbot-${BOT_ID}.azurewebsites.net) a je chráněn klíčem buď v  ?code=... URL query parametru nebo x-functions-key: ... HTTP hlavičce.

POST /api/management/trigger/${ADDRESS_JSON_AS_BASE64}/${DIALOG_ID}/${MODE?}

Příklad použití

External API recommendations

Do virtuálního asistenta je možné připravit libovolné množství "integračních kroků", což jsou body konverzačního stromu, kdy se virtuální asistent pomocí API integruje s jiným systémem za účelem získání nějakých dat nutných pro svou funkci nebo naopak nějaká data, která od uživatele zjistil do systému posílá.

Ve formátu a struktuře API se virtuální asistent může poměrně dost přizpůsobit, pokud by ale API vznikalo až kvůli němu, je možné se držet následujících doporučení, aby implementace byla co nejplynulejší.

Doporučené vlastnosti API
Ukázka

Virtuální asistent může pomocí API získat ze závislého systému seznam událostí, které má naplánované. ID uživatele jsou předány např. do WebChat komponenty uvnitř nějakého interního systému, kde je uživatel již autentizován. Data bot využije k zobrazení "carouselu" s naplánovanými událostmi, kde si uživatel jednu z nich může vybrat a pokračovat nějakou další akcí.

GET https://somedomain.cz/api/v1/user/33/events

Authorization: Bearer ...
Content-type: application/json

→ 200 [{"id":"1", "name":"Onboarding meeting", "date":"2020-05-07T08:22:30.871Z"}]

Na konci komunikace může virtuální asistent odeslat informace o nově získaném uživateli do CRM. Součástí požadavku můžou být všechna data, která virtuální asistent o uživateli posbíral.

POST https://somedomain.cz/api/v1/user

Authorization: Bearer ...
Content-type: application/json
{"email": "user@example.com", "name":"Jack", "surname":"User", "interestedInProductIds": [244, 234]}

→ 200 {"id":"433"}

Custom channel API

API documentation

JSON

JSON (JavaScript Object Notation) je nejčastěji používaný formát pro reprezentaci dat - používá se pro specifikaci API, configů, nebo se do něj dá ukládat celý bot - což mimo jiné náš případ 😉

JSON slouží zejména k popisování vlastností objektů. Objekt je v tomto případě jakákoli věc o které chceme zjistit jaké vlastnosti má. Vlastnosti objektu pak popisujeme takto:

"klíč": "hodnota"

Například pokud bychom popisovali vlastnost auta tak jeho objekt mohli popsat takto:

{
  "color": "blue",
  "doorCount": 3,
  "brand": "Toyota",
  "engine": {
  	"fuel": "petrol",
    "engineCapacity": 1.3,
    "cylinderCount": 4
  },
  "assets": ["AC", "GPS"]
}

Zde popisujeme vlastnosti auta jako jsou barva, počet dveří atd., kromě toho je zde zanořený objekt s vlastnostmi motoru a pole s doplňky auta - klimatizace a GPS

Objekty a pole mohou obsahovat další objekty a pole, toto může sloužit k oddělení kontextu dat

Typy v JSONu

Přístup k hodnotám

K hodnotám v JSONu lze přistupovat přes tečkovou notaci, tedy pokud budeme mít například tento JSON:

{
  "color": "blue",
  "doorCount": 3,
  "brand": "Toyota",
  "engine": {
  	"fuel": "petrol",
    "engineCapacity": 1.3,
    "cylinderCount": 4
  },
  "assets": ["AC", "GPS"]
}

a budeme chtít zjistit obsah motoru, tak toho docílíme tímto řádkem:

car.engine.engineCapacity

pokud budeme chtít zjistit jaká je první položka v seznamu doplňků, tak toho docílíme tímto řádkem:

car.assets[0]

První položku získáme přístupem do indexu 0, protože JavaScript čísluje pole od 0

Podklady pro vytvoření integračního kroku

Ahoj, jsem tvůj checklist k tomu, aby se výroba integračního kroku obešla bez zbytečných prodlev. Drž se mě a za hodinu můžeš mít perfektní integrační krok a všichni budou nadšený 🎉. A to je skvělý, no ne?

Takže co teda budem potřebovat?

1. API URL klienta

Když chceme někam sáhnout pro data, nebo je někam zapsat, musíme vědět kam - k tomu nám slouží API url, která nás navede na rozhraní klienta, přes které nám poskytne data, nebo nám umožní je zapisovat.

2. API Key klienta

Protože bezpečnost je důležitá a klient ve většině případů nebude chtít, aby mu kdokoli mohl sáhnout do databáze, bude mít svoje API nějak zabezpečené, ve většině případů se bude jednat o zabezpečení s Bearer klíčem. Ten budeme muset od klienta dostat, abychom byli schopni zavolat API.

Příklad klíče: Authorization: Bearer abcdef1234

3. Specifikace API

Specifikace API je potřeba, abychom věděli z jakého koncového bodu, jaké informace posílat, nebo stahovat. Jedná se v podstatě o takovou "dohodu" mezi námi a klientem jaká data, a v jakém formátu, očekáváme. Součástí specifikace může, ale nemusí být API URL a API klíč, na toto není pravidlo a každý klient specifikaci pojímá jinak, proto je dobré se zeptat, zda tyto informace specifikace obsahuje, pokud neobsahuje tak je potřeba o ně požádat.

4. Příklad volání

Ke konečnému otestování je potřeba mít nějaká data, na kterých si dokážeme zjistit, jak získaná data reprezentovat v botovi. Tedy například pokud se jedná o bota pro zásilkovou službu a klient chce zobrazovat data o zásilce na základě zadaného čísla zásilky, tak budeme potřebovat nějakou testovací zásilku abychom si ověřili, zda volání proběhlo v pořádku. 

 

Campaigns API

API specification