API chatbot connection

Activities Webhook Event Reference

The mluvii application sends events to your webhook in order to notify your chatbot at the moment when a variety of interactions or events happen (e.g. when a person sends a message). Webhook events are sent by the mluvii application as POST requests to your webhook.

When an activity has been sent to your chatbot by chatbot mluvii session this callback will occur.

You can receive either text messages or messages with attachments. Main supported attachment types are image,text, audio, video, file. You can also get fallback attachments. A common example of a 'fallback' is when a user shares some URL with a Page. You can encounter a fallback with no payload which is sent in case of unsupported shares made by users to your chatbot.

You can subscribe to this callback by setting callback url in mluvii administration.

Webhook Performance Requirements

Your webhook should follow the minimum performance standards:

  • Respond to all webhook events with a 200 OK.
  • Respond to all webhook events in 2 seconds or less.

If your webhook fails to meet either of the above requirements and it lasts more than 15 minutes your chatbot will be unsubscribed from receiving webhook events and your chatbot will be also disabled in mluvii.

Validating Webhook Events

It’s highly recommended to use authorization for the callback URL. You can use an access token or basic authorization in a URL.

Example callback URL: https://www.example.com/api/access_token=8973Fsad7as87dgh8gh09f8gh8f7gs68sdf5g9dfs85g9df

Webhook Events

The available webhook events are listed below. All webhook events are optional, so select those that are most relevant for the experience you are trying to create

Webhook Event Popis
ping It’s reserved to verify service functionality. This type of event has to be implemented and its response should be 200 OK.
activity Activity sent from user, operator or system

Send API

The Send API is the main API used to send (deliver) messages to users. It covers text, attachments, structured message templates, sender actions, and more. Chatbot only respond to a conversation he has received and he is routed to it.

Performance Requirements

Your request should meet the following performance standards:

  • Max request in one session is 120 request or less in 1 minutes

Authentication

https://docs.mluvii.com/guide/en/for-it-specialists/rest-api.html

Api key needs chatbot claim.

Supported activities

  1. GetAvailableOperators (chat, facebook, whatsapp)
  2. GetAvailableGroups (chat, facebook, whatsapp)
  3. Forward (chat, facebook, whatsapp)
  4. GetCallParams (chat, facebook, whatsapp)
  5. SetCallParams (chat, facebook, whatsapp)
  6. SendGuestOfflineEmail (chat)
  7. ChatbotOpenFileUploadPrompt (chat)
  8. GetGuestIdentity (chat)
  9. EnableGuestUpload (chat)
  10. DisableGuestUpload (chat)
  11. Text (chat, facebook, whatsapp)

GetAvailableOperators

Acquires a list of registered operators. Returns only operators from the groups defined in routing, which meet the routing conditions.

Request JSON:

{
    "session": {
        "id": "849846561894946"
    },
    "activities": [
        {
            "Activity": "GetAvailableOperators"
        }
    ]
}

Activity:

{
   "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.

Request JSON:

{
    "session": {
        "id": "849846561894946"
    },
    "activities": [
        {
            "Activity": "GetAvailableGroups"
        }
    ]
}

Activity:

{
   "Activity": "GetAvailableGroupsResponse"
   "AvailableGroups":[
      {
         "DisplayName":"Group one",
         "GroupId":1
      },
      {
         "DisplayName":"Group two",
         "GroupId":2
      }
   ]
}

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

Request JSON:

{
    "session": {
        "id": "849846561894946"
    },
    "activities": [
        {
            "Activity": "Forward",
            "OperatorGroupId": <integer:optional>,
            "UserId": <integer:optional>
        }
    ]
}

GetCallParams

Acquires CallParams associated with an active session.

Request JSON:


{
    "session": {
        "id": "849846561894946"
    },
    "activities": [
        {
            "Activity": "GetCallParams"
        }
    ]
}

Activity:

{
    "Activity": "GetCallParamsResponse",
    "CallParams":<dictionary>
}

SetCallParams

Set CallParams to active session.

Request JSON:

{
    "session": {
        "id": "849846561894946"
    },
    "activities": [
        {
            "Activity": "SetCallParams",
            "CallParams":<dictionary>
        }
    ]
}

Activity:

{
   "Activity": "SetCallParamsResponse"
   "Success": <boolean>,
   "ErrorMessage": <string>
}

SendGuestOfflineEmail

Sends an email to an address for messages from an offline form.

Request JSON:

{
    "session": {
        "id": "849846561894946"
    },
    "activities": [
        {
            "Activity": "SendGuestOfflineEmail",
            "Subject":<string>,
            "Message":<string>,
            "Location":<string> (zdroj zprávy pro rozlišení, např: "Chatbot Mluviik")
        }
    ]
}

ChatbotOpenFileUploadPrompt

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

Request JSON:

{
    "session": {
        "id": "849846561894946"
    },
    "activities": [
        {
            "Activity": "ChatbotOpenFileUploadPrompt"
        }
    ]
}

Activity:

{
   "Activity": "ChatbotOpenFileUploadPromptResponse"
   "FileUrl": <string>, (URL souboru nahraného uživatelem)
}

GetGuestIdentity

Gets properties from customer identity.

Request JSON:

{
    "session": {
        "id": "849846561894946"
    },
    "activities": [
        {
            "Activity": "GetGuestIdentity"
        }
    ]
}

Activity:

{
   "Activity": "GetGuestIdentityResponse"
   "TrackedGuestGuid": <Guid>, (unikátní identifikátor z cookie)
   "PhoneCallerId": <string>, (telefonní číslo)
   "FacebookPSID": <string>, (facebook identifikátor )
   "FacebookPageId": <string>, (facebook identifikátor )
}

EnableGuestUpload

Enable functions that allow user file upload.

Request JSON:

{
    "session": {
        "id": "849846561894946"
    },
    "activities": [
        {
            "Activity": "EnableGuestUpload"
        }
    ]
}

Activity:

{
   "Activity": "EnableGuestUploadResponse",
   "Success": <boolean>,
   "ErrorMessage": <string>
}

DisableGuestUpload

Disable functions that allow user file upload.

Request JSON:

{
    "session": {
        "id": "849846561894946"
    },
    "activities": [
        {
            "Activity": "DisableGuestUpload"
        }
    ]
}

Activity:

{
   "Activity": "DisableGuestUploadResponse",
   "Success": <boolean>,
   "ErrorMessage": <string>
}

Text

Send text.

Request JSON:

{
    "session": {
        "id": "849846561894946"
    },
    "activities": [
        {
            "Activity": "Text",
            "Text": "Hello world",
      }
    ]
}

GuestFileUpload

If client loads file through pin in chat input, Activity in this format will be send to chatbot

Request JSON:

{
    "session": {
        "id": "849846561894946"
    },
    "activities": [
        {
            "Activity": "GuestFileUpload"
            "FileUrl": <string>, (URL of file loaded by user)
        }
    ]
}

results matching ""

    No results matching ""