Česky
Mluvii web Login API DEMO

Podporované aktivity

Zde naleznete 2 sady podporovaných aktivit (globálně podporované aktivity a aktivity podporované jen částečně).

1) Aktivity podporované ve všech kanálech

  1. GetAvailableOperators

  2. GetAvailableGroups

  3. GetCallParams

  4. SetCallParams

  5. GetHeroCards

  6. SendGuestOfflineEmail

  7. GetGuestIdentity

  8. EndConversation

  9. Forward

  10. Handoff

  11. GetMediaObjects

2) Aktivity podporované jen v některých kanálech

Ne všechny tyto aktivity fungují ve všech kanálech. Facebook například podporuje jen některé aktivity. WhatsApp podporuje pouze základní text.

ActivityWebChatFacebookWhatsAppApple VK

Adaptive Cards

✔

✔

✘

✘

✘

Buttons

✔

✔

✘

✘

✘

Typing

✔

✘

✘

✔

✘

EnableGuestInput

✔

✘

✘

✘

✘

DisableGuestInput

✔

✘

✘

✘

✘

GetHeroCards

✔

✘

✔

✔

✘

SendHeroCard

✔

✘

✔

✔

✘

HeroCardSubmission

✔

✘

✔

✔

✘

ChatbotOpenFileUploadPrompt

✔

✘

✘

✘

✘

EnableGuestUpload

✔

✘

✘

✘

✘

DisableGuestUpload

✔

✘

✘

✘

✘

ShareFile (name)

✔

✔

✔

✔

✔

ShareFile (URL)

✔

✘

✘

✔

✔

Apple = Apple Messages for Business Facebook = Facebook Messenger

Aktivity

Způsob odeslání aktivity se liší podle typu chatbota:

  • Microsoft Bot Framework posílá aktivity pomocí ChannelData

  • Chatbot přes API posílá aktivity na API endpoint /api/v1/Chatbot/{chatbotId}/activity viz Odeslání aktivity

GetAvailableOperators

Získá seznam operátorů, kteří jsou přihlášeni a mají volné kapacity.

Pokud je parametr groupId nastaven, je vrácen seznam dostupných operátorů z vybrané skupiny.

Pokud parametr groupId není nastaven, dojde k opětovnému vyhodnocení routingových podmínek a je vrácen seznam dostupných operátoru pouze ze skupin, které splňují podmínky. Routingové podmínky se znovu vyhodnocují. Lze tedy změnit parametry sezení a dostat seznam dostupných operátoru podle aktuálních parametrů.

Request JSON:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "GetAvailableOperators",
  "groupId: <volitelné id skupiny operátorů>
}

Odpověď aktivity:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "GetAvailableOperatorsResponse",
  "availableOperators": [
    {
        "displayName":"Katka",
        "userId":1
    },
    {
        "displayName":"Tomáš",
        "userId":2
    }
  ]
}

GetAvailableGroups

Získá seznam skupin operátorů a jejich aktuální stavy.

Pokud je pole groupIds definováno, je vrácen seznam skupin podle tohoto pole.

Pokud parametr groupId není nastaven, dojde k opětovnému vyhodnocení routingových podmínek a je vrácen seznam skupin, které splňují podmínky. Routingové podmínky se znovu vyhodnocují. Lze tedy změnit parametry sezení a dostat seznam dostupných operátoru podle aktuálních parametrů.

Stav skupiny může nabývat těchto hodnot:

  • ONLINE - skupina má volné operátory

  • BUSY - všichni operátoři jsou obsazeni ale je volné místo ve frontě skupiny

  • OFFLINE - viz pole groupOfflineReasons

Pokud je skupina offline, pole groupOfflineReasons nabývá jedné nebo více hodnot:

  • BUSINESS_HOURS - skupina je mimo otevírací hodiny

  • NO_OPERATORS - ve skupině nejsou přihlášeni žádní operátoři

  • QUEUE_FULL - skupina má plnou frontu

  • DELETED - skupina byla smazána administrátorem

  • CHANNEL_BLOCKED - všichni operátoři mají zablokovaný kanál (ve kterém je sezení s chatbotem)

