VoxEngine concepts

Voximplant has a JS-based core called VoxEngine which processes calls on the basis of JS scenarios and works with the latest ECMAScript syntax.

Our scenarios use event-based approach, which means that developers can easily manage their application logic by subscribing to events and processing them.

Please notice, that some events are nested, which means, to subscribe to them, you first need to subscribe to the parent event. For example, to process the CallEvents, such as Connected or ToneReceived, first you need to subscribe to the parent CallAlerting event, which processes calls. After you subscribe to the CallAlerting event, you receive the Call object, which has its own events.

VoxEngine.addEventListener(AppEvents.CallAlerting, (e) => {
    // you receive the inbound call object in the e.call property
    // the call has its own events, such as "ToneReceived"

e.call.handleTones(true); // enable processing tone signals
    e.call.answer(); // answer the inbound call

//subscribe to the call's event
    e.call.addEventListener(CallEvents.ToneReceived, (e) => {
        e.call.say("You pushed the ${e.tone} button", {language: VoiceList.Amazon.en_US_Joanna});
    });

e.call.addEventListener(CallEvents.Disconnected, () => VoxEngine.terminate());
});

Without subscribing to the parent event, the inbound call object and its events are not available. For outbound calls from the scenario, you create the call object with its events via the call methods, for example:

VoxEngine.addEventListener(AppEvents.Started, () => {
    // create a new call when scenario starts
    const call = VoxEngine.callPSTN("numberToCall", "confirmedCallerId");
    // get the events from the newly created object
    call.addEventListener(CallEvents.Connected, () => {
        call.say("Wake up, Neo!", { language: VoiceList.Amazon.en_US_Joanna });
    });
});

Some events are consequent, which means that one event can only happen after a certain event has triggered. For example, the media player's PlaybackFinished event, which indicates that media player has finished playing media to the call, can only happen after the player's Started event, which indicates that the media player has started playing media to the call.

Every attempt to start a call using Voximplant creates a new independent call session in VoxEngine; except for conferences, in this case, the call goes into an existing session.

Normally, the session’s ending is executed in the next steps:

1. The terminate method is called, an error occurs, or a session ends after timeout if there are no active calls and ACD requests.
2. The Terminating event is triggered. Timers and any other external resources are not available after this event is triggered, but you can perform one HTTP request inside the event handler (e.g., to notify an external system about the fact that the session is finished). When that request is finished.
3. The Terminated event is triggered.

To learn about sessions limits, check out the Limits and restrictions article.

VoxEngine supports basic functions such as setTimeout, clearTimeout, str2Bytes, base64_encode, uuidgen, a set of crypto methods, etc. But they can be slightly different from their originals even in the names. Please look them up in the VoxEngine reference before using to make your scenario work properly.

Use the Logger.write method to write messages to the session logger.

When a session terminates, its log immeditately becomes available in Call history. To access it, you can either go to the Calls section in the Control panel or use the GetCallHistory API method. Retrieving logs via the Control panel, you gets access to a handful visual representation:

Key features