Voximplant. Blog

Audio conferencing

Audio Conference

Voximplant has one of the most advanced and flexible audio conferencing implementations you can find. Developers have full control of every call connected to the conference via VoxEngine. For example, it’s possible to record particular сonference calls or the entire conference; developers can record only one audio stream that goes to the conference (if you need to get the audio from particular participant). It’s possible to play audio file (or TTS) into the conference or to a particular participant (call connected to the conference), mute/unmute participants, and even join different conferences together. Our Web SDK allows developers create web applications for the conference in minutes, same with Mobile SDKs. It’s possible to implement convenient conference controls using messaging functionality (inside the call). In addition, SIP software and devices can be connected to the conference. It’s hard to imagine audio conferencing service you can’t build using Voximplant.

Overview

There are two types of conferences that can be created, let’s call them Local and Standalone. The main difference between them is in the type of calls that can be connected to the conference.

Local conference exists only inside one VoxEngine JavaScript session. It means you can make some call (session will be created together with the call) then create conference mixer inside the session and connect additional outbound calls (up to 49 calls per session) initiated from the session to the conference mixer. You won’t be able to connect new incoming calls to Local conference, since normal JavaScript session can have only one incoming call. It’s useful for scenarios when you need to add additional participants on-the-fly during the call via outgoing calls (for example, for call whisper in a contact center).

Standalone conference also exists inside its own VoxEngine JavaScript session, so you have full control of the conference on VoxEngine level, but it extends number of simultaneous calls up to 100 and you can forward incoming calls to that special “conference session” (of course, you can make outbound calls from the same session and join them to the conference like with Local conference). The conference JavaScript session is started via callConference from another JavaScript session (the call between normal and conference JavaScript sessions is internal and is not billed) or via the /StartConference HTTP API call (please note that sessions without incoming or outgoing calls are automatically terminated after 60 seconds).

This illustration highlights the difference between two types of conferences:
Conference Types

The Details

As you can see in the scheme there are two ways of starting the VoxEngine session with Local conference – by accepting an incoming call or by making StartScenarios request to HTTP API. To create the conference mixer object after the session started use the following code:

require(Modules.Conference);
var conf = VoxEngine.createConference();

Example for the conference that is created via the incoming call:

  1. require(Modules.Conference);
  2. var call, conf;
  3.  
  4. VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
  5. call = e.call;
  6. call.answer(); // answer on the call
  7. call.addEventListener(CallEvents.Connected, handleCallConnected);
  8. conf = VoxEngine.createConference(); // create conference mixer object
  9. });
  10.  
  11. function handleCallConnected(e) {
  12. // Connect media between call and conference (two-way audio)
  13. VoxEngine.sendMediaBetween(conf, e.call);
  14. }
  15.  
  16. // Make new call and connect it to the conference
  17. function addCallToConference() {
  18. var new_call = VoxEngine.callPSTN('somephonenumber');
  19. new_call.addEventListener(CallEvents.Connected, handleCallConnected);
  20. }
  21.  
  22. addCallToConference();

Example for the conference session that is created via the HTTP API request:

  1. require(Modules.Conference);
  2. var call1, call2, conf;
  3.  
  4. // We are assuming that session started with HTTP API request
  5. VoxEngine.addEventListener(AppEvents.Started, function(e) {
  6. // create conference
  7. conf = VoxEngine.createConference();
  8. // call 2 phone numbers and join them to the conference
  9. // (you can make up to 50 calls for the Local conference)
  10. call1 = VoxEngine.callPSTN('number1');
  11. call2 = VoxEngine.callPSTN('number2');
  12. call1.addEventListener(CallEvents.Connected, handleCallConnected);
  13. call2.addEventListener(CallEvents.Connected, handleCallConnected);
  14. });
  15.  
  16. function handleCallConnected(e) {
  17. // Connect media between call and conference (two-way audio)
  18. VoxEngine.sendMediaBetween(conf, e.call);
  19. }

Developers have full control of all calls in the conference. For example, if we need to mute one of the participants use

call.stopMediaTo(conf);

