CreateConference

The CreateConference command does exactly what its name implies — it creates an empty Conference (one without any Participants). Once created, a Conference remains in FreeClimb until explicitly terminated by a customer. Once a Conference has been terminated, it can no longer be used.

CreateConference is a Terminal command (any actions following it are never executed). When the Conference is successfully created, FreeClimb invokes the provided actionUrl using an HTTP POST with a createConference Webhook as the body. After this request, control picks up using the PerCL code received in the response.

Nesting Rules

No actions can be nested within CreateConference and CreateConference cannot be nested in any other actions.

Example

[
  {
        "CreateConference": {
            "actionUrl": "http://example.com/conferenceCreated",
            "statusCallbackUrl": "http://www.example.com/conferenceStatusChanged"
        }
    }
]

Command Attributes

CreateConference supports the following attributes that modify its behavior:

Attribute

Description

actionUrl

URL to which FreeClimb sends an HTTP POST request when the Conference is successfully created.

statusCallbackUrl

This URL is invoked when the status of the Conference changes or when a recording of the Conference has become available.

alias

Descriptive name for the Conference.

playBeep

Indicates whether to play a beep when a Participant enters or leaves the Conference.

record

When set to true, the entire Conference is recorded.

waitUrl

If specified, this URL provides the custom hold music for the Conference when it is in the populated state.


actionUrl

REQUIRED

Type: absolute URL
Default: null

This URL is invoked once the Conference is successfully created. Actions on the Conference, such as adding Participants, can be performed via the PerCL script returned in the response. Both the actionUrl and statusCallbackUrl are invoked when the Conference is successfully created.

Note: A PerCL response is expected to control the Conference.

The actionUrl is sent a createConference Webhook. The conferenceId parameter indicates the ID of the Conference that was created.


statusCallbackUrl

OPTIONAL

Type: absolute URL
Default: null

This URL is invoked when the status of the Conference changes or when a recording of the Conference has become available. A Conference status can change via:

  • PerCL command
  • REST API request
  • When it is successfully created and becomes empty
  • When the first Participant joins, resulting in a populated Conference
  • When the first Participant whose startConfOnEnter property is set to true joins (thereby changing the Conference to inProgress)
  • When the last Participant leaves the Conference, thereby changing the Conference status to empty
    Participants can be successfully added to a Conference once the statusCallbackUrl is invoked, signifying the Conference has been successfully created and is empty.
    When a populated or inProgress Conference is terminated (via PerCL or the REST API), this URL will be called twice – once when the Conference becomes empty and then again when it is terminated.

Note: This is a notification only; any PerCL returned will be ignored.

Additional Request Parameters

Request Parameter

Description

`conferenceId`

ID of the Conference created.

`status`

The new status of the Conference. See valid values below.

`recordingUrl`

URL of the Conference recorded audio. Populated only if a recording exists and the Conference was emptied.

`recordingId`

ID of the recording from this Conference. Populated only if a recording exists and the Conference was emptied.

`recordingDurationSec`

Duration of the recorded audio rounded up to the nearest second (in seconds). Populated only if a recording exists and the Conference was emptied.

status Valid Values

Value

Description

`creating`

Status while the Conference is being created.

`empty`

Status of the Conference when no Conference Participants are present.

`populated`

Status of the Conference when Conference Participants are present.

`inProgress`

Status of the Conference while active.

`terminated`

Status of a deleted Conference.


alias

OPTIONAL

Type: string
Default: null

Descriptive name for the Conference.


playBeep

OPTIONAL

Type: string (either always, never, entryOnly, or exitOnly)
Default: always

Indicates whether to play a beep when a Participant enters or leaves the Conference.


record

OPTIONAL

Type: boolean
Default: false

When set to true, the entire Conference is recorded. The statusCallbackUrl of the Conference will receive a conferenceRecordingStatus Webhook when the Conference transitions from the inProgress to empty status.


waitUrl

OPTIONAL

Type: absolute URL
Default: null

If specified, this URL provides the custom hold music for the Conference when it is in the populated state. A system default hold music will play for Conferences not using the waitUrl attribute. This attribute is always fetched using HTTP GET and is fetched just once – when the Conference is created.

Note: The URL must be an audio file that is reachable and readable by FreeClimb.