Request JSON:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "GetAvailableGroups",
  "groupIds: <volitelné pole id skupin operátorů>
}

Odpověď aktivity:

groupWorkload

  • maxSlots: Součet slotů všech přihlášených operátorů ve skupině

  • usedSlotsWaiting: Součet všech obsazených slotů čekajícími ve skupině

  • usedSlotsAccepted: Součet všech slotů obsazených odbavovanými sezeními ve skupině

  • freeSlots: Součet volných slotů všech operátorů ve skupině

queueWorkload

  • freeQueueSlotsCountTotal: Počet volných slotů ve frontě na skupině

  • inQueueCountTotal: Počet využitých slotů ve frontě na skupině

  • isQueueFull: freeQueueSlotsCountTotal == 0

{
  "sesionId": <nutné pouze u chatbota přes API>,
  "activity": "GetAvailableGroupsResponse",
  "availableGroups": [
    {
        "displayName":"Group one",
        "groupId": int,
        "groupState": jedna z hodnot: ONLINE, OFFLINE, BUSY,
        "groupOfflineReasons": [žadná nebo více z hodnot: BUSINESS_HOURS, NO_OPERATORS, QUEUE_FULL, DELETED, CHANNEL_BLOCKED],
        "groupWorkload": {
          "maxSlots": int,
          "usedSlotsWaiting": int,
          "usedSlotsAccepted": int,
          "freeSlots": int
        },
        "queueWorkload": {
          "freeQueueSlotsCountTotal": int,
          "inQueueCountTotal": int,
          "isQueueFull": boolean,
        }
    }
  ]
}

GetCallParams

Získá CallParams spojené s aktivním sezením.

Request JSON:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "GetCallParams"
}

Odpověď aktivity:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "GetCallParamsResponse",
  "callParams": <dictionary>
}

SetCallParams

Nastaví CallParams k aktivnímu sezení.

Request JSON:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "SetCallParams",
  "callParams": <dictionary>
}

Response Activity:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "SetCallParamsResponse",
  "success": <boolean>,
  "errorMessage": <string>
}

SendGuestOfflineEmail

Odešle email na adresu pro zprávy z offline formuláře. Offline formulář musí být nastaven na balíčku.

Request JSON:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "SendGuestOfflineEmail",
  "subject": <string>,
  "message": <string>,
  "location": <string> (zdroj zprávy pro rozlišení, např: "Chatbot Mluviik")
}

GetGuestIdentity

Vrátí všechny známé identifikátory uživatele.

Request JSON:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "GetGuestIdentity"
}

Odpověď aktivity:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "GetGuestIdentityResponse",
  "trackedGuestGuid": <Guid>, (unikátní identifikátor z cookie)
  "phoneCallerId": <string>, (telefonní číslo)
  "facebookPSID": <string>, (facebook identifikátor)
  "facebookPageId": <string>, (facebook identifikátor)
  "whatsAppContactId": <string>, (whatsapp identifikátor)
  "vkContactId": <string>, (vk identifikátor)
  "AppleContactId": <string>, (apple identifikátor)
}

Forward

Přesměruje interakci na živého operátora nebo skupinu. Alespoň jeden z parametrů operatorGroupId nebo userId musí být vyplněn.

Takto přesměrovaná sezení se chovají stejně jako sezení přesměrována ručně - tzn. ignorují nastavená kapacitní pravidla (velikost fronty skupiny/sloty operátora). Pokud chcete aby sezení nepřekročilo nastavená kapacitní pravidla použijte aktivitu HandOff nebo před přesměrovaním zjistěte aktuální vytížení operátorů pomocí aktivit GetAvailableOperators / GetAvailableGroups

Routingové parametry jsou znovu nevyhodnocují. Pokud chcete zaroutovat sezení znovu (například po změně parametrů sezení), lze použít aktivitu HandOff

Request:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "Forward",
  "operatorGroupId": <integer:optional if userId is set>,
  "userId": <integer:optional if operatorGroupId is set>
}

HandOff

