Ctrlk
Mluvii webLoginAPIDEMO
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API chatbot connection

Authentication

Requests sent by the chatbot via the API are authenticated using a bearer token. Each message from the bot is sent via an HTTP request with the header `Authorization: Bearer <token>`

There are two ways to obtain a token:

  1. Obtaining a bearer token using the OAuth2 endpoint (old method)

    • /login/connect/token

    • The `client_id` and `client_secret` are available in the chatbot settings

  2. Automatically generated token valid for a single session (recommended)

  • Every incoming activity to the webhook contains an `X-Session-Token` HTTP header containing the bearer token. The activity itself contains the `sessionId`

  • Every conversation always begins with the speaker sending a ChatbotConversationStarted event

  • The chatbot must maintain a map of active conversations: sessionId → token

  • When the chatbot wants to respond in a given session, it uses this token for authentication

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. The main supported attachment types are image, text, audio, video, and file. You can also get fallback attachments. A common example of a fallback is when a user shares a 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 a 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

Session start

Each session begins with an activity ConversationStarted. This may occur at the beginning of a session or during the session, immediately after the session is redirected to that chatbot. If Default is specified as the source, it is WebChat. For a complete list, see Session Source.

Session ending

When a conversation ends (end of session, or the chatbot forwards the conversation to someone else), a ConversationEnded activity is sent.

The chatbot implementation can, for example, delete temporary conversation data or terminate persistent actors (akka.net implementation) in response to this activity.

If you are interested in using it, feel free to ask.

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 requests 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

Next steps

Check supported activities and events

PreviousAPI endpoints
NextChatbot API-specific activities and events

Last updated

Was this helpful?