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 client 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	Description
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. See the following list of supported activities sent to the webhook.

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. If Default is specified as the source, it is WebChat. For a complete list, see Session Source.

{
  "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. Format of the API is available here.

Performance Requirements

Your request should meet the following performance standards:

• Max request in one session is 120 requests or less in one minute

Support messages according to the communication channel

Each communication channel has its own specifics. Here you can find a list of all supported activities. In the first list you will find activities that are common across all channels. In the second, those that are only for WebChat.

Good to know

Facebook

• 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 Facebook Messenger.

• Facebook supports the display of a maximum of 3 buttons.

General

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.

If you send a request, you will get an immediate response with status code 200 OK. If you are expecting a response, e.g. when sending GetAvailableGroups, you will also get an immediate answer 200 OK, but the actual result GetAvailableGroupsResponse will be sent to your webhook.

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