Vrátí interakci zpět do routingu a vyhodnotí znovu parametry sezení. Po zavolání této aktivity je chatbot ze sezení odpojen. Doporučujeme tedy nejprve zjistit dostupnost cílových operátorů/skupin pomocí aktivit GetAvailableOperators / GetAvailableGroups.

Výsledek operace HandOff závisí na stavu skupiny:

  • ONLINE - sezení se přiřadí operátorovi

  • BUSY - sezení půjde do fronty skupiny

  • OFFLINE - klientovi se zobrazí offline formulář

Je nutné nastavit routingové podmínky tak, aby nedošlo ke zpětnému zaroutovaní zpět na chatbota.

Příklad správného použití:

Routingová pravidla:

Pořadové čísloCílPodmínka

1

Skupina "Sales"

HandoffReason = Sales

2

Skupina "Reklamace"

HandoffReason = Reklamace

3

Chatbot

bez podmínky

4

Fallback - vypnutý

-

Při prvním naroutování je vybrán chatbot, protože parametr HandoffReason ještě není nastaven. Chatbot by měl nastavit tento parametr pomocí aktivity SetCallParams, než vrátí sezení do routingu. Tím je zajištěno, že sezení nebude naroutováno zpět na chatbota.

Request:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "HandOff"
}

EndConversation

Ukončí sezení.

Request:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "EndConversation",
}

Typing

Zobrazí/skryje informaci zda chatbot má "rozepsanou" zprávu.

Request:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "typing",
  "show": true
}

DisableGuestInput

Zakáže uživateli psát do chatu.

Request:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "DisableGuestInput"
}

Odpověď aktivity:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "GuestInputChangeResponse",
  "success": <bool>,
  "language": <string>,
  "source": <string>
}

EnableGuestInput

Povolí uživateli psát do chatu.

Request:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "EnableGuestInput"
}

Odpověď aktivity:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "GuestInputChangeResponse",
  "success": <bool>,
  "language": <string>,
  "source": <string>
}

GetHeroCards

Vrátí existující Hero Cards.

Request:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "GetHeroCards"
}

Response:

{
  "activity": "GetHeroCardsResponse",
  "heroCards": [
    {
        "displayName":"Hero Card one",
        "heroCardId":1
    },
    {
        "displayName":"Hero Card two",
        "heroCardId":2
    }
  ]
}
GetHeroCardsResponse vrací pouze Hero karty, které je možné poslat ve stávajícím sezení

SendHeroCard

Posílá vybraný hero Card do chatu klienta. Pro nastavení předvyplněných hodnot v hero kartě je možné využít objekt initialParams.

Příklady:

  1. Pokud chci poslat hero kartu ve které mám definované textové pole, které ukládá hodnotu do proměnné "call_param_fullname", initialParams bude vypadat následovně:

initialParams: {
  "call_param_fullname": "předvyplněná hodnota"
}

  1. Pokud chci poslat hero kartu s výběrem času 6.12.2021 od 14:00 do 14:30 a k 7.12.2021 od 8:00 do 9:00, která ukládá hodnotu do proměnné "call_param_time_picker, initialParams bude vypadat následovně:

initialParams: {
  "call_param_time_picker": "[
    { \"startTime\": \"2021-12-06T14:00\", \"endTime\": \"2021-12-06T14:30\"}, 
    { \"startTime\": \"2021-12-07T08:00\", \"endTime\": \"2021-12-07T09:00\"}
  ]"
}

  1. Pokud chci poslat WhatsApp hero kartu s parametry, použiji proměnnou additionalParams, která má nasledující formát:

"additionalParams": {"header": [], "buttons": [], "footer": [], "body": ["a", "b", "c", "d", "e"]}

názvy header, buttons, footer a body neměním, měním pouze hodnoty v poli. POkud daná sekce nemá žádné parametry, pošlu prázdnou array.

Request JSON:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "SendHeroCard",
  "heroCardId": <integer:required>,
  "selectedLanguage": <string: optional>,
  "initialParams": <dictionary<string, string>: nepovinný>,
  "additionalParams": <dictionary<string,string[]>: nepovinný>
}
selectedLanguage parametr je ve formátu "cs", "en", "de" apod.

