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

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.

{
  "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

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

$session and $client overflow events

SMS events

Account events

Inbound channel events

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

Bitrix24

edna WhatsApp 2.0

Microsoft Teams

Telegram

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

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

Customer engagement platform events

Telephony events