Podporované aktivity a události


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

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.

Aktivita WebChat Facebook WhatsApp Apple VKontakte
Adaptive Cards
Buttons
Typing
DisableGuestInput
EnableGuestInput
GetHeroCards
SendHeroCard
ChatbotOpenFileUploadPrompt
EnableGuestUpload
DisableGuestUpload
ShareFile (name)
ShareFile (url)

Aktivity

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

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 aktualní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 aktualní parametrů.

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

  • ONLINE - skupina ma 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

Vratí 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 aktualní vytížení operátorů pomocí aktivit GetAvailableOperators / GetAvailableGroups

Routingové parametry jsou znovu nevyhodnocují. Pokud chcete zaroutovat sezení znovu (napřiklad 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 sezeni. Po zavolání této aktivity je chatbot ze sezení odpojen. Doporučujeme tedy nejprve zjistit dostupnost cílových operatorů/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 formůlář

Důležité: Je nuté 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é číslo Cíl Podmínka
1 Skupina "Sales" HandoffReason = Sales
2 Skupina "Reklamace" HandoffReason = Reklamace
3 Chatbot bez podmínky
4 Fallback - vypnutý -

Při prvním naroutovaní je vybrán chatbot, protože parametr HandoffReason ještě není nastaven. Chatbot by měl nastavit tento parametr pomocí aktivity SetCallParams, než vratí 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
    }
  ]
}

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"
}

2) 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\"}
  ]"
}

Request JSON:

{
  "sessionId": <nutné pouze u chatbota přes API>,
  "activity": "SendHeroCard",
  "heroCardId": <integer:required>,
  "initialParams": <dictionary<string, string>: nepovinný>
}

Response Activity:

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

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 - buď v kombinaci s GetMediaObjects a použitím name, nebo pomocí url odkazu na daný soubor.

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.

Typ souboru WebChat Facebook WhatsApp Apple VKontakte
WAV
MP3
MP4
JPG
PNG
GIF
TXT

Příklady

Request JSON s použitím name:

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

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>

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

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"
}

results matching ""

    No results matching ""