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 Ostatní->Aplikace->Api klíče)

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 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 Mluvii chat
Callback Callback
Invitation Pozvánka
IncomingCall Příchozí hovor
OutgoingCall Odchozí hovor
Campaign Kampaň
API Public API
Facebook Facebook
WhatsApp WhatsApp
VK VKontakte

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

results matching ""

    No results matching ""