Events

There are two ways to interact with bots supported by Tovie Platform scripts:

• Queries — text or voice messages that users send to bots. They get processed by the natural language understanding (NLU) engine, then the bot switches to the appropriate state and executes its reactions.
• Events — actions that happen in the bot script, the Tovie Platform account, or a channel connected to the project. Event processing skips the NLU stage. If the bot can reach the state where an event is expected, it switches to this state immediately and executes the reactions.

Events can originate from any kind of source, for example:

• When the user sends a file to the chat, the channel will fire an event indicating that a file was received.
• The NLU engine itself generates an event when it can’t recognize the query.
• A third-party service can use an event to notify the bot of a successful user login.

Event types

System events

System events are available in all Tovie Platform scripts by default. You can learn more about the available events in the system events reference.

Custom events

Developers can implement their scripts in a way that allows processing events with arbitrary names. Such events are typically used to integrate bots into third-party services, such as chat applications or CRM systems.

• If the bot is connected to the Chat API channel, a third-party service can send a custom event to the chat via the /chatapi/{token} and /chatapi/{token}/async methods.
• The $pushgate built-in service enables the script to create scheduled events as well as pushbacks — special entities for processing events using the Pushgate API.
• Custom events can also be used in the script so that the bot is triggered when text campaigns are launched.

How to use

To set up an event by which the dialog can switch to a state, use the global event! tag or the local event tag. Supply the event name after the tag.

state: NoMatch
    event!: noMatch
    a: I’m sorry, I didn’t get that. Try saying your question differently.

    state: InnerNoMatch
        event: noMatch
        a: I’m afraid I didn’t understand you this time either. I’m patching you through to an agent.

Some events can have a body containing a data payload. You can reference it in the state triggered by an event as one of the following properties of the $request object:

• $request.data.eventData
• $request.rawRequest.eventData

tip

The actual data depends on the event type. For instance, the stickerEvent data contains the sticker metadata: its dimensions, presence of animation, the corresponding emoji, and other information.

Example value of $request.data.eventData

{
  "file_id": "CAACAgIAAxkBAAIEEmHxVulVK5-ctf22Mes9jGXRBVTdAAIdFwACKyEFAAHPqSzw8fRaOyME",
  "file_unique_id": "AgADHRcAAishBQAB",
  "width": 512,
  "height": 512,
  "is_animated": false,
  "thumb": {
    "file_id": "AAMCAgADGQEAAgQSYfFW6VUrn5y1_bYx6z2MZdEFVN0AAh0XAAIrIQUAAc-pLPDx9Fo7AQAHbQADIwQ",
    "file_unique_id": "AQADHRcAAishBQABcg",
    "width": 128,
    "height": 128,
    "file_size": 2436
  },
  "emoji": "😭",
  "set_name": "madl4bor",
  "file_size": 30934
}

System events reference

NLU events

Event	Description
match	The user request was recognized by the classifier, but the bot couldn’t reach any script state by the intent with the highest score.
noMatch	The classifier failed to recognize an intent or pattern in the user request with a high enough level of confidence.

tip

NLU events are only relevant for the second version of the bot engine. The first version has no match event, and the q!: * pattern is used instead of event!: noMatch.

Request limit events

Event	Description
lengthLimit	The limit on the user request length was exceeded.
timeLimit	The limit on the request processing time was exceeded.
nluSystemLimit	One of the system limits was exceeded: The limit on the number of phrase elements after tokenization. The limit on the number of recognized entities in a phrase. The limit on memory usage during pattern recognition. This event cannot be configured in the chatbot.yaml configuration file, but you can track it in the script.

$session and $client overflow events

Event	Description
sessionDataSoftLimitExceeded	A soft limit on the amount of data stored in $session was reached.
sessionDataHardLimitExceeded	A hard limit on the amount of data stored in $session was reached.
clientDataSoftLimitExceeded	A soft limit on the amount of data stored in $client was reached.
clientDataHardLimitExceeded	A hard limit on the amount of data stored in $client was reached.

SMS events

Event	Description
smsSuccessEvent	An SMS message was sent successfully.
smsFailedEvent	An SMS message failed to be sent.

Account events

Event	Description
tariffBlocked	The Tovie Platform account was suspended.

Inbound channel events

Event	Description
fileEvent	The user sent a file to the bot.
fileTooBigEvent	The user sent a file exceeding 50 MB in size.

tip

fileEvent and fileTooBigEvent are supported by all inbound channels except JivoChat, Zendesk, and Zendesk Chat. The chat widget only supports fileEvent.

edna WhatsApp 2.0

Event	Description
locationEvent	The user sent a location.

Microsoft Teams

Event	Description
acceptFile	The user agreed to accept a file.
declineFile	The user refused to accept a file.

Telegram

Event	Description
stickerEvent	The user sent a sticker.
telegramSendContact	The user sent a contact.
telegramSendLocation	The user sent a location.
telegramApiRequestFailed	The file sent by the user failed to be received.
telegramCallbackQuery	The user selected an inline button with the callback_data parameter. Its value is available as $request.rawRequest.callback_query.data.
telegramPaymentSuccessEvent	The user made a successful payment.
telegramPaymentFailedEvent	The payment failed, or an error occurred because the payment form parameters were filled incorrectly.
telegramPrecheckoutEvent	Telegram issued a goods availability check.

tip

telegramPaymentSuccessEvent, telegramPaymentFailedEvent, and telegramPrecheckoutEvent should only be handled if you set up payments via the telegramPayment reply type. If you use the TelegramPayment action tag instead, handling these events is already built into it.

Viber

Event	Description
viberSendLocation	The user sent a location.
viberSendSticker	The user sent a sticker.
viberSendContact	The user sent a contact.
viberUnsubscribe	The user unsubscribed from the bot. The bot cannot send new messages.
conversationStarted	The bot sent a greeting message before the session started.

caution

When using the conversationStarted event, there may be a discrepancy between the number of unique users displayed on the Account management page and the data the account manager has. Please contact your account manager for up-to-date information.

Vonage

When any non-text message is received in the Vonage WhatsApp channel, an event named after its type, such as event: audio, is sent to the script. All request data from the channel is sent as eventData.

WeChat

Event	Description
weChatSendLocation	The user sent a location.
weChatAnyMessage	The type of the user message failed to be recognized.

Customer engagement platform events

Event	Description
livechatFinished	The agent finished the chat with the user.
noLivechatOperatorsOnline	All agents are offline.

Telephony events

Event	Description
speechNotRecognized	The bot failed to recognize the customer’s speech after 5 seconds.
hangup	The customer ended the call.
botHangup	The bot ended the call via the $dialer.hangUp method.
transfer	The call was transferred to an agent.
noDtmfAnswerEvent	The customer failed to enter a DTMF message in tone dialing mode.
onCallNotConnected	The bot failed to reach the customer.
bargeInIntent	The customer made a conditional barge-in attempt.