Managing Conferences

Aculab Cloud supports unreserved small conferences of up to 40 participants, and reserved large conferences with up to 350 participants (see Conferencing). This document describes the web services that can be used to reserve large conferences and to manage participants of conferences in progress of all sizes.

Note

Please note that the large conference feature is not enabled by default on Aculab Cloud accounts. Please contact us if you would like to use this feature.

Note

This is a low level API. For information on higher level APIs see the Web Services Language Wrappers

Authorisation

This API uses basic authentication, using your cloud account username and API Access Key.


Username	: cloudID/username (e.g. 1-2-0/bob@example.com)
Password	: API Access Key

Conference States

During its lifetime, a conference passes through several states, and some of the web services can only act on conferences whilst they are in a specific state. To discover the current state of a conference, use Conference List.

Parameter	Description
RESERVED	a conference that has been reserved using Conference Reservation Create, but has not yet started.
HOLDING	a conference that is about to start. Participants are holding waiting for the conference to become active.
ACTIVE	a conference that currently contains two or more participants, including the leader.
COMPLETED	a reserved conference that has finished.

Conference Reservation Create

This makes a conference reservation on the Aculab Cloud for a number of participants, at a specified time and for a specified duration. Attempts to connect a participant into the conference between the booking being made and the conference start time will be rejected with a cause of BUSY unless the optional divert parameter is supplied. In that case the conference connect will be diverted to the specified inbound service which can play a "call back later" message.

Request


URL	: https://ws-[cloudID].aculabcloud.net/conference_reservation_create
Methods	: GET, POST

Parameter	Required/Optional	Default	Description
conference_name	required		A name for the conference, consisting of fewer than 48 alphabetic or numeric characters. This will be referenced by applications connecting to the conference.
max_participants	required		The maximum expected number of participants. Must be between 40 and 350.
start_time	required		The required start time in UTC, in the format YYYY-MM-DD_hh:mm:ss or YYYY-MM-DD-hh-mm. The time is rounded down to whole minutes. Must be at least 5 minutes in the future, but no more than 24 hours.
duration	required		the required duration in minutes. Must be between 15 and 480.
divert	optional	Early callers will be busied	The name of an inbound service that early callers to the conference will be diverted to.

Response

A JSON object containing the following properties:

Parameter	Type	Availability	Description
reservation_token	string	always	A reservation token that corresponds to the reserved conference.

Example

Request

https://ws-[cloudID].aculabcloud.net/conference_reservation_create?conference_name=MyConferenceRoom&max_participants=130&start_time=2019-06-20_15:15:00&duration=30&divert=MyEarlyAnnouncement

Response

  {
    "reservation_token": "GIYDCMZNGA2C2MRVFUYTKLJRGVPXE33CONZG633NL5ZG6YTFOJ2C443UMFYGK4TUIBQWG5LMMFRC4Y3PNU888888"
  }

///

Conference Reservation Modify

This modifies an existing conference reservation identified by its reservation token. Only reserved conferences in the RESERVED, ACTIVE or HOLDING states can be modified, and then only by extending the conference duration, providing that the conference is not already due to finish in the next five minutes. The overall duration cannot be extended beyond a total 480 minutes. See Conference States.

Request


URL	: https://ws-[cloudID].aculabcloud.net/conference_reservation_modify
Methods	: GET, POST

Parameter	Required/Optional	Default	Description
reservation_token	required		A conference reservation token as returned by Conference Reservation Create or Conference List.
duration	integer	required

Reponse

A JSON object containing the following parameters:

Parameter	Type	Availability	Description
extended	bool	always	true if the modification succeeded.

Example

Request

https://ws-[cloudID].aculabcloud.net/conference_reservation_modify?reservation_token=GIYDCMZNGA2C2MRVFUYTKLJRGVPXE33CONZG633NL5ZG6YTFOJ2C443UMFYGK4TUIBQWG5LMMFRC4Y3PNU888888&duration=45

Response

  {
    "extended": true
  }

Conference Reservation Remove

This removes an existing conference reservation. A reservation can only be removed if the conference is in the RESERVED state, and is not due to start within the next 5 minutes. See Conference States.

Request


URL	: https://ws-[cloudID].aculabcloud.net/conference_reservation_remove
Methods	: GET, POST

Parameter	Required/Optional	Default	Description
reservation_token	required		A conference reservation token as returned by Conference List.

Response

A JSON object containing the following parameters:

Parameter	Type	Availability	Description
removed	string	always	true if the removal was successful.

Example

Request

https://ws-[cloudID].aculabcloud.net/conference_reservation_remove?reservation_token=GIYDCMZNGA2C2MRVFUYTKLJRGVPXE33CONZG633NL5ZG6YTFOJ2C443UMFYGK4TUIBQWG5LMMFRC4Y3PNU888888

Response

  {
    "removed": true
  }

Conference List

This lists all of the user's reserved and currently active conferences.

Request


Url	: https://ws-[cloudID].aculabcloud.net/conference_list
Methods	: GET, POST

Response

A JSON object containing a list of dictionaries describing conferences. The dictionaries contain the following fields.

