User events

Alan AI emits several types of events driven by users’ interactions with the AI assistant. You can listen to these events with the onUserEvent callback and perform the activities needed for your assistant logic.

Note

The user statistics is updated after the user dialog session is closed.

Types of events

You can use the following events in your dialog script:

Web

Event name	Description
buttonClicked	Fired when the user clicks the AI assistant button in the app
buttonReady	Fired when Alan AI connects to the virtual assistant project and is ready to listen to the user’s input
firstActivate	Fired when the user activates the AI assistant for the first time during the dialog session
firstClick	Fired when the user clicks the AI assistant button for the first time during the dialog session
micAllowed	Fired when the user allows access to the microphone
micPermissionPrompt	Fired when a prompt to allow access to the microphone is displayed
popupCloseClicked	Fired when the user clicks the close icon in the Alan AI button popup
recognized	Fired during and upon the user’s input recognition
showPopup	Fired when a popup next to the AI assistant button is displayed

In the example below, the AI assistant listens to the firstActivate event and, if the last interaction with the user occurred earlier than one day ago, plays a greeting to the user.

Dialog script

function diffFrom(ts, units) {
    let last = DateTime.fromMillis(ts);
    let now  = DateTime.local();
    console.log(`now.diff(last): ${now.diff(last)}`);
    console.log(`units: ${units}, now.diff(last).as(units): ${now.diff(last).as(units)}`);
    return now.diff(last).as(units);
}

onUserEvent((p, e) => {
    console.info('event', JSON.stringify(e));
    if (e.event == 'firstActivate') {
        if (diffFrom(e.userInfo.lastInteractionTs, 'days') > 1) {
            p.play('(Hi|Hi there|Hello), I am Alan, your AI assistant. Ask any question or tell me what you would like to do');
        }
    }
});

buttonClicked event

Fired when the user clicks the AI assistant button in the app.

Event object

{
    "event": "buttonClicked",
    "micAllowed": false,
    "ts": 1666259901446,
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 1666255324364,
        "lastConnectTs": 1666259897357
    }
}

Field name	Data type	Description
event	String	Event name: buttonClicked
micAllowed	Boolean	Access to microphone during the dialog session: allowed (true) or denied (false)
ts	Integer	Timestamp of when the AI assistant button was clicked
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

buttonReady event

Fired when Alan AI connects to the AI assistant project and is ready to listen to the user’s input.

Event object

{
    "event": "buttonReady",
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 0,
        "lastConnectTs": 1666259897357
    }
}

Field name	Data type	Description
event	String	Event name: buttonReady
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

firstActivate event

Fired when the user activates the AI assistant for the first time during the dialog session.

Event object

{
    "event": "firstActivate",
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 1666255324364,
        "lastConnectTs": 1666259138126
    }
}

Field name	Data type	Description
event	String	Event name: firstActivate
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

firstClick event

Fired when the user clicks the AI assistant button for the first time during the dialog session.

Event object

{
    "event": "firstClick",
    "ts": 1666259398408,
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 1666255324364,
        "lastConnectTs": 1666259395336
    }
}

Field name	Data type	Description
event	String	Event name: firstClick
ts	Integer	Timestamp of when the AI assistant button was clicked for the first time
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

micAllowed event

Fired when the user allows access to the microphone.

Event object

{
    "event": "micAllowed",
    "ts": 1666259399772,
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 1666255324364,
        "lastConnectTs": 1666259395336
    }
}

Field name	Data type	Description
event	String	Event name: micAllowed
ts	Integer	Timestamp of when the microphone access was allowed
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

micPermissionPrompt event

Fired when a prompt to allow access to the microphone is displayed.

Event object

{
    "event": "micPermissionPrompt",
    "ts": 1666259901443,
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 1666255324364,
        "lastConnectTs": 1666259897357
    }
}

Field name	Data type	Description
event	String	Event name: micPermissionPrompt
ts	Integer	Timestamp of when the prompt was displayed
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

recognized event

Fired during and upon the user’s input recognition. The event description contains an interim or final result for the interpreted user’s phrase and the recognition state in the final field:

• If the user’s input is still being recognized, the final field value is false.

• If the user’s input has been recognized, the final field value is true.

Event object

{
    "event": "recognized",
    "final": false,
    "text": "hello",
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 1666255324364,
        "lastConnectTs": 1666257658614
    }
}

Field name	Data type	Description
event	String	Event name: recognized
final	Boolean	User’s input recognition state: final (true) or interim (false)
text	String	Interim or final result for the interpreted user’s input
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

