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.

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"
  }