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

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.

Activity

WebChat

Facebook

Apple

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é číslo

Cíl

Podmínka

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
}

Použijte "true" pro zapnutí a "false" pro vypnutí typingu.

DisableGuestInput

Skryje chatové pole a neumožní 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

Zobrazí chatové pole a umožní tak 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í seznam existujících HeroCards.

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á vybranou HeroCard do chatu klienta. Pro nastavení předvyplněných hodnot v HeroCard je možné využít objekt initialParams.

HeroCard s předvyplněnou hodnotou parametru

Pokud chci poslat HeroCard, ve které je použito 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"
}

"Běžnou" HeroCard je možné použít v rámci kanálů Webchat, WhatsApp a Apple.

HeroCard s výběrem času

Pokud chci poslat hero kartu s výběrem časů (termínů) 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\"}
  ]"
}

Tuto HeroCard je možné použít v rámci Webchat a WhatsApp kanálů.

WhatsApp HeroCard (Template Message)

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 (v hlavičce, tlačítek, v zápatí a těle) Template Message jsou dané, měníte pouze hodnoty v poli. Pokud daná sekce nemá žádné parametry, pošlete 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 použijte 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 HeroCard nebo 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>
}

ObtainCrmIdentity

Vrací seznam existujících záznamů z Adresáře Kontaktů, u kterých je nalezena alespoň minimální shoda v identifikačních údajích klienta v daném sezení (např. klientovo jméno, tel. číslo, e-mail, ...).

Chování je identické jako v případě sezení se živým operátorem, který dostává informace o nalezených shodách s existujícími záznamy v Adresáři Kontaktů.

Request JSON:

{
        "activity": "ObtainCrmIdentity",
        "sessionId": 7418277
}

Odpověď aktivity:

{
  "activity": "ObtainCrmIdentityResponse",
  "assignedCrmIdentityId": null,
  "matchedCrmIdentities": [
    {
      "crmIdentityId": 9943973,
      "score": 95,
      "data": {
        "oo1_guest_facebook_psid": [
          "1901491179944737",
          "2075406945856826"
        ],
        "oo1_guest_guid": [
          "09ac8a24-b342-14e5-f1cd-6cdf50c5a25e"
        ],
        "oo1_guest_email": [
          "marek.maly@gmail.com",
          "marek48@gmail.com",
          "malymarek@gmail.com",
          "maly@mluvii.com"
        ],
        "CrmUrl": [
          "https://org39940337.crm4.dynamics.com/main.aspx?app=d365default&forceUCI=1&pagetype=entityrecord&etn=contact&id="
        ],
        "oo1_guest_phone": [
          "+420258963147"
        ]
      }
    },
    {
      "crmIdentityId": 8527408,
      "score": 64,
      "data": {
        "oo1_guest_facebook_psid": [
          "1901491179944737"
        ],
        "oo1_guest_guid": [
          "8cc011e1-3889-9e58-2dba-07bc824ffbb3"
        ],
        "oo1_guest_email": [
          "karelsdfdfserwer"
        ],
        "oo1_guest_phone": [
          "16567879778"
        ]
      }
    }
}

Často se může stát, že výsledků API vrátí více a bude na vás, podle jakého klíče označíte nejrelevantnější záznam, který chatbot vybere pro přiřazení klientské identity. Jako vodítko můžete použít parametr "score".

AssignCrmIdentity

Používá se pro přiřazení klientské identity k existujícímu či novému záznamu v Adresáři kontaků. Typicky tento request zavoláte na základě výsledku ObtainCrmIdentity.

Request JSON:

{
        "activity": "AssignCrmIdentity",
        "existingCrmIdentityId": 9943973,
        "sessionId": 7418277
}

Odpověď activity:

{
  "activity": "AssignCrmIdentityResponse",
  "created": false,
  "crmIdentityId": 9943973,
  "sessionId": 7417841,
  "language": "en",
  "source": "Default"
}

Jestliže v odpovědi na activitu ObtainCrmIdentity dostanete záznamy s určitou shodou, použijete v requestu hodnotu parametru "crmIdentityID". Pokud žádné shody nejsou nalezeny, jako hodnotu parametru "crmIdentityId" použijete "null".

V odpovědi activity si můžete všimnout parametru "created", který nabývá hodnot "true" při vytváření nového záznamu a hodnoty "false" při napárování na existující záznam v Adresáři Kontaktů.

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 type

WebChat

Facebook Messenger

Apple Messages for Business

VKontakte

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 API NextNávody

Last updated 6 months ago