# Supported activities and events

## Common activities across channels:

1. [GetAvailableOperators](#getavailableoperators)
2. [GetAvailableGroups](#getavailablegroups)
3. [GetCallParams](#getcallparams)
4. [SetCallParams](#setcallparams)
5. [GetHeroCards](#getherocards)
6. [SendGuestOfflineEmail](#sendguestofflineemail)
7. [GetGuestIdentity](#getguestidentity)
8. [EndConversation](#endconversation)
9. [Forward](#forward)
10. [Handoff](#handoff)
11. [GetMediaObjects](#getmediaobjects)
12. [ShareFile (name)](#sharefile-file-name)
13. [ObtainCrmIdentity](#obtaincrmidentity)
14. [AssignCrmIdentity](#assigncrmidentity)

## 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.

<table><thead><tr><th width="214">Activity</th><th width="107">WebChat</th><th width="109">Facebook</th><th>WhatsApp</th><th width="85">Apple</th><th width="116">VKontakte</th></tr></thead><tbody><tr><td><a href="#adaptive-cards">Adaptive Cards </a></td><td>✔</td><td>✔</td><td>✘</td><td>✘</td><td>✘</td></tr><tr><td><a href="#attachment">Attachment</a></td><td>✔</td><td>✘</td><td>✔</td><td>✘</td><td>✘</td></tr><tr><td><a href="#buttons">Buttons</a></td><td>✔</td><td>✔</td><td>✘</td><td>✘</td><td>✘</td></tr><tr><td><a href="#typing">Typing</a></td><td>✔</td><td>✘</td><td>✘</td><td>✔</td><td>✘</td></tr><tr><td><a href="#enableguestinput">EnableGuestInput</a></td><td>✔</td><td>✘</td><td>✘</td><td>✘</td><td>✘</td></tr><tr><td><a href="#disableguestinput">DisableGuestInput</a></td><td>✔</td><td>✘</td><td>✘</td><td>✘</td><td>✘</td></tr><tr><td><a href="#getherocards">GetHeroCards</a></td><td>✔</td><td>✘</td><td>✔</td><td>✔</td><td>✘</td></tr><tr><td><a href="#sendherocard">SendHeroCard</a></td><td>✔</td><td>✘</td><td>✔</td><td>✔</td><td>✘</td></tr><tr><td><a href="#herocardsubmission">HeroCardSubmission</a></td><td>✔</td><td>✘</td><td>✔</td><td>✔</td><td>✘</td></tr><tr><td><a href="#chatbotopenfileuploadprompt">ChatbotOpenFileUploadPrompt</a></td><td>✔</td><td>✘</td><td>✘</td><td>✘</td><td>✘</td></tr><tr><td><a href="#enableguestinput">EnableGuestUpload</a></td><td>✔</td><td>✘</td><td>✘</td><td>✘</td><td>✘</td></tr><tr><td><a href="#disableguestinput">DisableGuestUpload</a></td><td>✔</td><td>✘</td><td>✘</td><td>✘</td><td>✘</td></tr><tr><td><a href="#sharefile-url">ShareFile (url)</a></td><td>✔</td><td>✘</td><td>✘</td><td>✔</td><td>✔</td></tr><tr><td><a href="#requestlocation">RequestLocation</a></td><td>✔</td><td>✘</td><td>✘</td><td>✘</td><td>✘</td></tr></tbody></table>

*Facebook = Facebook Messenger*\
*Apple = Apple Messages for Business*

## Activities

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

* [Microsoft Bot Framework](https://dev.botframework.com/) sends activities by using [ChannelData](https://docs.microsoft.com/en-us/previous-versions/azure/bot-service/dotnet/bot-builder-dotnet-channeldata?view=azure-bot-service-3.0)
* API chatbot sends activities to the API endpoint `/api/v1/Chatbot/{chatbotId}/activity` see Send activities.

### GetAvailableOperators

This gets a list of operators that are logged in and available.&#x20;

If the `groupId` parameter is set, and a list of available operators from the selected group is returned.&#x20;

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:

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

Response:

```json
{
  "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.&#x20;

If the `groupIds` field is defined, and a list of groups according to this field is returned.&#x20;

Otherwise, the [routing conditions](/en/for-administrators/tenant-management/settings/routing.md) are re-evaluated and a list of groups that meet the conditions is returned. It is therefore possible to [change the session parameters](#setcallparams) 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 the following values:**

* BUSINESS\_HOURS - the group is outside configured business hours
* NO\_OPERATORS - there are logged-in operators in the group
* QUEUE\_FULL - the group has reached the maximum configured queue size
* DELETED - the group was deleted by an administrator
* CHANNEL\_BLOCKED - all operators have blocked the given channel

Request JSON:

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

Response:

**groupWorkload**

* maxSlots: Sum of all slots of logged operators in group
* usedSlotsWaiting: Sum of all waiting slots of logged operators in group
* usedSlotsAccepted: Sum of all accepted slots of logged operators in group
* freeSlots: Sum of free slots of logged operators in group

**queueWorkload**

* freeQueueSlotsCountTotal: Free queue slots of group
* inQueueCountTotal: Used queue slots of group
* isQueueFull: freeQueueSlotsCountTotal == 0

```json
{
  "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
        },
        "queueWorkload": {
          "freeQueueSlotsCountTotal": int,
          "inQueueCountTotal": int,
          "isQueueFull": boolean,
        }
    }
  ]
}
```

### GetCallParams

Acquires [CallParams](https://docs.mluvii.com/guide/pro-administratory/nastaveni/aplikace.html#prom%C4%9Bnn%C3%A9) associated with an active session.

Request JSON:

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

Response:

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

### SetCallParams

Set [CallParams](https://docs.mluvii.com/guide/pro-administratory/nastaveni/aplikace.html#prom%C4%9Bnn%C3%A9) to active session.

Request JSON:

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

Response:

```json
{
  "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:

```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 client identity.

Request JSON:

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

Response:

```json
{
  "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. Either `operatorGroupId` or `userId` must be set.

Forwarded sessions ignore configured capacity rules (group queue limit/operator slots. If this is not desirable either handle the capacity manually using [GetAvailableOperators](#getavailableoperators) / [GetAvailableGroups](#getavailablegroups) or use [HandOff](#handoff) activity instead.

Routing parameters are not re-evaluated. If you want to route the session again (for example after [changing the session parameters](#setcallparams)), you can use the HandOff activity.

Request JSON:

```json
{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "Forward",
  "operatorGroupId": <integer:optional if userId is set>,
  "userId": <integer:optional if operatorGroupId is set>
}
```

### HandOff

This returns the interaction 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](#getavailableoperators) / [GetAvailableGroups](#getavailablegroups) activities.

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

* ONLINE - a session is assigned to an operator
* BUSY - a session goes to the group queue
* OFFLINE - an offline form is displayed to a client

{% hint style="warning" %}
*It is necessary to set the routing conditions to avoid routing back to the chatbot.*
{% endhint %}

**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 using the [SetCallParams](#setcallparams) activity before returning the session to routing. This ensures that the session is not routed back to the chatbot.

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

### EndConversation

It ends a session.

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

### Typing

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

Request JSON:

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

### DisableGuestInput

Hides the input field and allows typing into the chat for a client.

Request JSON:

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

Response:

```json
{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "GuestInputChangeResponse",
  "success": <bool>,
  "language": <string>,
  "source": <string>
}
```

### EnableGuestInput

Displays the text input and allows typing into a chat for a client.

Request JSON:

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

Response:

```json
{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "GuestInputChangeResponse",
  "success": <bool>,
  "language": <string>,
  "source": <string>
}
```

### GetHeroCards

Returns available Hero cards.

Request JSON:

```json
{
  "activity": "GetHeroCards"
}
```

Response:

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

{% hint style="info" %}
*GetHeroCardsResponse returns HeroCards that can be used in the current session only.*
{% endhint %}

### SendHeroCard

Send selected hero card to client chat. To set predefined values in a HeroCard you can use object *initialParams*.&#x20;

#### Examples:

1. If you want to send a hero card with a text field that sets values in the call parameter "call\_param\_fullname", initialParams should look like the following:

```json
initialParams: {
  "call_param_fullname": "predefined value"
}
```

1. If you wish to send a hero card with a time picker ranging from 6th of December 2021 2:00 pm to 2:30 pm and from 7th of December 2021 8:00 am to 9:00 am and store the selected value to call parameter "call\_param\_time\_picker", initialParams should look like the following (using military time):

```json
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\"}
  ]"
}
```

2. If you want to send a WhatsApp HeroCard with params, additional params should look like this:

Note that you should not change the header, buttons, footer, and body names, just add or remove values in an array. If you don't have any parameters in section, send an empty array.&#x20;

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

Request JSON:

```json
{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "SendHeroCard",
  "heroCardId": <integer:required>,
  "selectedLanguage": <string: optional>
  "initialParams": <dictionary<string, string>: optional>,
  "additionalParams": <dictionary<string,string[]>: optional>
}
```

{% hint style="info" %}

```
selectedLanguage string should be in format "cs", "en", "de" etc.
```

{% endhint %}

Response:

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

{% hint style="success" %}
*Until recently, the chatbot was unable to detect that a Hero Card confirmation had occurred by the client and was reliant on tracking the session parameter change. This is no longer necessary as confirmation information can be obtained via webhook.*
{% endhint %}

### HeroCardSubmission

Information for the chatbot that the client has confirmed the Hero Card or selected one of the options (applies to WhatsApp).

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

### ChatbotOpenFileUploadPrompt

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

Request JSON:

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

Response:

```json
{
  "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:

```json
{
  "activity": "EnableGuestUpload"
}
```

Response:

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

### DisableGuestUpload

Disable functions that allow user file upload.

Request JSON:

```json
{
  "activity": "DisableGuestUpload"
}
```

Response:

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

### GetMediaObjects

Gets a list of files stored in mluvii and available for the given session.

Request JSON:

```json
{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "GetMediaObjects"
}
```

Response:

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

### ObtainCrmIdentity

Returns a list of existing records from the Contacts Directory for which at least a minimum match is found in the client's identification data in the given session (e.g. client's name, phone number, e-mail, ...).

{% hint style="info" %}
*The behavior is identical to that of a session with a live operator, which receives information about matches found with existing records in the Contacts Directory.*
{% endhint %}

Request JSON:

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

Response:

```json
{
  "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"
        ]
      }
    }
}    
```

{% hint style="success" %}
*Often, the API will return multiple results, and it will be up to you to select the most relevant record for the chatbot to assign a client identity. You can use the "score" parameter as a guide.*
{% endhint %}

### AssignCrmIdentity

It is used to assign a client identity to an existing or new entry in the Contact Directory. Typically, you call this request based on the ObtainCrmIdentity result.

Request JSON:

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

Response:

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

{% hint style="success" %}
*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".*
{% endhint %}

{% hint style="info" %}
*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ů.*
{% endhint %}

### ShareFile

Send a file to chat. It can be done in two ways:

#### ShareFile (name)

a) A combination of GetMediaObjects, which is used to get a list of all files stored in Files /name + id. In the second step, you use the *name* of the specific file within the ShareFile activity.

**Example:** Request JSON using *name* parameter:

```json
{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "ShareFile",
  "name": <string obtained via GetMediaObjects>
}
```

#### ShareFile (URL)

Using the ShareFile activity with the URL of the particular file hosted externally.

Request JSON using *URL* parameter:

```json
{
  "sessionId": <mandatory for API chatbot only>,
  "activity": "ShareFile",
  "url": <string>
}
```

Response:

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

{% hint style="info" %}
*If you want to send a YouTube video URL to the chat, use the "message" type and put the URL in "text".*
{% endhint %}

There are two ways of sending a file - either with [GetMediaObjects](#getmediaobjects) using a *name* or you can use a *URL* link to the specified file.

#### **Allowed file types**

You can whitelist file types on the company level - this overview specifies which files are working in which channel. For example, sending and playing MP3 files works for WhatsApp but not for Facebook sessions.

<table><thead><tr><th width="115">File type</th><th width="104">WebChat</th><th>Facebook Messenger</th><th width="114">WhatsApp</th><th width="150">Apple Messages for Business</th><th>VKontakte</th></tr></thead><tbody><tr><td>WAV</td><td>✔</td><td>✘</td><td>✘</td><td>✔</td><td>✔</td></tr><tr><td>MP3</td><td>✔</td><td>✘</td><td>✔</td><td>✔</td><td>✔</td></tr><tr><td>MP4</td><td>✔</td><td>✘</td><td>✔</td><td>✔</td><td>✔</td></tr><tr><td>JPG</td><td>✔</td><td>✔</td><td>✔</td><td>✔</td><td>✔</td></tr><tr><td>PNG</td><td>✔</td><td>✔</td><td>✔</td><td>✔</td><td>✔</td></tr><tr><td>GIF</td><td>✔</td><td>✔</td><td>✔</td><td>✔</td><td>✔</td></tr><tr><td>PDF</td><td>✔</td><td>✔</td><td>✔</td><td>✔</td><td>✔</td></tr><tr><td>TXT</td><td>✔</td><td>✔</td><td>✔</td><td>✔</td><td>✔</td></tr></tbody></table>

### RequestLocation

The chatbot requests the client's location via an internet browser and is able to obtain the location from both desktop and mobile devices.

Request JSON:

```
{
  "activity": "RequestLocation",
  "sessionId": <integer>
}
```

Response:

```
{
  "activity": "GuestLocation",
  "sessionId": <integer>
} 
```

### Adaptive cards

Our API supports <https://adaptivecards.io> standard for message formatting.

Example of a carousel adaptive card:

```json
{
  "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
          }
        ]
      }
    }
  ]
}
```

### Attachment

Sends a file to the chat (the file is not stored in Files, but is located, for example, on a local disk).

Request JSON:

```
{
        "activity": "Attachment",
        "file": <string>, (file URL loaded by a guest)
        "sessionId": 7418277
}
```

### Buttons

Buttons can be sent using [adaptive cards](https://adaptivecards.io/explorer).

Request JSON:

```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:

```json
{
  "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:

```json
{
  "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 the bot in the following format.

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mluvii.com/en/for-it-specialists/chatbot-connection/supported-activities-and-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.