User events

Alan emits several types of events driven by users’ interactions with the in-app 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 voice script:

Event name

Description

buttonClicked

Fired when the user clicks the in-app assistant button in the app

buttonReady

Fired when Alan connects to the voice project and is ready to listen to the user’s input

firstActivate

Fired when the user activates the in-app assistant for the first time during the dialog session

firstClick

Fired when the user clicks the in-app 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 button popup

recognized

Fired during and upon the user’s input recognition

showPopup

Fired when a popup next to the Alan button is displayed

In the example below, the in-app 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.

Voice 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 in-app assistant. Ask any question or tell me what you would like to do');
        }
    }
});

buttonClicked event

Fired when the user clicks the in-app 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 in-app 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app assistant

buttonReady event

Fired when Alan connects to the voice 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app assistant

firstActivate event

Fired when the user activates the in-app 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app assistant

firstClick event

Fired when the user clicks the in-app 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 in-app 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app assistant

Fired when the user clicks the close icon in the popup displayed next to the Alan button. For details, see Alan 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app assistant

showPopup event

Fired when a popup next to the Alan 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app assistant

Event name

Description

buttonReady

Fired when Alan connects to the voice project and is ready to listen to the user’s input

firstClick

Fired when the user clicks the in-app 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 in-app 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.

Voice 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 in-app assistant. Ask any question or tell me what you would like to do');
       }
    }
});

buttonReady event

Fired when Alan connects to the voice 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app assistant

firstClick event

Fired when the user clicks the in-app 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 in-app 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app 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 in-app assistant

lastConnectTs

Integer

Timestamp of the last connection to the in-app assistant