Managing Conferences

Aculab Cloud supports unreserved small conferences of up to 40 participants, and reserved large conferences with up to 350 participants (see Conferencing Capabilities). 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.

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.

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

Note on 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.

State	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.

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

Request:

Url	:	https://ws.aculabcloud.net/conference_reservation_create
Methods	:	GET, POST

Parameter	Value	Description
conference_name	string	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	integer	the maximum expected number of participants. Must be between 40 and 350.
start_time	string	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	integer	the required duration in minutes. Must be between 15 and 480.
divert	string	an optional parameter that specifies the inbound service to bounce early participants to. If not present, early callers will be busied instead.

Returns:

A JSON object containing the following properties:

Parameter	Value	Description
reservation_token	string	a reservation token that corresponds to the reserved conference.

Example:

https://ws.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 Note on Conference States for details on conference states.)

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

Request:

Url	:	https://ws.aculabcloud.net/conference_reservation_modify
Methods	:	GET, POST

Parameter	Value	Description
reservation_token	string	a conference reservation token as returned by Conference Reservation Create or Conference List.
duration	integer	the number of minutes by which to extend the existing conference reservation. Must be between 15 and 60 minutes, and cannot take the total conference duration beyond 480 minutes.

Returns:

A JSON object containing the following parameters:

Parameter	Value	Description
extended	boolean	true if the modification succeeded.

Example:

https://ws.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 Note on Conference States for details on conference states.)

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

Request:

Url	:	https://ws.aculabcloud.net/conference_reservation_remove
Methods	:	GET, POST

Parameter	Value	Description
reservation_token	string	a conference reservation token as returned by Conference Reservation Create or Conference List.

Returns:

A JSON object containing the following parameters:

Parameter	Value	Description
removed	string	true if the removal was successful.

Example:

https://ws.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.

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

Request:

Url	:	https://ws.aculabcloud.net/conference_list
Methods	:	GET, POST

Returns:

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

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

Example:

https://ws.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.

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

Request:

Url	:	https://ws.aculabcloud.net/conference_participant_list
Methods	:	GET, POST

Parameter	Value	Description
conference_name	string	a conference name as returned by Conference List.
reservation_token	string	optional alternate instead of conference_name: a conference reservation token as returned by Conference List.

Returns:

A JSON object containing the following properties:

Parameter	Value	Description
status	string	the current state of the conference. See Note on Conference States for details.
participants	JSON array of dictionaries	an array of dictionaries that correspond to each participant in the conference.

The details dictionary for a participant contains:

Parameter	Value	Description
participant_id	string	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	true if the participant is currently muted.
dtmf_enabled	boolean	true if the participant's use of dtmf keys is currently enabled.

Example:

https://ws.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 Note on Conference States for details on conference states.)

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

Request:

Url	:	https://ws.aculabcloud.net/conference_participant_set_options
Methods	:	GET, POST

Parameter	Value	Description
conference_name	string	a conference name as returned by Conference List.
reservation_token	string	optional alternate instead of conference_name: a conference reservation token as returned by Conference List.
participant_id	string	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	string	'true' to mute the participant, or 'false' to unmute the participant.
dtmf_enabled	string	'true' to enable dtmf key actions for the participant, or 'false' to disable these.

Returns:

A JSON object containing the following parameters:

Parameter	Value	Description
options_set	boolean	true if the operation succeeded.

Example:

https://ws.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 Note on Conference States for details on conference states.)

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

Request:

Url	:	https://ws.aculabcloud.net/conference_participant_eject
Methods	:	GET, POST

Parameter	Value	Description
conference_name	string	a conference name as returned by Conference List.
reservation_token	string	optional alternate instead of conference_name: a conference reservation token as returned by Conference List.
participant_id	string	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.