Supported activities and events
Check required format for chatbot api
Common activities across channels:
- Text
- GetAvailableOperators
- GetAvailableGroups
- GetCallParams
- SetCallParams
- SendGuestOfflineEmail
- GetGuestIdentity
- Forward
- EndConversation
Specific activities for the mluvii chat:
- Typing
- DisableGuestInput
- EnableGuestInput
- GetHeroCards
- SendHeroCard
- ChatbotOpenFileUploadPrompt
- EnableGuestUpload
- DisableGuestUpload
- Adaptive Cards
- Buttons
Specific activities for Facebook:
Events
Activities
Text
It sends a text message with a time stamp. Text formatting can be used for mluvii chat, Facebook and WhatsApp - since different channels use different types of formatting, we have introduced automatic conversion in our application and it is enough to always send html elemments. The following are allowed: strong, em and a.
Simple text message:
{
"sessionId": 1,
"type": "message",
"timestamp": "2020-09-09T10:03:53.4976861+02:00",
"text": "Sample text"
}
Formated text message:
{
"sessionId": 1,
"type": "message",
"timestamp": "2020-09-09T10:03:53.4976861+02:00",
"text": "<em>Italic part</em>, <strong>Bold part</strong>"
}
GetAvailableOperators
Acquires a list of registered operators. Returns only operators from the groups defined in routing, which meet the routing conditions.
Supported mluvii channels: chat, facebook, whatsapp
Request JSON:
{
"sessionId": 1,
"activity": "GetAvailableOperators"
}
Response:
{
"sessionId": 1,
"activity": "GetAvailableOperatorsResponse",
"availableOperators": [
{
"displayName":"Katka",
"userId":1
},
{
"displayName":"Tomáš",
"userId":2
}
]
}
GetAvailableGroups
Acquires a list of created groups. Returns only groups defined in routing, which meet the routing conditions.
Supported mluvii channels: chat, facebook, whatsapp
Request JSON:
{
"sessionId": 1,
"activity": "GetAvailableGroups"
}
Response:
{
"sesionId": 1,
"activity": "GetAvailableGroupsResponse",
"availableGroups": [
{
"displayName":"Group one",
"groupId":1
},
{
"displayName":"Group two",
"groupId":2
}
]
}
GetCallParams
Acquires CallParams associated with an active session.
Request JSON:
{
"sessionId": 1,
"activity": "GetCallParams"
}
Response:
{
"sessionId": 1,
"activity": "GetCallParamsResponse",
"callParams": <dictionary>
}
SetCallParams
Set CallParams to active session.
Request JSON:
{
"sessionId": 1,
"activity": "SetCallParams",
"callParams": <dictionary>
}
Response:
{
"sessinId": 1,
"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": 1,
"activity": "SendGuestOfflineEmail",
"subject": <string>,
"message": <string>,
"location": <string> (message source for resolution, e.g.: "Chatbot Mluviik")
}
GetGuestIdentity
Gets properties from customer identity.
Request JSON:
{
"sessionId": 1,
"activity": "GetGuestIdentity"
}
Response:
{
"sessionId": 1,
"activity": "GetGuestIdentityResponse",
"trackedGuestGuid": <Guid>, (uniq identifier from cookie)
"phoneCallerId": <string>, (phone number)
"facebookPSID": <string>, (facebook identifier)
"facebookPageId": <string>, (facebook page identifier)
"whatsAppContactId": <string>, (whatsapp identifier)
"vkContactId": <string>, (vk 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.
Request JSON:
{
"sessionId": 1,
"activity": "Forward",
"operatorGroupId": <integer:optional>,
"userId": <integer:optional>
}
EndConversation
It ends a session.
{
"sessionId": 1,
"activity": "EndConversation",
}
Typing
It displays/hides an "unfinished" from a chatbot.
Request JSON:
{
"sessionId": 1,
"activity": "typing",
"show": true
}
DisableGuestInput
It forbids typing into the chat.
Request JSON:
{
"sessionId": 1,
"activity": "DisableGuestInput",
}
EnableGuestInput
It allows typing into a chat for user.
Request JSON:
{
"sessionId": 1,
"activity": "EnableGuestInput",
}
GetHeroCards
Returns available Hero cards.
Supported mluvii channels: chat
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.
Supported mluvii channels: chat
Request JSON:
{
"sessionId": 1,
"activity": "ChatbotOpenFileUploadPrompt"
}
Response:
{
"activity": "ChatbotOpenFileUploadPromptResponse",
"fileUrl": <string>, (file URL uploaded by guest)
}
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": 1,
"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. Úlice, 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": "Úlice, Plzeň, Czechia",
"value": 1
}
]
}
},
{
"contentType": "application/vnd.microsoft.card.hero",
"content": {
"title": "Street #2 again",
"subtitle": "1. Úlice, 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": "Úlice, 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)
}