Advanced Conferencing Overview

Advanced Conferencing

All About Conferencing

Conferences are how two or more calls are bridged together to share audio. A conference of two calls behaves like a regular two-party phone call. A conference with more than two calls can be anything from a small conference call to a massive townhall meeting. It is in these larger scenarios that advanced conference controls are necessary to facilitate clear communication.

It is convenient to conceptualize conferences as real-world rooms that two or more people can enter and talk with each other. That metaphor can fail, however, when conferences and calls become more complex. For example, on our platform it is possible for one call to be in multiple conferences. Since a person cannot be in two rooms at the same time, this breaks the metaphor. Perhaps think of “joining a conference” as opening a door to an adjacent room. If two or more people open doors to the same room, they can all talk with each other. If a person opens a second door to a different room, he can now talk with both rooms, but the rooms are not connected. An example of this is in our Whisper docs.

Finally, this “open room door” metaphor works better because calls do not enter conferences, leave conferences, get pulled into conferences, etc. Calls do not travel about. The are simply bridged together, like opening a door.

Basic Conferences

All conferences are the same. The differences between a basic and advanced conference is only conceptual. If you do not need any fancy conference features, basic conferences will come with less surprises.

The following is the most basic conference action to put a call into a conference:

{
  "type": "CONFERENCE",
  "params": {
    "name": "my-conference"
  }
}

If the conference does not exist, it will be created on-demand and the call will be joined. Other calls can join. The conference will be garbage collected when the last call leaves. However, as far as the developer is concerned, conferences might as well be “always on”.

Conferences are differentiated by name.

The following can be considered Advanced Conference features. In pratice, basic and advanced conferences are interchangable.

Max Participants

The max_participants parameter enforces the number of participants that can join a conference. If a call attempts to join a full conference, it will be rejected. The developer has the option to handle this event.

The parameter max_participants does not last for the life of the conference. It is simply a check at that moment for that one call. This allows for tiered entry. For example, you can fill up a conference with 100 listeners with max_participants=”100″ but let moderators enter any time with max_participants=”110″.

OnJoin and OnExit Behavior

The following boolean paramters determine the onJoin and onExit behavior of conferences:

hold_on_exit will cause all participants to be placed on hold when a specified participant leaves a conference, provided it was set to true when joining.

end_on_exit will cause all participants to leave the conference when a specified participant leaves a conference, provided it was set to true when joining.

hold_on_join will cause all participants to be put on hold upon joining the conference. Participants can be taken off hold with…

start_on_join will cause an on hold or ended conference to start.

Tip: When using these behaviors, sometimes it’s easier to not reuse conference names. When possible, use a new name.

The following diagram illustrates how hold_on_join, start_on_join, hold_on_exit and end_on_exit affect conference participants:

Explanation: Call 1 initiates the conference with HoldOnJoin, causing subsequent calls to also enter on hold. Call 3 joins with StartOnJoin, releasing all other calls from hold. Call 3 also entered with HoldOnExit. Should Call 3 unexpectedly leave, all calls are placed on hold. Upon return, Call 3 starts the conference again. At the planned conclusion of the conference, you may wish to force all to leave the conference when Call 3 leaves. Simply execute another Join Conference with EndOnExit (yes, even though Call 3 is still in the conference). This will override the initial HoldOnExit setting. Now, when Call 3 leaves, all other calls are forced to leave and new attempts to join are blocked.

The next diagram illustrates how hold_on_join and end_on_exit affect conference participants:

Explanation: While similar to the previous diagram, this diagram differs in that Call 3 joins the conference with EndOnExit. As expected, when Call 3 exits, all calls are forced to exit and subsequent join attempts are blocked. To restart the conference, a call must join with StartOnJoin (or HoldOnJoin). This will allow join attempts to succeed.

Conference Events

The following events are optional and accept arrays of Actions.

on_enter will execute every time a call joins a conference.

on_enter_started will execute when a conference is in-progress.

on_enter_waiting will execute when a conference is on-hold.

on_enter_error will execute every time a call is rejected from joining.

on_enter_error_max_participants will execute when a call is rejected due to failing the max_participants check.

on_enter_error_ended will execute when a call attempts to join a conference that ended with a end_on_exit behavior.

Asynchronous Join Conference

By default, the Join Conference action will block the call flow execution. Only when the call leaves will the call flow continue executing. By setting async to true, the call will join the conference and the call flow will continue executing actions while the call is in the conference.

This allows the possibility of some exciting behaviors for a conferenced call. For example, PAUSE for 30 seconds, PLAY a message and repeat. This is also one way to put a call into multiple conferences.

To block later on in the call flow, simply join the call into the same conference with async set to false.

Joining Multiple Conferences

It is possible for a call to be in more than one conference. “What maddness is this?” you ask. With a combination of conferences and muting, it is possible to achieve some exciting behavior. For an example, check out out Whisper docs. Whisper allows two calls to talk while a third is only heard by one. A use case would be a supervisor listening in on a call and “whispering” to his agent for coaching with the customer none the wiser.

Early Media

Early media is the ability for two agents to communicate before a call is actually connected. To allow one call can hear another call’s ringing or busy signal, we use conferences.

To hear a connecting call’s early media, it must be placed in the same conference as the current call. To do this, simply make the Join Conference action the first thing in the callback response. Any other action will block until a connection is made.

Call Whisper

Join Conference to Whisper

Whisper allows a call to talk with one call in a conference while hearing all other calls. A simple example is, when calls A and B are talking, call C can hear calls A and B but only be heard by call A.

Let’s look at a sales-type use case. A sales rep is talking to a client with a supervisor listening. The supervisor could coach the sales rep without the client hearing.

How Whisper Works

While the use case of Whisper is simple, it is a good idea to understand how Voxology implements it so you can better control calls to achieve advanced features. Below is a diagram to illustrate the implementation.

In the left-side diagram, calls 1 and 2 are in a conference named ‘myConf’. Both calls can speak into the conference and hear what is said. Basically, a regular phone call. Call 3 is standing by, unable to hear or speak into the conference.

In the right-side diagram, call 3 has joined the conference ‘myConf’ on mute so she can hear the conversation. Call 3 would like to talk only to call 2 (the target), so a second conference is created with call 2 and 3 joining. However, call 2 is muted to avoid an echo, since call 3 can already hear from ‘myConf’. Note the naming convention of the second conference: ‘789@2::whisper-conf’. It is the target call’s ID plus ‘::whisper-conf’. Understanding this will allow you to manipulate calls in more advanced ways than what our convenience API methods allow.

To allow call 3 to speak to both calls 1 and 2, call 3 must be muted in ‘789@2::whisper-conf’ conference and unmuted in ‘myConf’ conference. The keypress commands for mute and unmute are wired opposite so that this can be achieved easily.

If you’d like to get daring, try having multiple calls whisper to one call.