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 :
- Vygenerované API uživatelské jméno a heslo (client_credentials).
- 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.
Vlastnost | Hodnota |
---|---|
userId | number |
status | Stav operátora |
availabilityStatus | Stav dostupnosti operátora |
availabilityStatusReason | string |
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.
Vlastnost | Hodnota |
---|---|
id | number |
channel | Kanál sezení |
source | Zdroj sezení |
tenantId | number |
SessionStarted
Spustí se při zahájení relace (operátorem nebo chatbotem).
Vlastnost | Hodnota |
---|---|
id | number |
channel | Kanál sezení |
source | Zdroj sezení |
started | datetime |
tenantId | number |
SessionForwarded
Spustí se při předávání relace.
Vlastnost | Hodnota | Popis |
---|---|---|
id | number | - |
channel | Kanál sezení | - |
source | Zdroj sezení | - |
time | datetime | - |
userId | number | omitted if not forwarded to an operator |
operatorGroupId | number | omitted if not forwarded to a group |
chatbotId | number | omitted if not forwarded to a chatbot |
tenantId | number | - |
SessionEnded
Spustí se při ukončení relace (operátor nebo klient ukončil sezení).
Vlastnost | Hodnota | Popis |
---|---|---|
id | number | - |
channel | Kanál sezení | - |
source | Zdroj sezení | - |
started | datetime | null pokud sezení nezačalo |
ended | datetime | - |
tenantId | number | - |
SessionOperatorJoined
Spustí se při vstupu operátora do sezení.
Vlastnost | Hodnota |
---|---|
id | number |
userId | number |
channel | Kanál sezení |
source | Zdroj sezení |
time | datetime |
tenantId | number |
SessionOperatorLeft
Spustí se při odpojení operátora od sezení.
Vlastnost | Hodnota |
---|---|
id | number |
userId | number |
channel | Kanál sezení |
source | Zdroj sezení |
time | datetime |
tenantId | number |
SessionOperatorConcluded
Spustí se při ukončení sezení operátorem nebo po vypršení ACW limitu.
Vlastnost | Hodnota |
---|---|
id | number |
userId | number |
channel | Kanál sezení |
source | Zdroj sezení |
time | datetime |
tenantId | number |
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.
Vlastnost | Hodnota | Popis |
---|---|---|
id | number | Jedná se o sessionId |
tenantId | number | - |
EmailThreadCreated
Spustí se při vytvořeni noveho email vlakna buďto napise client nebo operator.
Vlastnost | Hodnota |
---|---|
id | number |
created | datetime |
tenantId | number |
EmailThreadOperatorJoined
Spustí se kdyz operátor vstoupi do e-mail vlakna.
Vlastnost | Hodnota |
---|---|
id | number |
time | datetime |
userId | number |
tenantId | number |
EmailThreadOperatorLeft
Spustí se při odpojení operátora od e-mail vlakna.
Vlastnost | Hodnota |
---|---|
id | number |
time | datetime |
userId | number |
tenantId | number |
EmailThreadForwarded
Spustí se při předávání relace.
Vlastnost | Hodnota | Popis |
---|---|---|
id | number | |
time | datetime | |
userId | number | omitted if not forwarded to an operator |
operatorGroupId | number | omitted if not forwarded to a group |
tenantId | number |
EmailThreadParamsUpdated
Spustí se při přidání parametru k e-mailovému vláknu operátorem, nebo pomocí public api.
Vlastnost | Hodnota | Popis |
---|---|---|
id | number | Jedná se o e-mail thread id |
tenantId | number | - |
GuestIdentityUpdated
Spustí se po editaci informací u klienta.
Vlastnost | Hodnota |
---|---|
id | number |
tenantId | number |
SessionActivityAvRequest
Spustí se při pokusu o navázání AV přenosu.
Vlastnost | Hodnota |
---|---|
sessionId | number |
operatorId | number |
SessionActivityAvTerminated
Spustí se při ukončení AV přenosu.
Vlastnost | Hodnota |
---|---|
sessionId | number |
operatorId | number |
SessionActivityAvResponse
Spustí se při reakci uživatele na pokus o AV spojení.
Vlastnost | Hodnota |
---|---|
sessionId | number |
operatorId | number |
response | SessionAVRequestState |
SessionActivityAvMediaResult
Spustí se při navázání AV spojení.
Vlastnost | Hodnota |
---|---|
sessionId | number |
operatorId | number |
isStreamAvailable | bool |
response | GetMediaResult |
SessionActivityHeroCardSubmission
Spustí se při potvrzení/zrušení hero karty.
Vlastnost | Hodnota | Popis |
---|---|---|
sessionId | number | |
originalFormID | number | |
result | HeroCardSubmissionResult | |
submittedByClient | bool | pokud hero kartu vyplní uživatel, bude hodnota na true, pokud ji vyplní operátor, bude hodnota false |
params | dictionary | obsahuje vyplněné údaje |
HeroCardSubmissionResult
Hodnota | Popis |
---|---|
Submitted | Údaje potvrzeny |
Cancelled | Vyplnění hero karty zrušeno |
GetMediaResult
Hodnota | Popis |
---|---|
Success | Úspěšný přenos |
NoCameraOnlyMic | Pouze mikrofon |
NoDevices | Žádná zařízení pro přenos audio/video |
UserDenied | Uživatel nepovolil audio/video zařízení |
SessionAVRequestState
Hodnota | Popis |
---|---|
Requested | Vyžádáno |
Accepted | Přijato |
RejectedUser | Odmítnuto uživatelem |
RejectedNoMic | Uživatel nemá mikrofon |
Zdroj sezení
Hodnota | Popis |
---|---|
Default | WebChat |
Callback | Callback |
Invitation | Pozvánka |
IncomingCall | Příchozí hovor |
OutgoingCall | Odchozí hovor |
Campaign | Kampaň |
API | Public API |
VK | VKontakte |
Apple | Apple Messages for Business |
Kanál sezení
Hodnota | Popis |
---|---|
AV | Audio video přenos |
Chat | Textový kanál |
Phone | Telefonní hovor |
Stav operátora
Hodnota | Popis |
---|---|
OFFLINE | Odhlášený |
ONLINE | Dostupný |
AWAY | Nedostupný |
Stav dostupnosti
Hodnota | Popis |
---|---|
DEFAULT | Online |
AWAY | Pryč |
ON_CALL | AV nebo telefonní hovor |