VoxEngine concepts

Voximplant has a JS-based core called VoxEngine which processes applications based on JS scenarios.

VoxEngine uses the ECMAScript 6 standard JavaScript and based on the SpiderMonkey engine, that is also used in the Firefox 81 web browser. Hence, it supports all the features that this engine supports.

We recommend sticking to the ECMAScript 6 standard when writing your scenarios, and if you want to use some of the newer features, check if this feature is compatible with Firefox 81 via the Can I use website.

You can use our Cloud IDE for working with VoxEngine scenarios, or you can use your 3rd-party IDE solution. Working with 3rd-party IDEs has its advantages and disadvantages. For example, you can create scenarios with the help of technologies such as TypeScript and Webpack. However, these instruments can be configured incorrectly, resulting in not human-readable code, which makes it impossible for developers to work with their code, and for the Voximplant support team to troubleshoot and debug your applications.

This is why we recommend using VoxEngine CI when developing your scenario in a 3rd-party IDE.

Our scenarios use the 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 incoming 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 incoming 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 incoming call object and its events are not available. For outgoing 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 been 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 session 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 them to make your scenario work properly.

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

When a session terminates, its log immediately 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 get access to a handful of visual representation:

Key features