Response Activity:

{
  "activity": "SendHeroCardResponse",
  "success": <boolean>,
  "errorMessage": <string>
}

Chatbot donedávna nebyl schopný zjistit, že došlo k potvrzení Hero Card klientem a byl odkázaný na to sledat změnu parametru sezení. To již není nutné, protože informaci o potvrzení je možné získat přes webhook.

HeroCardSubmission

Informace pro chatbota, že klient potvrdil Hero Card nebo či vybral některou z možností (platí pro WhatsApp).

{
  "activity": "HeroCardSubmission",
  "params": {
    "oo1_guest_ident": "Test"
  },
  "sessionId": 23647,
  "language": "cs",
  "source": "Default"
}

ChatbotOpenFileUploadPrompt

Otevře dialog, který umožní uživateli nahrát soubor.

Request JSON:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "ChatbotOpenFileUploadPrompt"
}

Odpověď aktivity:

{
  "activity": "ChatbotOpenFileUploadPromptResponse",
  "fileUrl": <string | null>, (URL souboru nahraného uživatelem)
  "canceledByGuest": <boolean> (true, pokud uživatel zrušil prompt pro nahrání)
}

EnableGuestUpload

Povolit funkce, které umožňují nahrávání uživatelských souborů.

Request JSON:

{
  "activity": "EnableGuestUpload"
}

Odpověď aktivity:

{
  "activity": "EnableGuestUploadResponse",
  "success": <boolean>,
  "errorMessage": <string>
}

DisableGuestUpload

Zakázat funkce, které umožňují nahrávání uživatelských souborů.

Request JSON:

{
  "activity": "DisableGuestUpload"
}

Odpověď aktivity:

{
  "activity": "DisableGuestUploadResponse",
  "success": <boolean>,
  "errorMessage": <string>
}

GetMediaObjects

Vrátí seznam souborů, které jsou uložené v mluvii a dostupné pro dané sezení.

Request JSON:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "GetMediaObjects"
}

Odpověď aktivity:

{
  "activity": "GetMediaObjectsResponse",
  "fileStoreItems": [
    {
      "id": <integer>,
      "name": <string>
    }
  ],
  "sessionId": <integer>,
  "language": <string>,
  "source": <string>
}

ShareFile

Odešle soubor do chatu. Lze provést dvěma způsoby:

ShareFile (name)

Kombinace GetMediaObjects, což slouží k získání seznamu všech souborů uložených v Souborech (name + id). V druhém kroku použijete v rámci aktivity ShareFile name konkrétního souboru.

Příklad: Request JSON s použitím name:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "ShareFile",
  "name": <string získaný pomocí GetMediaObjects>
}

ShareFile (URL)

Volání aktivity ShareFile s URL souboru hostovaného mimo mluvii.

Příklad: Request JSON s použitím url:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "ShareFile",
  "url": <string>
}

Odpověď aktivity:

