Events

There are two ways to interact with bots supported by JAICP 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 JAICP 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 JAICP 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.

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.

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

Bitrix24

Event	Description
`CRM_SUCCESS_EVENT`	Bitrix24 CRM event was updated.
`CRM_FAILED_EVENT`	Bitrix24 CRM event was not updated.
`ONAPPINSTALL`	An application was installed.
`ONAPPUPDATE`	An application was updated.
`ONIMBOTMESSAGEADD`	The bot received a message.
`ONIMBOTMESSAGEUPDATE`	The bot updated the message.
`ONIMBOTMESSAGEDELETE`	The bot deleted the message.
`ONIMCOMMANDADD`	The bot received a command.
`ONIMJOINCHAT`	The bot was notified that it was added to a chat.
`ONIMBOTDELETE`	The bot was deleted.

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.

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.
`speechInvalid`	The bot failed to synthesise speech or to play an audio file. Use to handle synthesis and playback errors.

Event types​

System events​

Custom events​

How to use​

System events reference​

NLU events​

Request limit events​

$session and $client overflow events​

SMS events​

Account events​

Inbound channel events​

Bitrix24​

edna WhatsApp 2.0​

Microsoft Teams​

Telegram​

Viber​

Vonage​

WeChat​

Customer engagement platform events​

Telephony events​