API chatbot connection

Authentication

Chatbot api calls need to be authenticated by the following steps. The api key must have chatbot permission set.

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=YOUR_ACCESS_TOKEN

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

Webhook payload from mluvii

Ping

{
  "activity": "Ping"
}

Activity

{
  "activity": "Text",
  "timestamp": "2020-09-09T10:03:46.792954",
  "text": "Hello world!",
  "sessionId": 2359788,
  "language": "en",
  "source": "Default"
}

Session start

Each session begins with an activity ConversationStarted

{
  "activity": "ConversationStarted",
  "timestamp": "2020-09-09T09:59:49.5640515+02:00",
  "sessionId": 2359753,
  "language": "en",
  "source": "Default"
}

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

Support messages according to the communication channel

Each communication channel has its own specifics, for example Facebook does not support the display of all functions, such as the web chat.

Activity Type Web Chat Facebook WhatsApp
Text Yes Yes Yes
Herocard (SendHeroCard) Yes Yes (partially) No
Adaptive Cards Yes No No
Audio Yes Yes Yes
Video (attachment) Yes Yes Yes
GetAvailableOperators Yes Yes Yes
GetAvailableGroups Yes Yes Yes
GetCallParams Yes Yes Yes
SetCallParams Yes Yes Yes
SendGuestOfflineEmail Yes No No
ChatbotOpenFileUploadPrompt Yes No No
EnableGuestUpload Yes No No
DisableGuestUpload Yes No No
GetGuestIdentity Yes Yes Yes
Forward Yes Yes Yes

Stricter rules must be followed for Facebook; all restrictions are available in the official documentation at https://developers.facebook.com/docs/messenger-platform/reference

In case the chatbot sends an invalid message that cannot be displayed, this message will not appear in the Facebook Messenger.

Good to know

Facebook supports the display of a maximum of 3 buttons.

Each button has a limited number of characters.

It is not possible to send buttons without a text in the title, subtitle, or text

Send activities

Every action between chatbot and mluvii session is called an activity. You need to know chatbotId to send activities. ChatbotId can be found in the url when editing a chatbot, e.g. ..../app/1/1/settings/chatbots/edit/166/general.

Each request should have the following format:

Request to /api/v1/Chatbot/{chatbotId}/activity

{
  "sessionId": "2359788",
  "type": "message",
  "text": "Sample text",
  "timestamp": "2020-09-09T10:03:53.4976861+02:00"
}

Next steps

Check supported activities and events

results matching ""

    No results matching ""