Conferences API

When multiple callers take part in a meeting or training they use conferences. Use the conferences API documents to get realtime information such as the number of members, the number of moderators, the duration of the conference, and the conference locked status. The realtime information is added to conference document under a _read_only key (to avoid accidental document updates).

API calls

Click on each call to view the endpoint, method, and request example.

Perform action on a conference
Perform action on participants in a conference
Perform action on a participant
Get conferences

Parameters

The table shows the possible parameters available for conferences requests.

Key	Description	Type	Options/Min/Max/Default
`name`	Required. A friendly name for the conference .	string	(1..128)
`bridge_password`	The password used for a conference bridge.	string
`bridge_username`	The username used for a conference bridge.	string
`caller_controls`	The caller controls (configuration settings).	string
`conference_numbers`	Defines conference numbers that can be used by members or moderators	array(string)
`conference_numbers.[]`	Specific conference numbers.	string
`focus`	This is a read-only property indicating the media server that is hosting the conference.	string
`max_members_media`	Specifies the media that should play when the conference is full.	string
`max_participants`	Indicates the maximum number of participants that can join.	integer
`member`	Defines the discovery (call in) properties for a member.	object
`member.join_deaf`	Determines if a member should be unable to hear the other members upon joining the conference.	boolean	The default is `false`.
`member.join_muted`	Determines if a member should be muted upon joining the conference.	boolean	The default is `true`.
`member.numbers`	Defines the conference (call in) number for members.	array(string)
`member.numbers.[]`	Specific member conference numbers.	string
`member.pins`	Defines the pin number for members array.	string
`member.pins.[]`	Specific pin numbers.	string
`moderator`	Defines the discovery (call in) properties for a moderator.	object
`moderator.join_deaf`	Determines if a moderator should join the conference unable to hear the members.	boolean	The default is `false`.
`moderator.join_muted`	Determines if a moderator should join the conference muted.	boolean	The default is `true`.
`moderator.numbers`	Defines the conference (call in) number(s) for moderators.	array(string)
`moderator.numbers.[]`	Specific moderator numbers.	string
`moderator.pins`	Defines the pin number(s) for moderators.	array(string)
`moderator.pins.[]`	Specific pin numbers.	string
`moderator_controls`	The profile on the switch for controlling the conference as a moderator.	string
`owner_id`	The user ID who manages the conference.	string	(32)
`play_entry_tone`	Specifies whether to play an entry tone, or which entry tone to play.	boolean, string
`play_exit_tone`	Specifies whether to play an exit tone, or which exit tone to play	boolean, string
`play_name`	Specifies if new conference members are announced.	boolean	Default is `false`.
`play_welcome`	Defines if the welcome prompt should play.	boolean
`profile`	The XML profile name used to configure the conference string.	false
`require_moderator`	Specifies if the conference requires a moderator.	boolean
`wait_for_moderator`	Defines if members should wait for a moderator before joining the conference.	boolean

Perform action on a conference

Performs an action on a specific conference.

Method and endpoint

PUT /v2/accounts/{ACCOUNT_ID}/conferences/{CONFERENCE_ID}

Request

curl -v -X PUT \
    -d '{"data": {"action": {CONFERENCE_ACTION}}}' \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/conferences/{CONFERENCE_ID}
    CONFERENCE_ACTION: lock, unlock

Perform action on participants

Performs an action on the participants in a conference.

Method and endpoint

  PUT /v2/accounts/{ACCOUNT_ID}/conferences/{CONFERENCE_ID}/participants

Request

  curl -v -X PUT \
      -d '{"data": {"action": {PARTICIPANTS_ACTION}}}' \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/conferences/{CONFERENCE_ID}/participants
  PARTICIPANTS_ACTION: mute/unmute/deaf/undeaf/kick

Perform action on a participant

Performs an action on a specific participant.

Method and endpoint

  PUT /v2/accounts/{ACCOUNT_ID}/conferences/{CONFERENCE_ID}/participants/{PARTICIPANT_ID}

Request

  curl -v -X PUT \
      -d '{"data": {"action": {PARTICIPANT_ACTION}}}' \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/conferences/{CONFERENCE_ID}/participants/{PARTICIPANT_ID}
  PARTICIPANT_ACTION: mute/unmute/deaf/undeaf/kick

Get conferences

Returns a list of all conferences.

Response

