Rate this page:

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.

Event-based model

Copy URL

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 });
    });
});
What is concidered an inbound call?

Please note, that if you are making a call via web or mobile SDK, it consists of two call legs: SDK → scenario and scenario → destination. In this case, the SDK → scenario call leg is considered an inbound call in the scenario, so you need to process it via the CallAlerting event as well. Read the How to process calls in a scenario article to learn more about processing inbound and outbound calls in scenarios.

See Available Roles

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.

Session lifecycle

Copy URL

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.

  • A session always starts with the Started event due to an inbound call or an HTTP request.

  • The next event depends on what started a session: it can be the CallAlerting event in case of a call or the HttpRequest event in case of an HTTP request.

  • The CallEvents can be triggered during a session: when a call is connected or when it is put on hold, when call recording is started, and so on.

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.
Timeout

A session without calls and ACD requests is terminated after 60 seconds.

See Available Roles

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

Standard library

Copy URL

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.

Logging

Copy URL

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:

Logs

Key features

  • Copying a log itself or the link to it to the clipboard

  • Downloading logs in the .txt format – see the button in the the top right corner

  • Events and their time codes are highlighted for readability

  • Navigating through long logs with the help of a minimap in the top right corner

  • Hiding any of a call's sides (legs) for more convenient analysis – unfold the needed leg the left side of the screen and uncheck the Highlight call lines box there.

Legs