API pro integraci chatbota

Autentifikace

Volání api chatbot musí být ověřena pomocí následujících kroků. Api klíč musí mít nastavené oprávnění chatbot.

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žívatel sdílí nepodporovanou přílohu.

Callback si nastavíte v mluvii v sekci Nastavení/Chatboti u Vašeho konkrétního chatbota.

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

Dostupné webhook eventy jsou vypsané v tabulce. Všechny webhooku jsou volitelné, proto použijte ty, které jsou relevantní pro vás.

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 Mluvii chat. 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.

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 a událostí. 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ě pokud chatbot pošle nevalidní zprávu, kterou nelze zobrazit. Tak tato zpráva se nezobrazí v facebook messengeru

• 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 text 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.

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