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í

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

results matching ""

    No results matching ""