Skip to content

Overview

Since Asterisk 13.22.0 and 15.5.0, the ConfBridge application is optionally able to send enhanced messages to participants about the bridge itself and the participants in the bridge.

What data is available?

The AMI events generated by the ConfBridge application give you an idea of what data is available. You can take a look at the ConfBridge manager events pages of your version of Asterisk. However, AMI events are typically sent only to trusted parties so not all of the information in each event is available via Enhanced Messaging. Conversely, there is data available via Enhanced Messaging that is useful for a conference application but not included in the AMI events. One of the most useful of these is a ConfbridgeWelcome event that participants receive when they join a conference. It contains a list of all the other participants currently in the conference.

What could you do with the data?

These are just a few examples.

  • For your chat application, show a list of all the current conference participants.
  • Overlay participant nicknames on their video windows.
  • Add mute/unmute indicators.
  • Highlight the video element of the current speaker.

Message examples

When Bob joins the ConfBridge he receives the ConfbridgeWelcome event:

{
 "type": "ConfbridgeWelcome",
 "timestamp": "2018-08-17T08:33:30.806-0600",
 "bridge": {
 "id": "75539107-a8fb-47fd-9b6a-7a9391ce011a",
 "name": "MYCONF",
 "video_mode": "sfu"
 },
 "channels": [
 {
 "id": "confserver-1534516369.15",
 "name": "PJSIP/trunk1-00000003",
 "state": "Up",
 "caller": {
 "name": "Alice",
 "number": "alicewonderland"
 },
 "creationtime": "2018-08-17T08:32:49.741-0600",
 "language": "en",
 "admin": true,
 "muted": false
 },
 {
 "id": "confserver-1534516410.21",
 "name": "PJSIP/trunk1-00000000",
 "state": "Up",
 "caller": {
 "name": "Bob",
 "number": "robert"
 },
 "creationtime": "2018-08-17T08:17:36.353-0600",
 "language": "en",
 "admin": true,
 "muted": false
 }
 ]
}

In the ConfbridgeWelcome event, the "channels" arrays contains all of the channels currently in the bridge, including Bob himself. In this case, Alice was already in the conference when Bob joined.

The ConfbridgeJoin event is sent to all other participants when someone joins the conference. In this case Bob is joining the conference. If the "echo_events" option is enabled, Bob can also receive his join message when he joins.

{
 "type": "ConfbridgeJoin",
 "timestamp": "2018-08-17T08:17:39.578-0600",
 "bridge": {
 "id": "ea65ab81-179a-47eb-b55e-be716a2c7c80",
 "name": "MYCONF",
 "video_mode": "sfu"
 },
 "channels": [
 {
 "id": "confserver-1534516410.21",
 "name": "PJSIP/trunk1-00000000",
 "state": "Up",
 "caller": {
 "name": "Bob",
 "number": "robert"
 },
 "creationtime": "2018-08-17T08:17:36.353-0600",
 "language": "en",
 "admin": true,
 "muted": false
 }
 ]
}

Since this is an event related to a specific participant, the "channels" array just has Bob's channel in it.

Most of the other ConfBridge events have the same contents. They are ConfbridgeJoin, ConfbridgeLeave, ConfbridgeRecord, ConfbridgeStopRecord, ConfbridgeMute, ConfbridgeUnmute, ConfbridgeWelcome. If your bridge has the "talk_detection_events" option set to "yes", participants will also receive ConfbridgeTalking events containing a "talking_status" indicator in place of the "muted" parameter appearing in most of the other events.

If you are familiar with the ConfBridge AMI events, you will notice that the ConfbridgeStart and ConfbridgeEnd events are missing. That is because they do not make much sense in this context. At the time they are generated, there are no participants to receive them.

Getting events sent to your web application

In Asterisk

Start by adding a few parameters to your user and bridge profiles in confbridge.conf:

[default_user]
type=user
send_events=yes ; If events are enabled for this bridge and this option is
 ; set, users will receive events like join, leave, talking,
 ; etc. via text messages. For users accessing the bridge
 ; via chan_pjsip, this means in-dialog MESSAGE requests.
 ; This is most useful for WebRTC participants where the
 ; browser application can use the messages to alter the user
 ; interface.
echo_events=yes ; If events are enabled for this user and this option is set,
 ; the user will receive events they trigger, talking, mute, etc.
 ; If not set, they will not receive their own events.
[default_bridge]
type=bridge
enable_events=yes ; If enabled, recipients who joined the bridge via a channel driver
 ; that supports Enhanced Messaging (currently only chan_pjsip) will
 ; receive in-dialog messages containing a JSON body describing the
 ; event. The Content-Type header will be
 ; "application/x-asterisk-confbridge-event+json".
 ; This feature must also be enabled in user profiles.

Of course, your configuration will be different but those are the parameters that need to be set.

Warning

If a user connects to the bridge via a DAHDI channel or some other non-SIP based channel, they may receive messages in another format, like SMS, which is probably not a good idea. To prevent this, you may want to use two different user profiles, one with events enabled and one without. You could then do some simple dialplan logic to look at the incoming channel technology and call ConfBridge() with the appropriate user profile.

In the browser

You use the same mechanism as shown in Conference Participant Messaging. The only difference will be that the message Content-Type will be "application/x-asterisk-confbridge-event+json". The message bodies will be JSON events as shown above.

Putting it all together

One of the possible uses for the events mentioned above was overlaying a participant's nickname on their video window. Here is a hint on how you could do that.

If you look at the events you will notice that every channel specifies an "id" field which is the Asterisk channel's unique id. When you receive ConfbridgeJoin or ConfbridgeWelcome events, save the event in a hashmap keyed by that id. When you receive a new video stream, which you can intercept by adding an "sdp" handler to your JsSip RTCSession, look at the sdp and look for the "a:label" and "a:msid" attributes in each video stream. The "a:label" will be the participant's channel id as specified in the events and the "a:msid" will be available in the video element WebRTC creates. Now, just create another hashmap that cross references the two and when you draw your video elements, you can grab the msid from it and then get the corresponding participant from the hashmaps.