Skip to main content

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

EventDescription
matchThe user request was recognized by the classifier, but the bot couldn’t reach any script state by the intent with the highest score.
noMatchThe 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

EventDescription
lengthLimitThe limit on the user request length was exceeded.
timeLimitThe 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

EventDescription
sessionDataSoftLimitExceededA soft limit on the amount of data stored in $session was reached.
sessionDataHardLimitExceededA hard limit on the amount of data stored in $session was reached.
clientDataSoftLimitExceededA soft limit on the amount of data stored in $client was reached.
clientDataHardLimitExceededA hard limit on the amount of data stored in $client was reached.

SMS events

EventDescription
smsSuccessEventAn SMS message was sent successfully.
smsFailedEventAn SMS message failed to be sent.

Account events

EventDescription
tariffBlockedThe JAICP account was suspended.

Inbound channel events

EventDescription
fileEventThe user sent a file to the bot.
fileTooBigEventThe 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

EventDescription
CRM_SUCCESS_EVENTBitrix24 CRM event was updated.
CRM_FAILED_EVENTBitrix24 CRM event was not updated.
ONAPPINSTALLAn application was installed.
ONAPPUPDATEAn application was updated.
ONIMBOTMESSAGEADDThe bot received a message.
ONIMBOTMESSAGEUPDATEThe bot updated the message.
ONIMBOTMESSAGEDELETEThe bot deleted the message.
ONIMCOMMANDADDThe bot received a command.
ONIMJOINCHATThe bot was notified that it was added to a chat.
ONIMBOTDELETEThe bot was deleted.

edna WhatsApp 2.0

EventDescription
locationEventThe user sent a location.

Microsoft Teams

EventDescription
acceptFileThe user agreed to accept a file.
declineFileThe user refused to accept a file.

Telegram

EventDescription
stickerEventThe user sent a sticker.
telegramSendContactThe user sent a contact.
telegramSendLocationThe user sent a location.
telegramApiRequestFailedThe file sent by the user failed to be received.
telegramCallbackQueryThe user selected an inline button with the callback_data parameter. Its value is available as $request.rawRequest.callback_query.data.
telegramPaymentSuccessEventThe user made a successful payment.
telegramPaymentFailedEventThe payment failed, or an error occurred because the payment form parameters were filled incorrectly.
telegramPrecheckoutEventTelegram 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

EventDescription
viberSendLocationThe user sent a location.
viberSendStickerThe user sent a sticker.
viberSendContactThe user sent a contact.
viberUnsubscribeThe user unsubscribed from the bot. The bot cannot send new messages.
conversationStartedThe 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

EventDescription
weChatSendLocationThe user sent a location.
weChatAnyMessageThe type of the user message failed to be recognized.

Customer engagement platform events

EventDescription
livechatFinishedThe agent finished the chat with the user.
noLivechatOperatorsOnlineAll agents are offline.

Telephony events

EventDescription
speechNotRecognizedThe bot failed to recognize the customer’s speech after 5 seconds.
hangupThe customer ended the call.
botHangupThe bot ended the call via the $dialer.hangUp method.
transferThe call was transferred to an agent.
noDtmfAnswerEventThe customer failed to enter a DTMF message in tone dialing mode.
onCallNotConnectedThe bot failed to reach the customer.
bargeInIntentThe customer made a conditional barge-in attempt.