In “Enrich Your Conference App with Asterisk Enhanced Messaging – Part 1” I demonstrated how you could include chat or other messaging features in your conference app.  In Part 2, I’ll show you how to include information about the conference bridge itself and the participants.

What data is available?

If you’re familiar with the AMI events generated by app_confbridge then you’ve got a leg up on the data available.  If not, take a quick look at the Confbridge events on the Asterisk 16 AMI Events page of the Asterisk Wiki.  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 app 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 can I do with the data?

Let’s see…

• For your chat app, 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.

These are just a few examples.  I’m sure you can think of more uses for your own app.

Exactly what data do I get?

Let’s take a look at the ConfbridgeJoin event.  It’s sent to all participants when someone joins the conference.  In this case, Bob is joining.

{
  "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.  Now let’s take a look at the ConfbridgeWelcome event that Bob also received when he joined:

{
  "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.

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” 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’re familiar with the Confbridge AMI events, you’ll notice that the ConfbridgeStart and ConfbridgeEnd events are missing.  That’s because they don’t make much sense in this context.  At the time they’re generated, there are no participants to receive them!

OK, How do I get the events in my web app?

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 messages.
                ; 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.  One note of warning though, 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 Part 1 of this blog series.  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 shown above.

Putting it all together

One of the possible uses for the events I mentioned above was overlaying a participant’s nickname on their video window so here’s a hint on how you could do that.

If you look at the events you’ll 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.

Wrap up

Hopefully you’ve now got a good idea of what Enhanced Messaging can do for your conference app.  Feel free to ask questions here, on the asterisk-dev mailing list or in the #asterisk-dev freenode IRC channel.

If you’re coming to AstriCon or AstriDevCon in October, we’ll be there and would love to hear your feedback!