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

{
  userId: number,
  status: enum { OFFLINE, ONLINE, BUSY },
  availabilityStatus: enum { DEFAULT, AWAY, IDLE, BUSY_GUESTS, EXCLUSIVE_SESSION },
  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.

{
  id: number,
  channel: enum { Chat, AV },
  source: enum { Default, Callback, Invitation, ChatInvitation, API, Facebook, WhatsApp, VK }
}

SessionStarted

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

{
  id: number,
  channel: enum { Chat, AV },
  source: enum { Default, Callback, Invitation, ChatInvitation, API, Facebook, WhatsApp, VK },
  started: datetime
}

SessionForwarded

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

{
  id: number,
  channel: enum { Chat, AV },
  source: enum { Default, Callback, Invitation, ChatInvitation, API, Facebook, WhatsApp, VK },
  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 */
}

SessionEnded

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

{
  id: number,
  channel: enum { Chat, AV },
  source: enum { Default, Callback, Invitation, ChatInvitation, API, Facebook, WhatsApp, VK }
  started: datetime /* null if never started */,
  ended: datetime
}

SessionOperatorJoined

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

{
  id: number,
  userId: number,
  channel: enum { Chat, AV },
  source: enum { Default, Callback, Invitation, ChatInvitation, API, Facebook, WhatsApp, VK }
  time: datetime
}

SessionOperatorLeft

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

{
  id: number,
  userId: number,
  channel: enum { Chat, AV },
  source: enum { Default, Callback, Invitation, ChatInvitation, API, Facebook, WhatsApp, VK }
  time: datetime
}

SessionOperatorConcluded

Spustí se po vyplnění výstupního formuláře operátorem.

{
  id: number,
  userId: number,
  channel: enum { Chat, AV },
  source: enum { Default, Callback, Invitation, ChatInvitation, API, Facebook, WhatsApp, VK }
  time: datetime
}

SessionCallParamsUpdated

Spustí se při změně CallParams. Parametr Id je SessionID.

{
  id: number
}

EmailThreadCreated

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

{
  id: number,
  created: datetime
}

EmailThreadOperatorJoined

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

{
  id: number,
  time: datetime,
  userId: number
}

EmailThreadOperatorLeft

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

{
  id: number,
  time: datetime,
  userId: number
}

EmailThreadForwarded

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

{
  id: number,
  time: datetime,
  userId: number /* omitted if not forwarded to an operator */,
  operatorGroupId: number /* omitted if not forwarded to a group */,
}

Zdroj sezení