{
  "activity": "ShareFileResponse",
  "isSuccess": <boolean>,
  "errorMessage": <string>,
  "fileSource": "<string>",
  "sessionId": <integer>,
  "language": <string>,
  "source": <string>

Pokud chcete zasílat do chatu URL na Youtube video, použijte typ "message" a URL vkládejte do "textu".

Přehled povolených souborů pro daný kanál

Na úrovni společnosti se dají omezit povolené soubory - tato tabulka z ní vychází a upřesňuje, které soubory jsou pro který kanál funkční. Například poslání a přehrání mp3 souboru funguje pro WhatsApp sezení, ale nikoliv pro Facebook.

File typeWebChatFacebook MessengerWhatsAppApple Messages for BusinessVKontakte

WAV

✔

✘

✘

✔

✔

MP3

✔

✘

✔

✔

✔

MP4

✔

✘

✔

✔

✔

JPG

✔

✔

✔

✔

✔

PNG

✔

✔

✔

✔

✔

GIF

✔

✔

✔

✔

✔

PDF

✔

✔

✔

✔

✔

TXT

✔

✔

✔

✔

✔

Adaptive cards

Api podporuje formátování zpráv podle standardu https://adaptivecards.io.

Příklad použití adaptive card carousel:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "type": "message",
  "timestamp": "2020-06-12T12:13:39.7593384+02:00",
  "attachmentLayout": "carousel",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.hero",
      "content": {
        "title": "Street #1",
        "subtitle": "1. Street Foo 254 Czechia",
        "images": [
          {
            "url": "https://dev.virtualearth.net/REST/V1/Imagery/Map/Road?form=BTCTRL&mapArea=49.7463607788086,13.1083498001099,49.7932815551758,13.1951398849487&mapSize=500,280&pp=49.7616882324219,13.1491804122925;1;1&dpi=1&logo=always&key=ApBn8xoItlENbFx-rr1kzt_JakWdFTH24taCasYxQCgit15NtDeYrztO4chDtrg5"
          }
        ],
        "buttons": [
          {
            "type": "imBack",
            "title": "Street Foo 254",
            "value": 1
          }
        ]
      }
    },
    {
      "contentType": "application/vnd.microsoft.card.hero",
      "content": {
        "title": "Street #2",
        "subtitle": "1. Ulice, Plzeň, Czechia",
        "images": [
          {
            "url": "https://dev.virtualearth.net/REST/V1/Imagery/Map/Road?form=BTCTRL&mapArea=49.7463607788086,13.1083498001099,49.7932815551758,13.1951398849487&mapSize=500,280&pp=49.7616882324219,13.1491804122925;1;1&dpi=1&logo=always&key=ApBn8xoItlENbFx-rr1kzt_JakWdFTH24taCasYxQCgit15NtDeYrztO4chDtrg5"
          }
        ],
        "buttons": [
          {
            "type": "imBack",
            "title": "Ulice, Plzeň, Czechia",
            "value": 1
          }
        ]
      }
    },
    {
      "contentType": "application/vnd.microsoft.card.hero",
      "content": {
        "title": "Street #2 again",
        "subtitle": "1. Ulice, Plzeň, Czechia",
        "images": [
          {
            "url": "https://dev.virtualearth.net/REST/V1/Imagery/Map/Road?form=BTCTRL&mapArea=49.7463607788086,13.1083498001099,49.7932815551758,13.1951398849487&mapSize=500,280&pp=49.7616882324219,13.1491804122925;1;1&dpi=1&logo=always&key=ApBn8xoItlENbFx-rr1kzt_JakWdFTH24taCasYxQCgit15NtDeYrztO4chDtrg5"
          }
        ],
        "buttons": [
          {
            "type": "imBack",
            "title": "Ulice, Plzeň, Czechia",
            "value": 1
          }
        ]
      }
    }
  ]
}

Buttons

Tlačítka lze poslat pomocí adaptive cards.

Request JSON:

{
  "type": "message",
  "timestamp": "2020-09-09T10:03:53.4976861+02:00",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.hero",
      "content": {
        "title": "Test buttons",
        "buttons": [
          {
            "type": "imBack",
            "title": "Title of first button",
            "value": "Value of first button"
          },
          {
            "type": "imBack",
            "title": "Title of second button",
            "value": "Value of second button"
          }
        ]
      }
    }
  ]
}

Odpověď na vybrané tlačítko (Button 2) je pak aktivita typu Text v následujícím formátu:

{
  "activity": "Text",
  "timestamp": "2020-12-04T16:12:57.172",
  "text": "Button 2",
  "sessionId": 13,
  "language": "cs",
  "source": "Facebook"
}

Eventy

Příchozí zpráva

Jakmile klient odešle textovou zprávu do chatu, v Callback URL se zobrazí následující aktivita:

{
  "sessionId": 1,
  "activity": "Text",
  "text": "Hello world"
}

Příchozí soubor

Pokud klient nahraje soubor pomocí kancelářské sponky ve vstupním poli chatu, přijde botovi Aktivita v následujícím formátu.

{
  "activity": "GuestFileUpload",
  "fileUrl": <string>, (file URL loaded by a guest)
}
PreviousUdálosti specifické pro Chatbot APINextNávody

Last updated