popupCloseClicked event

Fired when the user clicks the close icon in the popup displayed next to the AI assistant button. For details, see Alan AI button popups.

Event object

{
    "event": "popupCloseClicked",
    "ts": 1666259141166,
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 1666255324364,
        "lastConnectTs": 1666259138126
    }
}

Field name	Data type	Description
event	String	Event name: popupCloseClicked
ts	Integer	Timestamp of when the close icon was clicked
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

showPopup event

Fired when a popup next to the AI assistant button is displayed. For details, see Alan button popups.

Event object

{
    "event": "showPopup",
    "ts": 1666259141166,
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 1666255324364,
        "lastConnectTs": 1666259138126
    }
}

Field name	Data type	Description
event	String	Event name: showPopup
ts	Integer	Timestamp of when the popup was displayed
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

iOS/Android

Event name	Description
buttonReady	Fired when Alan AI connects to the virtual assistant project and is ready to listen to the user’s input
firstClick	Fired when the user clicks the AI assistant button for the first time during the dialog session
micAllowed	Fired when the user allows access to the microphone
micPermissionPrompt	Fired when a prompt to allow access to the microphone is displayed
recognized	Fired during and upon the user’s input recognition

In the example below, the AI assistant listens to the firstClick event and, if the last interaction with the user occurred earlier than one day ago, plays a greeting to the user.

Dialog script

function diffFrom(ts, units) {
    let last = DateTime.fromMillis(ts);
    let now  = DateTime.local();
    console.log(`now.diff(last): ${now.diff(last)}`);
    console.log(`units: ${units}, now.diff(last).as(units): ${now.diff(last).as(units)}`);
    return now.diff(last).as(units);
}

onUserEvent((p, e) => {
    console.info('event', JSON.stringify(e));
    if (e.event == 'firstClick') {
        if (diffFrom(e.userInfo.lastInteractionTs, 'days') > 1) {
            p.play('(Hi|Hi there|Hello), I am Alan, your AI assistant. Ask any question or tell me what you would like to do');
       }
    }
});

buttonReady event

Fired when Alan AI connects to the AI assistant project and is ready to listen to the user’s input.

Event object

{
    "event": "buttonReady",
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 0,
        "lastConnectTs": 1666259897357
    }
}

Field name	Data type	Description
event	String	Event name: buttonReady
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

firstClick event

Fired when the user clicks the AI assistant button for the first time during the dialog session.

Event object

{
    "event": "firstClick",
    "ts": 1666259398408,
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 1666255324364,
        "lastConnectTs": 1666259395336
    }
}

Field name	Data type	Description
event	String	Event name: firstClick
ts	Integer	Timestamp of when the AI assistant button was clicked for the first time
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

micAllowed event

Fired when the user allows access to the microphone.

Event object

{
    "event": "micAllowed",
    "ts": 1666259399772,
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 1666255324364,
        "lastConnectTs": 1666259395336
    }
}

Field name	Data type	Description
event	String	Event name: micAllowed
ts	Integer	Timestamp of when the microphone access was allowed
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

micPermissionPrompt event

Fired when a prompt to allow access to the microphone is displayed.

Event object

{
    "event": "micPermissionPrompt",
    "ts": 1666259901443,
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 1666255324364,
        "lastConnectTs": 1666259897357
    }
}

Field name	Data type	Description
event	String	Event name: micPermissionPrompt
ts	Integer	Timestamp of when the prompt was displayed
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant

recognized event

Fired during and upon the user’s input recognition. The event description contains an interim or final result for the interpreted user’s phrase and the recognition state in the final field:

• If the user’s input is still being recognized, the final field value is false.

• If the user’s input has been recognized, the final field value is true.

Event object

{
    "event": "recognized",
    "final": false,
    "text": "hello",
    "userInfo": {
        "interactions": 25,
        "recognized": 25,
        "unrecognized": 0,
        "lastInteractionTs": 1666255324364,
        "lastConnectTs": 1666257658614
    }
}

Field name	Data type	Description
event	String	Event name: recognized
final	Boolean	User’s input recognition state: final (true) or interim (false)
text	String	Interim or final result for the interpreted user’s input
interactions	Integer	Number of interactions with the user
recognized	Integer	Number of recognized user’s interactions
unrecognized	Integer	Number of unrecognized user’s interactions
lastInteractionTs	Integer	Timestamp of the last interaction with the AI assistant
lastConnectTs	Integer	Timestamp of the last connection to the AI assistant