Conferences

The Conference resource represents a connection between two or more Calls.

Overview

A Conference must be created explicitly. You logically cannot add a participant to a conference that does not exist. A conference is created either through the CreateConference PerCL command or through the REST API by posting to the /Conferences endpoint. For more information about Conferences created through PerCL, see Conferences.

The statusCallbackUrl attribute in CreateConference and /Conferences POST request are invoked as needed to inform the application of all conference status transitions. When a conference is successfully created, the statusCallbackUrl is invoked to inform the application of its conferenceId and its new empty state. In this state, conference actions such as Say or Play are not possible. No wait music plays and no recording occurs when a conference is empty.

A conference is no longer empty when at least one call/participant joins. Once populated, commands such as Say and Play to the conference can execute and wait music will start to play and will continue to play until the conference has started (status = inProgress). Only participants with listen privileges can hear the wait music.

The start of a conference (status = inProgress) occurs when at least one participant is a start-moderator. A start-moderator is one who has the startConfOnEnter flag set. In FreeClimb, there can be any number of start-moderators. Recording of a conference also starts when a conference starts. Note that conference recording option must be enabled at the time of creation of the conference.

A conference ends and returns to the empty status when the last participant leaves the conference. If recording of the conference active, the recording ends when the conference ends. The application may choose to terminate the Conference resource or to leave it empty for reuse.

It is possible to repopulate an empty conference with participants. Such reuse is possible up until the time the conference is terminated using the Conference POST method with status = terminated or the use of the TerminateConference PerCL command. When a conference is terminated, all calls that participated in the conference are terminated also. Upon termination, a conference is archived to the FreeClimb database. The ID of an archived conference will not be reused by FreeClimb when creating another conference. Note that terminating a conference doesn't delete the Conference resource from the account that owns it.

The following diagram shows a Conference’s states, and the transitions between them:


Resource properties

A Conference resource is represented by the following properties:

Property

Type

Description

uri

string

The URI for this resource, relative to /apiserver.

dateCreated

string date-time

The date that this Conference was created (GMT) in RFC 1123 format (e.g., Mon, 15 Jun 2009 20:45:30 GMT).

dateUpdated

string date-time

The date that this Conference was last updated (GMT) in RFC 1123 format (e.g., Mon, 15 Jun 2009 20:45:30 GMT).

revision

int integer

Revision count for the resource. This count is set to 1 on creation and is incremented every time it is updated.

conferenceId

string

A string that uniquely identifies this Conference resource.

accountId

string

ID of the account that created this Conference.

alias

string

A description for this Conference.

playBeep

string

Setting that controls when a beep is played. One of: always, never, entryOnly, exitOnly. Defaults to always.

record

bool

Flag indicating whether recording is enabled for this Conference.

status

string

The status of the Conference. One of: creating, empty, populated, inProgress, or terminated.

waitUrl

string

URL referencing the audio file to be used as wait music for the Conference when it is in the populated state.

actionUrl

string

URL invoked once the Conference is successfully created.

statusCallbackUrl

string url

URL to inform that the Conference status has changed.

subresourceUris

object

The list of subresources for this Conference. This includes current participants and/or recordings.