Parameter	Type	Availability	Description
conference_name	string	always	The name of the conference.
reservation_token	string	always	The reservation token for the conference reservation. Only present if the conference is a reserved conference.
max_participants	integer	always	The maximum number of participants that the conference can hold.
start_time	string	if a reserved conference	The time, in the format YYYY-MM-DD-hh-mm, at which a reserved conference is due to start.
start_datetime	string	if a reserved conference	The time, in the format YYYY-MM-DD_hh:mm:ss, at which a reserved conference is due to start.
duration	integer	if a reserved conference	The number of minutes for which a reserved conference is due to run.
divert	string	if a reserved conference	The inbound service to which early participants to a reserved conference will be bounced.
status	string	always	The current state of the conference. One of RESERVED, HOLDING, ACTIVE, COMPLETED. The RESERVED and COMPLETED states are only reported for reserved conferences. See Conference States for details on conference states.

Example

Request

https://ws-[cloudID].aculabcloud.net/conference_list

Response

  [
    {
      "conference_name": "AnotherConf2",
      "max_participants": 40,
      "status": "ACTIVE"
    },
    {
      "conference_name": "MyConf1",
      "max_participants": 40,
      "status": "HOLDING"
    },
    {
      "reservation_token": "GIYDCMZNGA2C2MRVFUYTKLJRGVPXE33CONZG633NL5ZG6YTFOJ2C443UMFYGK4TUIBQWG5LMMFRC4Y3PNU888888",
      "conference_name": "MyConferenceRoom",
      "max_participants": 130,
      "start_time": "2019-06-20-15-15",
      "start_datetime": "2019-06-20_15:15:00",
      "duration": 30,
      "divert": "MyEarlyAnnouncement",
      "status": "RESERVED"
    }
  ]

Conference Participant List

This obtains a list of currently connected participants in the named conference. Only conferences in the ACTIVE and HOLDING states have participants to list. Note that this information is collected asynchonously from the media processing instance hosting the conference and may be up to 15 seconds behind real time.

Request


URL	: https://ws-[cloudID].aculabcloud.net/conference_participant_list
Methods	: GET, POST

Parameter	Required/Optional	Default	Description
conference_name	optional *		A conference name as returned by Conference List.
reservation_token	optional *		A conference reservation token as returned by Conference List.

* one of conference_name or reservation_token is required.

Response

A JSON object containing the following properties:

Parameter	Type	Availability	Description
status	string	always	The current state of the conference. See Conference States.
participants	JSON array of dictionaries	always	An array of dictionaries that correspond to each participant in the conference.

The details dictionary for a participant contains:

Parameter	Type	Availability	Description
participant_id	string	always	The instance ID of the application which placed the call to connect this participant to the conference, followed by xN if that call was placed on its Extra Channel N.
muted	boolean	always	true if the participant is currently muted.
dtmf_enabled	boolean	always	true if the participant's use of dtmf keys is currently enabled.

Example

Request

https://ws-[cloudID].aculabcloud.net/conference_participant_list?conference_name=MyConf1

Response

  {
    "status": "ACTIVE",
    "participants":
    [
      {
        "participant_id": "01234567a1b1c1c1.12345x0",
        "muted": true,
        "dtmf_enabled": false
      },
      {
        "participant_id": "01234567a1b1c1c2.234",
        "muted": false,
        "dtmf_enabled": true
      }
    ]
  }

Conference Participant Set Options

This sets the values of the muted and dtmf_enabled properties of the named participant in the named conference. Note that participant options can only be changed if the conference is in the ACTIVE state. See Conference States.

Request


URL	: https://ws-[cloudID].aculabcloud.net/conference_participant_set_options
Methods	: GET, POST

Parameter	Required/Optional	Description
conference_name	optional *	A conference name as returned by Conference List.
reservation_token	optional *	A conference reservation token as returned by Conference List.
participant_id	required	A conference participant_id as returned by Conference Participant List. The instance ID of the application which placed the call to connect this participant to the conference, followed by xN if that call was placed on its Extra Channel N.
muted	required	"true" to mute the participant, or "false" to unmute the participant.
dtmf_enabled	required	"true" to enable dtmf key actions for the participant, or "false" to disable these.

* one of conference_name or reservation_token is required.

Response

A JSON object containing the following parameters:

Parameter	Type	Availability	Description
options_set	boolean	always	true if the operation succeeded.

Example

Request

https://ws-[cloudID].aculabcloud.net/conference_participant_set_options?conference_name=MyConf1&participant_id=012345671a1b1c1d.12345x0&muted=true&dtmf_enabled=false

Response

  {
     "options_set": true
  }

Conference Participant Eject

This ejects the named participant from the named active conference. Note that participants can only be ejected if the conference is in the ACTIVE state. See Conference States.

Request


URL	: https://ws-[cloudID].aculabcloud.net/conference_participant_eject
Methods	: GET, POST

Parameter	Required/Optional	Description
conference_name	optional *	A conference name as returned by Conference List.
reservation_token	optional *	A conference reservation token as returned by Conference List.
participant_id	required	A conference participant_id as returned by Conference Participant List. The instance ID of the application which placed the call to connect this participant to the conference, followed by xN if that call was placed on its Extra Channel N.

* one of conference_name or reservation_token is required.

Response

A JSON object containing the following parameters:

Parameter	Type	Availability	Description
ejected	boolean	always	true if the ejection succeeded.

Example

Request

https://ws-[cloudID].aculabcloud.net/conference_participant_eject?conference_name=MyConf1&participant_id=012345671a1b1c1d.12345x0

Response

  {
      "ejected": true
  }