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.

StateDescription
RESERVEDa conference that has been reserved using Conference Reservation Create, but has not yet started.
HOLDINGa conference that is about to start. Participants are holding waiting for the conference to become active.
ACTIVEa conference that currently contains two or more participants, including the leader.
COMPLETEDa 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

    ParameterValueDescription
    conference_namestringa name for the conference, consisting of fewer than 48 alphabetic or numeric characters. This will be referenced by applications connecting to the conference.
    max_participantsintegerthe maximum expected number of participants. Must be between 40 and 350.
    start_timestringthe 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.
    durationintegerthe required duration in minutes. Must be between 15 and 480.
    divertstringan 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:

    ParameterValueDescription
    reservation_tokenstringa 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

    ParameterValueDescription
    reservation_tokenstringa conference reservation token as returned by Conference Reservation Create or Conference List.
    durationintegerthe 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:

    ParameterValueDescription
    extendedbooleantrue 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

    ParameterValueDescription
    reservation_tokenstringa conference reservation token as returned by Conference Reservation Create or Conference List.

    Returns:

    A JSON object containing the following parameters:

    ParameterValueDescription
    removedstringtrue 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.

    ParameterValueDescription
    conference_namestringthe name of the conference.
    reservation_tokenstringthe reservation token for the conference reservation. Only present if the conference is a reserved conference.
    max_participantsintegerthe maximum number of participants that the conference can hold.
    start_timestringthe 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_datetimestringthe 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.
    durationintegerthe number of minutes for which a reserved conference is due to run. Only present if the conference is a reserved conference.
    divertstringthe inbound service to which early participants to a reserved conference will be bounced. Only present if the conference is a reserved conference.
    statusstringthe 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

    ParameterValueDescription
    conference_namestringa conference name as returned by Conference List.
    reservation_tokenstringoptional alternate instead of conference_name: a conference reservation token as returned by Conference List.

    Returns:

    A JSON object containing the following properties:

    ParameterValueDescription
    statusstringthe current state of the conference. See Note on Conference States for details.
    participantsJSON array of dictionariesan array of dictionaries that correspond to each participant in the conference.

    The details dictionary for a participant contains:

    ParameterValueDescription
    participant_idstringthe 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.
    mutedbooleantrue if the participant is currently muted.
    dtmf_enabledbooleantrue 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

    ParameterValueDescription
    conference_namestringa conference name as returned by Conference List.
    reservation_tokenstringoptional alternate instead of conference_name: a conference reservation token as returned by Conference List.
    participant_idstringa 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.
    mutedstring'true' to mute the participant, or 'false' to unmute the participant.
    dtmf_enabledstring'true' to enable dtmf key actions for the participant, or 'false' to disable these.

    Returns:

    A JSON object containing the following parameters:

    ParameterValueDescription
    options_setbooleantrue 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

    ParameterValueDescription
    conference_namestringa conference name as returned by Conference List.
    reservation_tokenstringoptional alternate instead of conference_name: a conference reservation token as returned by Conference List.
    participant_idstringa 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.

    Returns:

    A JSON object containing the following parameters:

    ParameterValueDescription
    ejectedbooleantrue if the ejection succeeded.

    Example:

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

    Response:

      {
          "ejected": true
      }