Managing Conferences

[adamreed90]

Hello! I wasn't exactly clear how to manage conference members, I didn't find it exactly clear via the documentation.

Is it possible to create a conference with a primary member, then add and remove secondary members?

For example:
Start a conference
Add a member to the conference from a Dial Out
Remove that member from the conference, and add another new member via a dial out?

[cdosoftei]

Before delving into the posted questions, it should be noted the Conference concept is based on FreeSWITCH's mod_conference module. Eqivo provides programmatic access to Conferences via REST API calls as well as webhooks for event handling, acting as a higher level wrapper.

Conferences are referred by name (alphanumeric) whereas its members are referred by their ID (integer values).

Is it possible to create a conference with a primary member, then add and remove secondary members?

Indeed, that's actually a common scenario. The member classification (akin to primary vs secondary) can be a bit more granular, based on each member's attributes particularly startConferenceOnEnter, endConferenceOnExit and stayAlone. Depending on interpretation, one could look as a primary member having all these three attributes set to true.

Let's go through the proposed flow:

Start a conference

Assuming the conference will be kicked off by an inbound call (it can be an outbound call, next item somewhat addresses that), the integrating application must designate a default answer URL which will handle the business logic determining whether the conference should be started and the caller will be designated as a primary member. The business logic typically involves evaluation the dialed number (extension) and the caller's identity but can get as a complex as integrating other elements (such as collecting and evaluating a PIN etc.).

Once the business logic is cleared, the integrating application's answer URL would respond with RestXML document in the lines of:

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
    <Conference startConferenceOnEnter="true" endConferenceOnExit="true" stayAlone="true" callbackUrl="https://example.org/conference/?room=42">
        Room42
    </Conference>
</Response>

The room naming is at the discretion of the integrating application (dynamic or static, whichever works best).

Add a member to the conference from a Dial Out

Adding more members is achieved via the REST API. The integrating application will decide when it's appropriate to do so; let's assume we want to place the outbound call as soon as the primary member joins. Please note the callbackUrl attribute from the excerpt above; Eqivo will be sending conference related events to that URL.

When the said endpoint receives the enter event for the primary member, it should fire a (REST API call)[https://eqivo.org/#v0-1-call] for placing the outbound call. Let's assume the callee number is 2025551234; a curl-style example follows:

curl -X POST https://your.eqivo.host/v0.1/Call/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic ACCESS_TOKEN'
  -d 'From=8005551234&CallerName=8005551234&To=2025551234&Gateways=sofia/gateway/your_trunk/&AnswerUrl=https://example.org/conference/secondary/?room=42'

The URL designated by AnswerUrl will be invoked once the remote party answers the call. For our example, the URL would return a RestXML document such as:

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
    <Conference endConferenceOnExit="false" stayAlone="false" callbackUrl="https://example.org/conference/?room=42">
        Room42
    </Conference>
</Response>

Note the changed attributes, hinting at a less privileged conference member.

Remove that member from the conference, and add another new member via a dial out?

Conference events sent to callbackUrl feature a MemberID property. One can use this to alter a member's experience within a conference; for kicking out a member one would fire a ConferenceKick REST API call, e.g.:

curl -X POST https://your.eqivo.host/v0.1/ConferenceKick/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic ACCESS_TOKEN'
  -d 'ConferenceName=Room42&MemberID=2'

Adding new (or more concurrent) members would take a reiteration of the prior step.

Lastly, the Eqivo Sandbox repository features an example (the Click-2-Call one) which is a subset of the suggested flow. The integrating application code sample is available here (node.js for readability, adjust it to your favorite language/runtime 😄).