API pro integraci chatbota

Autentizace

Volání api chatbot musí být ověřena pomocí následujících kroků.

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"
}

Start sezení

Každé sezení začíná aktivitou ConversationStarted. 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"
}

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