If we want to play some audio file to the participant:

call.startPlayback("http://somewebservice/file.mp3");

If we need to play audio to all the participants we need something like that:

  1. require(Modules.Player);
  2. var player = VoxEngine.createURLPlayer("http://somewebservice/file.mp3");
  3. player.sendMediaTo(conf);
  4. player.addEventListener(PlayerEvents.PlaybackFinished, function(e) {
  5. // check e.error to see if something went wrong
  6. });

Record a conference (or particular calls):

  1. require(Modules.Recorder);
  2. var recorder = VoxEngine.createRecorder();
  3. conf.sendMediaTo(recorder);
  4. // you can stop recording using recorder.stop();

Standalone conference is created either by the StartConference request to HTTP API  or by forwarding call to the conference using VoxEngine.callConference. In both cases the conference will be created in a new session where all calls can be processed on VoxEngine JavaScript scenario level. We need to create two scenarios for the conference – Conference Gatekeeper (to forward calls to the conference) and Conference Manager (where inbound calls from the gatekeeper can be processed and connected to the conference, and where outbound calls can be initiated and connected to the conference). In addition to the scenarios we will need to create appropriate Voximplant application rules that will be used to launch required scenarios.

Conference Gatekeeper example:

  1. // Handle incoming call from PSTN/SIP/SDK
  2. VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
  3. /**
  4.   * conferenceId will be used in the application rule to forward the call
  5.   * to Conference Manager scenario
  6.   */
  7. var conf_call = VoxEngine.callConference('conferenceId');
  8. VoxEngine.easyProcess(e.call, conf_call);
  9. });

We havet to forward an incoming call to our conference. In order for Voximplant to know which JavaScript scenario is associated with which conference id it’s required to create a rule in the Voximplant control panel applications. The rule must has a conference name as a pattern and to be associated with conference JavaScript scenario.

Conference Manager scenario example:

  1. require(Modules.Conference);
  2. require(Modules.Player);
  3. var conf = null, calls = []; // remember incoming calls to manage them
  4.  
  5. // Handle incoming call from the gatekeeper
  6. VoxEngine.addEventListener(AppEvents.CallAlerting, function (e) {
  7. // create conference if it hasn't been created yet
  8. if (conf == null) {
  9. conf = VoxEngine.createConference();
  10. }
  11. // we can store all calls in array to control them
  12. calls.push(e.call);
  13. e.call.answer();
  14. e.call.addEventListener(CallEvents.Connected, handleCallConnected);
  15. e.call.addEventListener(CallEvents.Disconnected, handleCallDisconnected);
  16. });
  17.  
  18. function handleCallConnected(e) {
  19. // Notify the conference about new participant
  20. var player = VoxEngine.createTTSPlayer("New participant has joined the conference.");
  21. player.sendMediaTo(conf);
  22. player.addEventListener(PlayerEvents.PlaybackFinished, function (e) {
  23. // Start sending audio between the call and the conference
  24. VoxEngine.sendMediaBetween(e.call, conf);
  25. });
  26. }
  27.  
  28. function handleCallDisconnected(e) {
  29. // Let the conference know that one of the participants has left the conference
  30. var player = VoxEngine.createTTSPlayer("Participant has left the conference.");
  31. player.sendMediaTo(conf);
  32. }

This scenarios can be modified according to developer needs. For example, to create and join outbound call to the conference remotely, we could use media_session_access_url and make a call to the existing conference session:

  1. VoxEngine.addEventListener(AppEvents.HttpRequest, function (e) {
  2. // we can pass number in the request path if required
  3. // var number = getNumberFromPath(e.path);
  4. var new_call = VoxEngine.callPSTN('number');
  5. new_call.addEventListener(CallEvents.Connected, function (e) {
  6. VoxEngine.sendMediaBetween(e.call, conf);
  7. });
  8. });

It’s easy to add different conferencing features – write some JS code to add access code and passcode check, authorization by Caller ID, or web management interface. Check our GitHub page to get ready-to-use audio conferencing service scenarios and interfaces https://github.com/voximplant/conference

Comments