REST API

Upozornění: Tento návod předpokládá, že zákazník využívá cloudové řešení aplikace mluvii. V případě, že zákazník využívá on premise varianty, je nutné zaměnit hostovací url za url zákazníkova serveru.

Jedná se o rozhraní, které umožňuje komunikaci mezi mluvii a vašimi interními aplikacemi. Data můžete přeposlat z mluvii do svých vlastních systémů pomocí REST API callů. Díky tomu uchováte data mimo platformu mluvii, vytvoříte vlastní reporting, integrujete systémy třetích stran a mnohem více. Můžete například automaticky připojit všechna sezení ke konkrétnímu zákazníkovi v CRM.

K čemu slouží?

REST API umožňuje hned několik užitečných akcí. Využijete ho například ve chvíli, kdy chcete převést informace o uživateli z aplikace do jiného systému. Slouží také k synchronizaci stavů uživatelů mezi mluvii a systémy třetích stran. Podstatnou akcí je také anonymizace údajů o klientech. Data lze anonymizovat jak v případě všech informací o klientovi tak u jednotlivých Sezení.

Pomocí REST API lze také zobrazit kompletní údaje o sezení nebo uživatelích aplikace (jméno, příjmení, e-mail, ID, username). Další možností je generování pozvánek s neomezenou platností a jejich pozdější zneplatnění. Administrátoři také jistě ocení možnost hromadně měnit vzhled a chování existujících balíčků (vizuál chatových tlačítek, skrývání tlačítek a změna formulářů).

V neposlední řadě lze díky volání tzv. webhook metody předávat informace z mluvii do jiného systému v reálném čase:

• změna stavu operátora,
• zahájení sezení,
• přepojení sezení na jiného operátora,
• ukončení sezení.

REST API Portál

Prostředí se nachází na adrese https://app.mluvii.com/api (v případě on premise varianty https://{vase_domena}/api). Kliknutím na tlačítko se můžete autentizovat jedním ze způsobů uvedených v sekci Autentizace a volat API přímo z portálu, kliknutím na tlačítko u konkrétní API metody.

Autentizace

Pokud chcete volat rozhraní REST API, musíte nejprve mít JWT token z autentizačního serveru. Token má platnost 1 hodinu, po uplynutí této doby musí být aktualizován (vydán znovu).

mluvii REST API umožnuje 2 způsoby autentizace podle OAuth2.0 standardu :

1. Vygenerované API uživatelské jméno a heslo (client_credentials).
2. Přihlášení přes login obrazovku (OpenID Connect)

1. API uživatelské jméno a heslo

Krok 1

Vygenerujte nové username a heslo pro API z administračního rozhraní mluvii. (Sekce Nastavení->Api klíče)

Poznámka: Pro přístup do sekce musíte mít oprávnění Správce společnosti!

Krok 2

Použijte generované heslo k volání autentizačního serveru.

curl -X POST \
  https://app.mluvii.com/login/connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'response_type=token&grant_type=client_credentials&client_id=<vaše API username>&client_secret=<vaše API heslo>'

On premise varianta: curl -X POST https://{vase_domena}/login/connect/token

Pro tento krok, je možné použít libovolnou knihovnu nebo nástroj, který podporuje OAuth2 standard,. např. Postman:

Krok 3

Použijte JWT token vrácený autentizačním serverem k volání rozhraní REST API pomocí http hlavičky "Bearer".

curl -X GET https://app.mluvii.com/api/v1/Sessions/{id} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'

On premise varianta: curl -X GET https://{vase_domena}/api/v1/Sessions/{id}

2. Přihlášení přes login obrazovku

Pokud zavoláte libovolnou API metodu bez tokenu, autentizační server požadavek přesměruje na přihlašovací stránku. Pokud máte práva administrátora, můžete po přihlášení volat API přímo z prohlížeče.

Webhooks

Tato část popisuje formát webových volání. Po odeslání dané události jsou tyto požadavky odeslány na vybranou adresu URL.

UserStatusChanged

Spustí se při změně stavu operátora.

SessionCreated

Spustí se při vytvořeni relace vstupem hosta do aplikace ještě před jejím přijetím operátorem nebo chatbotem.

SessionStarted

Spustí se při zahájení relace (operátorem nebo chatbotem).

SessionForwarded

Spustí se při předávání relace.

SessionEnded

Spustí se při ukončení relace (operátor nebo klient ukončil sezení).

SessionOperatorJoined

Spustí se při vstupu operátora do sezení.

SessionOperatorLeft

Spustí se při odpojení operátora od sezení.

SessionOperatorConcluded

Spustí se při ukončení sezení operátorem nebo po vypršení ACW limitu.

SessionCallParamsUpdated

Spustí se při změně call paramů v operátorovi, při potvrzení hero karty nebo call skriptu, pomocí feedback formuláře nebo přes public api.

EmailThreadCreated

Spustí se při vytvořeni noveho email vlakna buďto napise client nebo operator.

EmailThreadOperatorJoined

Spustí se kdyz operátor vstoupi do e-mail vlakna.

EmailThreadOperatorLeft

Spustí se při odpojení operátora od e-mail vlakna.

EmailThreadForwarded

Spustí se při předávání relace.

EmailThreadParamsUpdated

Spustí se při přidání parametru k e-mailovému vláknu operátorem, nebo pomocí public api.

GuestIdentityUpdated

Spustí se po editaci informací u klienta.

SessionActivityAvRequest

Spustí se při pokusu o navázání AV přenosu.

SessionActivityAvTerminated

Spustí se při ukončení AV přenosu.

SessionActivityAvResponse

Spustí se při reakci uživatele na pokus o AV spojení.

SessionActivityAvMediaResult

Spustí se při navázání AV spojení.

SessionActivityHeroCardSubmission

Spustí se při potvrzení/zrušení hero karty.

HeroCardSubmissionResult

GetMediaResult

SessionAVRequestState

Zdroj sezení

Kanál sezení

Stav operátora

Stav dostupnosti