Event-driven call processing

All scenarios are event based.

To make your application work, you will need to add event listeners for several events. Currently, events can be dispatched by 2 types of objects:

  1. VoxEngine: You can check the reference documentation for a complete list of events that can be dispatched by the VoxEngine object
  2. Call objects: A complete list of events dispatched by these objects is available here. Please note that each Call object has its own list of event listeners, so to handle the specific event of each call even with the same function, you will need to call the addEventListener function for each object

To explain further, let's examine the source code of the helper function we used in our Getting Started tutorial.

The application code looks like this:

VoxEngine.playSoundAndHangup("http://voximplant.com/hello.mp3");

Now let's take a look at the source of the playSoundAndHangup function:

  1. VoxEngine.playSoundAndHangup = function(fileURL)
  2. {
  3. VoxEngine.addEventListener(AppEvents.CallAlerting, function(e)
  4. {
  5. e.call.answer();
  6. e.call.addEventListener(CallEvents.Connected, function (e){
  7. e.call.startPlayback(fileURL);
  8. });
  9. e.call.addEventListener(CallEvents.Failed, function(e){
  10. VoxEngine.terminate();
  11. });
  12. e.call.addEventListener(CallEvents.Disconnected, function(e){
  13. VoxEngine.terminate();
  14. });
  15. e.call.addEventListener(CallEvents.PlaybackFinished, function(e){
  16. VoxEngine.terminate();
  17. });
  18. });
  19. }

First, we have this line:

VoxEngine.addEventListener(AppEvents.CallAlerting, function(e)

This code defines a callback that will be used when a new call arrives to the scenario. Since every new call made to VoxImplant creates a new call processing session, it may only be called once during a session's lifetime. When this callback is executed, it has a Call object associated with the incoming call, so we can add event listeners to it.

But first we want to answer the call:

e.call.answer();

Remember that all Call operations are asynchronous, so the executor will not dispatch events associated with this operation (like CallEvents.Connected) until the processing of the current event finishes.

After the call is established (we answered and a remote party confirmed it), we decide that we want to play audio to the caller:

  1. e.call.addEventListener(CallEvents.Connected, function (e){
  2. e.call.startPlayback(fileURL);
  3. });

Finally, we add handlers for following behavior. We want to terminate the call control session if:

  1. The incoming call fails before the remote party received the answer command
    1. e.call.addEventListener(CallEvents.Failed, function(e){
    2. VoxEngine.terminate();
    3. });
  2. The incoming call is ended by a remote party
    1. e.call.addEventListener(CallEvents.Disconnected, function(e){
    2. VoxEngine.terminate();
    3. });
  3. The playback of audio file finishes. This event is triggered if the playback finished with an error (for example, if the file format was invalid, or it couldn't be downloaded), so it's not necessary separate event handlers to handle a failure in playback.
    1. e.call.addEventListener(CallEvents.PlaybackFinished, function(e){
    2. VoxEngine.terminate();
    3. });

That's it!

If you would like to read more about specific events that can be dispatched by objects, check the VoxEngine Reference documentation.