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


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:

uristringThe URI for this resource, relative to /apiserver.
dateCreatedstring date-timeThe date that this Conference was created (GMT) in RFC 1123 format (e.g., Mon, 15 Jun 2009 20:45:30 GMT).
dateUpdatedstring date-timeThe date that this Conference was last updated (GMT) in RFC 1123 format (e.g., Mon, 15 Jun 2009 20:45:30 GMT).
revisionint integerRevision count for the resource. This count is set to 1 on creation and is incremented every time it is updated.
conferenceIdstringA string that uniquely identifies this Conference resource.
accountIdstringID of the account that created this Conference.
aliasstringA description for this Conference.
playBeepstringSetting that controls when a beep is played. One of: always, never, entryOnly, exitOnly. Defaults to always.
recordboolFlag indicating whether recording is enabled for this Conference.
statusstringThe status of the Conference. One of: creating, empty, populated, inProgress, terminated, or internalError.
waitUrlstringURL referencing the audio file to be used as wait music for the Conference when it is in the populated state.
actionUrlstringURL invoked once the Conference is successfully created.
statusCallbackUrlstring urlURL to inform that the Conference status has changed.
subresourceUrisobjectThe list of subresources for this Conference. This includes current participants and/or recordings.