[
    {
        "id": "",
        "name": "",
        "owner_id": "",
        "member": {
            "join_muted": false,
            "join_deaf": false,
            "numbers": [],
            "pins": []
        },
        "moderator": {
            "join_deaf": false,
            "join_muted": false,
            "numbers": [],
            "pins": []
        },
        "members": 0,
        "admins": 0,
        "duration": 0,
        "is_locked": false
    },
    ...
]
Conference document
{
    "name": "Conf",
    "id": "",
    "owner_id": "",
    "play_entry_tone": true,
    "play_exit_tone": true,
    "play_name": false,
    "conference_numbers": [],
    "member": {
        "join_muted": false,
        "join_deaf": false,
        "numbers": [],
        "pins": []
    },
    "ui_metadata": {
        "ui": "hostedpbx-ui"
    },
    "moderator": {
        "join_deaf": false,
        "join_muted": false,
        "numbers": [],
        "pins": []
    },
    "_read_only": {
        "members": 0,
        "admins": 0,
        "duration": 0,
        "is_locked": false,
        "participants": [
            {
                "call_id": "",
                "conference_name": "",
                "conference_uuid": "",
                "switch_hostname": "",
                "floor": false,
                "hear": true,
                "speak": true,
                "talking": false,
                "mute_detect": false,
                "participant_id": 1,
                "energy_level": 20,
                "current_energy": 0,
                "video": false,
                "is_moderator": false,
                "join_time": 63635217275,
                "duration": 10
            },
            ...
        ]
    }
}

Where join_time is a participant's join time as epoch (reference time from which the rest of the duration is measured). Duration is number of seconds participants are actively in the conference. In the response, you can see the values are set up for a member, and also for a moderator.

The field, play_entry_tone, is at the root of the document which means that this field applies to everyone in the conference.

Available fields

The fields play_entry_tone and play_exit_tone can be either a boolean or a non-empty string. If true, it means that the default tone should play when someone joins (or leaves) the conference. If false, it disables the tone from being played. A string like a tone string or a URI to a media file can be inputed.

Actions

Actions are JSON objects in format:

{
    "action": {action}
}

Conference actions

lock: lock conference (prevent participants to join)
unlock: unlock conference (allow everybody to join)

Participants actions

  mute/unmute: mute/unmute all participants except moderators
  deaf/undeaf: deaf/undeaf all participants except moderators
  kick: kick every participant out

Participant actions

  mute/unmute: mute/unmute participant
  deaf/undeaf: deaf/undeaf participant
  kick: kick participant

Web-socket events

A client might subscribe to a conference event using websocket connection. Participant events are published as amqp conference.event.{conference_id}.{call_id}, where call_id is participant"s call.

The list of published events is determined by the publish_participant_event parameter of ecallmgr configuration. If this parameter is not set, then all events are published.

Participant events

add-member
del-member
stop-talking
start-talking
mute-member
unmute-member
deaf-member
undeaf-member

Example event

  {
      "custom_channel_vars": {
          "account_id": "9d351ad7ffd6f846313af9eed3bb7b85",
          "authorizing_id": "6507f40b09a61fbb8b025dbad9316eb5",
          "authorizing_type": "device",
          "owner_id": "32d8788da9506b4b1991d5bb86d27b0a",
          "presence_id": "1000@kamailio.hostedpbx",
          "fetch_id": "56507071-a216-4e0a-a28f-ff3bd9c86ac3",
          "bridge_id": "934800819",
          "precedence": 5,
          "realm": "kamailio.hostedpbx",
          "username": "sip1",
          "call_interaction_id": "63635497023-3e247b2e"
      },
      "channel_presence_id": "1000@kamailio.hostedpbx",
      "caller_id_number": "sip1",
      "caller_id_name": "sip1",
      "mute_detect": false,
      "video": false,
      "energy_level": 20,
      "current_energy": 0,
      "talking": false,
      "speak": true,
      "hear": true,
      "floor": false,
      "participant_id": 20,
      "instance_id": "d5765180-53d5-4104-860e-b352f3f8e6b1",
      "conference_id": "5edbfdd3b825314a71b0a05957392edb",
      "focus": "freeswitch@freeswitch.hostedpbx",
      "call_id": "934800819",
      "event": "add-member",
      "node": "hostedpbx_apps@jh460",
      "msg_id": "a6fbbf034b5cd3af",
      "event_name": "participant_event",
      "event_category": "conference",
      "app_version": "4.0.0",
      "app_name": "ecallmgr",
      "routing_key": "participant_event"
  }