Links

REST API

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. 1.
    Vygenerované API uživatelské jméno a heslo (client_credentials).
  2. 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í společnosti->Api klíče)
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
availabilityStatus
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
source
tenantId
number

SessionStarted

Spustí se při zahájení relace (operátorem nebo chatbotem).
Vlastnost
Hodnota
id
number
channel
source
started
datetime
tenantId
number

SessionForwarded

Spustí se při předávání relace.
Vlastnost
Hodnota
Popis
id
number
-
channel
-
source
-
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
-
source
-
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
source
time
datetime
tenantId
number

SessionOperatorLeft

Spustí se při odpojení operátora od sezení.
Vlastnost
Hodnota
id
number
userId
number
channel
source
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
source
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

SessionActivityAvMediaResult

Spustí se při navázání AV spojení.
Vlastnost
Hodnota
sessionId
number
operatorId
number
isStreamAvailable
bool
response

SessionActivityHeroCardSubmission

Spustí se při potvrzení/zrušení hero karty.
Vlastnost
Hodnota
Popis
sessionId
number
originalFormID
number
result
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
Facebook
Facebook
WhatsApp
WhatsApp
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