API pro integraci chatbota

Autentizace

Požadavky posílané chatbotem přes API se autentizují pomocí bearer tokenu. Každá zpráva od bota se posílá HTTP požadavkem s hlavičkou Authorization: Bearer <token>

Token lze získat dvěma způsoby:

1. Získání bearer tokenu pomocí oauth2 endpointu (stará metoda)

   1. /login/connect/token

   2. client_id a client_secret jsou dostupné v nastavení chatbota

2. Automaticky generovaný token platný pro jednotlivé sezení (doporučeno)

   1. Každá příchozí aktivita na webhook obsahuje HTTP hlavičku X-Session-Token obsahující bearer token. Samotná aktivita obsahuje sessionId

   2. Každá konverzace se vždy zahajuje tím, že mluvii pošle aktivitu ChatbotConversationStarted

   3. Chatbot si musí držet mapu aktivních konverzací sessionId → token

   4. Když chce chatbot odpovědět v daném sezení použije tento token k autentizaci

Reference Webhook Event aktivit

Mluvii aplikace posílá eventy do vašeho webhooku pro notifikaci bota, když se uskuteční různé interakce nebo události, včetně zaslání zprávy klientem. Webhook eventy jsou odeslány z Mluvii jako POST request na váš webhook.

Tento callback přijde, když byla odeslána aktivita z mluvii chatbot sezení do vašeho chatbota. Můžete přijmout textové zprávy, nebo zprávy s přílohami.

Typy příloh 'image', 'text', 'audio', 'video', 'file' jsou hlavními podporovanými typy.

Můžete také přijmout 'fallback' přílohy. Všeobecný příklad 'fallback' přílohy je sdílení URL stránky. Prázdná 'fallback' příloha může být zaslána vašemu chatbotovi, když uživatel sdílí nepodporovanou přílohu.

Callback si nastavíte v detailu vašeho konkrétního chatbota v sekci Chatboti.

Požadavky na výkonnost Webhooku

Váš webhook by měl splňovat tyto minimální výkonnostní standardy:

• 200 OK odpověď na všechny webhook eventy

• odpověď na všechny webhook eventy do 2 sekund

Pokud váš webhook nesplní tyto požadavky po dobu víc než 15 minut, chatbot bude odpojen od přijímání webhook eventů a bude vypnutý v Mluvii.

Validace webhook eventů

Je doporučeno použít autorizaci pro callback URL. Například access token nebo basic authorization v URL. Příklad callback url:

 https://www.example.com/api/access_token=YOUR_ACCESS_TOKEN

Webhook eventy

Na zaregistrovaný webhook se poslají tyto typy událostí:

Webhook Event	Popis
ping	rezervováno pro ověření funkčnosti služby. Tento typ eventu musí být implementován s response 200 OK.
activity	aktivita zaslána uživatelem, operátorem nebo systémem. Seznam aktivit odesílaných na webhook.

Formát těla příchozího webhooku z mluvii

Ping

{
  "Activity": "Ping"
}

Activity

{
  "activity": "Text",
  "timestamp": "2020-09-09T10:03:46.792954",
  "text": "Hello world!",
  "sessionId": 2359788,
  "language": "en",
  "source": "Default"
}

Response aktivity je doručena vždy na Callback URL daného chatbota.

Připojení chatbota do sezení

Moment připojení chatbota do sezení je označen aktivitou ConversationStarted. Ta se může vyskytnout na začátku sezení či v jeho průběhu bezprostředně po přesměrování sezení na daného chatbota.

Pokud je jako source uvedena hodnota Default, jedná se o WebChat. Pro kompletní výčet viz Zdroj sezení.

{
  "activity": "ConversationStarted",
  "timestamp": "2020-09-09T09:59:49.5640515+02:00",
  "sessionId": 2359753,
  "language": "en",
  "source": "Default"
}

Odpojení chatbota ze sezení

Při ukončení konverzace (konec sezení, forward od chatbota na někoho jiného) se pošle aktivita ConversationEnded. Implementace chatbota může např. v reakci na tuto aktivitu smazat dočasná data konverzace nebo ukončit persistentní actory (akka.net implementace).

Send API

Send API je hlavní API použité pro posílání zpráv uživatelům, včetně textu, příloh, strukturovaných šablon, akcí odesílatele a dalších. Chatbot může odpovědět jenom na konverzaci, kterou přijal a je na ní naroutován. Formát API naleznete v této sekci.

Performance požadavky

Váš request by měl splnit následující výkonnostní požadavky:

• maximální počet requestů je 120/min v 1 sezení

Podporované zprávy podle komunikačního kanálu

Aktivity jsou rozdělené podle kanálu, který je podporuje. Zde najdete seznam podporovaných aktivit.

V prvním seznamu nalezete aktivity, které jsou společné napříč všemi kanály.

Ve druhém pak ty, které jsou pouze pro mluvii chat.

Dobré vědět

Facebook

• Pro Facebook je nutné dodržet přísnější pravidla, veškerá omezení jsou dostupná v oficiální dokumentaci https://developers.facebook.com/docs/messenger-platform/reference

• V případě, že chatbot pošle nevalidní zprávu, kterou nelze zobrazit, tato zpráva se ve Facebook Messengeru nezobrazí.

• Facebook podporuje zobrazení maximálně 3 tlačítek.

Obecné

• Každé tlačítko má omezený počet znaků.

• Není možné poslat tlačítka bez textu v title, subtitle, nebo v textu.

Odeslání aktivity

Každá akce mezi chatbotem a sezením se nazývá aktivita. Pro posílání aktivit je nutné znát chatbotId. ChatbotId lze nalézt v url při editování chatbota. Například:

.../app/31/22/settings/chatbots/edit/166/general

Pokud pošlete request, dostanete okamžitě zpět odpověď se statusem 200 OK. Pokud na request čekáte nějakou odpověď, např. při GetAvailableGroups, dostanete také ihned 200 OK, ale odpověď GetAvailableGroupsResponse vám přijde do webhooku.

Každý request musí obsahovat sessionId a měl by mít následující formát:

Request to /api/v1/Chatbot/{chatbotId}/activity

{
  "sessionId": "2359788",
  "type": "message",
  "text": "Sample text",
  "timestamp": "2020-09-09T10:03:53.4976861+02:00"
}

Kam pokračovat dál:

Zkontrolujte podporované aktivity