Supported activities and events

Common activities across channels:

  1. GetAvailableOperators
  2. GetAvailableGroups
  3. GetCallParams
  4. SetCallParams
  5. GetHeroCards
  6. SendGuestOfflineEmail
  7. GetGuestIdentity
  8. EndConversation
  9. Forward
  10. Handoff

Specific activities for some channels:

Not all of these activities work on all channels. For example, Facebook only supports some activities. Whatsapp only supports basic text.

Activity Mluvii chat Facebook WhatsApp
Adaptive Cards ✔ ✔ ✘
Buttons ✔ ✔ ✘
Typing ✔ ✘ ✘
DisableGuestInput ✔ ✘ ✘
EnableGuestInput ✔ ✘ ✘
GetHeroCards ✔ ✘ ✘
SendHeroCard ✔ ✘ ✘
ChatbotOpenFileUploadPrompt ✔ ✘ ✘
EnableGuestUpload ✔ ✘ ✘
DisableGuestUpload ✔ ✘ ✘

Activities

The way how to send an activity varies depending on the type of chatbot:

GetAvailableOperators

This gets a list of operators that are logged in and available. If the groupId parameter is set, a list of available operators from the selected group is returned. Otherwise (groupId isn't set), the routing conditions are re-evaluated and only a list of available operators from the groups that meet the conditions is returned. It is therefore possible to change the session parameters and get a list of available operators according to the current parameters.

Request JSON:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "GetAvailableOperators",
  "groupId: <Group id is optional>
}

Response:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "GetAvailableOperatorsResponse",
  "availableOperators": [
    {
        "displayName":"Katka",
        "userId":1
    },
    {
        "displayName":"Tomáš",
        "userId":2
    }
  ]
}

GetAvailableGroups

This gets a list of operator groups and their current status. If the groupIds field is defined, a list of groups according to this field is returned. Otherwise, the routing conditions are re-evaluated and a list of groups that meet the conditions is returned. It is therefore possible to change the session parameters and get a list of available operators according to the current parameters.

Group status can have these values:

  • ONLINE - a group has available operators
  • BUSY - all operators are busy but the group queue is not full
  • OFFLINE - group queue is full

In addition when group is offline, the groupOfflineReasons array is populated with following values:

  • BUSINESS_HOURS - group is outside configured business hours
  • NO_OPERATORS - there are logged in operators in the group
  • QUEUE_FULL - group has reached maximum configured queue size
  • DELETED - group was deleted by an administrator
  • CHANNEL_BLOCKED - all operators have blocked the given channel

Request JSON:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "GetAvailableGroups",
  "groupIds: <optional field>
}

Response:

{
  "sesionId": <mandatory for API chatbot only>,
  "activity": "GetAvailableGroupsResponse",
  "availableGroups": [
    {
        "displayName":"Group one",
        "groupId": int,
        "groupState": one of: ONLINE, OFFLINE, BUSY,
        "groupOfflineReasons": [zero or more of: BUSINESS_HOURS, NO_OPERATORS, QUEUE_FULL, DELETED, CHANNEL_BLOCKED],
        "groupWorkload": {
          "maxSlots": int,
          "usedSlotsWaiting": int,
          "usedSlotsAccepted": int,
          "freeSlots": int
        }
    }
  ]
}

GetCallParams

Acquires CallParams associated with an active session.

Request JSON:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "GetCallParams"
}

Response:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "GetCallParamsResponse",
  "callParams": <dictionary>
}

SetCallParams

Set CallParams to active session.

Request JSON:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "SetCallParams",
  "callParams": <dictionary>
}

Response:

{
  "sessinId": <mandatory for API chatbot only>,
  "activity": "SetCallParamsResponse",
  "success": <boolean>,
  "errorMessage": <string>
}

SendGuestOfflineEmail

Sends an email to an address for messages from an offline form. The offline form has to be set on a widget level.

Request JSON:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "SendGuestOfflineEmail",
  "subject": <string>,
  "message": <string>,
  "location": <string> (message source for distinction, e.g.: "Chatbot Mluviik")
}

GetGuestIdentity

Gets properties from customer identity.

Request JSON:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "GetGuestIdentity"
}

Response:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "GetGuestIdentityResponse",
  "trackedGuestGuid": <Guid>, (unique identifier from cookie)
  "phoneCallerId": <string>, (phone number)
  "facebookPSID": <string>, (facebook identifier)
  "facebookPageId": <string>, (facebook page identifier)
  "whatsAppContactId": <string>, (whatsapp identifier)
  "vkContactId": <string>, (vk identifier)
  "AppleContactId": <string>, (apple identifier)
}

Forward

Redirects interaction for a live operator. If neither the target operator nor the group is defined, the group is automatically selected according to the settings of routing rules. Routing parameters are not re-evaluated.

If you want to route the session again (for example after changing the session parameters), you can use the HandOff activity.

Request JSON:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "Forward",
  "operatorGroupId": <integer:optional>,
  "userId": <integer:optional>
}

HandOff

This returns the interaction back to routing and re-evaluates the session parameters. After calling this activity, the chatbot is disconnected from the session. Therefore, we recommend that you first determine the availability of target operators/groups using the GetAvailableOperators / GetAvailableGroups activities.

The result of the Handoff operation depends on the state of the group:

  • ONLINE - a session is asigned to operator
  • BUSY - a session goes to the group queue
  • OFFLINE - an offline form is displayd to a client

Important: It is necessary to set the routing conditions in order to avoid routing back to the chatbot.

Example of correct use:

Sequence Target Condition
1 Group "Sales" HandoffReason = Sales
2 Group "Complaint" HandoffReason = Complaint
3 Chatbot no condition
4 Fallback - turned off -

Firstly, the chatbot is selected on the first routing because the HandoffReason is not set yet. Chatbot should set this parameter usingthe SetCallParams activity before returning the session to routing. This ensures that the session is not routed back to the chatbot.

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "HandOff"
}

EndConversation

It ends a session.

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "EndConversation",
}

Typing

It displays/hides an "unfinished" message from a chatbot.

Request JSON:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "typing",
  "show": true
}

DisableGuestInput

It forbids typing into the chat for a client.

Request JSON:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "DisableGuestInput",
}

EnableGuestInput

It allows typing into a chat for a client.

Request JSON:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "EnableGuestInput",
}

GetHeroCards

Returns available Hero cards.

Request JSON:

{
  "activity": "GetHeroCards"
}

Response:

{
  "activity": "GetHeroCardsResponse",
  "heroCards": [
    {
        "displayName":"Hero card one",
        "heroCardId":1
    },
    {
        "displayName":"Hero card two",
        "heroCardId":2
    }
  ]
}

SendHeroCard

Send selected hero card to client chat.

Request JSON:

{
  "activity": "SendHeroCard",
  "heroCardId": <integer:required>
}

Response:

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

ChatbotOpenFileUploadPrompt

Opens a dialog box to allow the user to upload the file.

Request JSON:

{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "ChatbotOpenFileUploadPrompt"
}

Response:

{
  "activity": "ChatbotOpenFileUploadPromptResponse",
  "fileUrl": <string | null>, (file URL uploaded by guest),
  "canceledByGuest": <boolean> (true, if guest canceled file upload prompt)
}

EnableGuestUpload

Enable functions that allow user file upload.

Request JSON:

{
  "activity": "EnableGuestUpload"
}

Response:

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

DisableGuestUpload

Disable functions that allow user file upload.

Request JSON:

{
  "activity": "DisableGuestUpload"
}

Response:

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

Adaptive cards

Our API supports https://adaptivecards.io standard for message formating.

Example of carousel adaptive card:

{
  "sessionId": <mandatory for API chatbot only>,
  "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

Buttons can be sent using 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 the first button",
            "value": "Value of the first button"
          },
          {
            "type": "imBack",
            "title": "Title of the second button",
            "value": "Value of the second button"
          }
        ]
      }
    }
  ]
}

The response to the selected button (Button 2) is then a Text activity in the following format:

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

Events

Incoming Message

When a guest sends a text message to a chat, the following activity comes at the callback url:

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

Incoming File

If a guest uploads the file using a paper clip in the chat input, the following Activity comes to a bot in the following format.

{
  "activity": "GuestFileUpload",
  "fileUrl": <string>, (file URL loaded by a guest)
}

results matching ""

    No results matching ""