When using the Dolby.io Communications API, we often find that it is helpful to create tools to enforce moderation of participants. We want to be able to manage who is allowed in each session, what access they have, and so on, with all of these needs changing depending on the situation. This can even change in the middle of each conference, and is useful for situations such as moderating webinars and live streams. To help manage these situations, we can use the Dolby.io Monitor and Conference REST API endpoints to perform these actions on demand. This blog post will highlight how to get started using these APIs using Postman Flows to illustrate a typical workflow.
Live Stream & Webinar Moderator Tools
Moderators Tools for Live Streams and Webinars
In this guide, we will be using the “Kick” command as the example used to demonstrate the API workflow, but the steps can be modified to whichever result is needed for the situation. Kicking participants is a common tool used for managing unwanted participants from our meetings to remove them before they are able to create further disruption. To begin, we will first need to obtain some information. Other tools offered by Dolby.io Communications include:
- Inviting Users
- Updating Permissions
- Modifying the Spatial Audio scene
- Broadcasting Messages
- Terminating the Conference
These tools will be covered in future content, and can be found at the API reference.
Collecting API Credentials
As with every other API call we make, we first need to obtain our client token used to access the Dolby.io Communications APIs. If this is your first-time or would like to review the steps, our API Authentication guide covers where you should look at. In this case, we are using Postman as our interface, so we will be saving our Key and Secret directly within our environment, but ensure you are able to obtain your Bearer Token for the interface you are using! Make sure to sign up for an account for free if you haven’t already.
Obtaining Conference Metadata
The first step we need to do in order to actively moderate our conference is to figure out the unique identifiers that are specific to the conference in question. This is done with the get a list of conferences endpoint within the Monitor API. What this will output is a list of the last 100 conferences associated with the inputted API credentials, along with all of the metadata associated. We can change some of the optional parameters in this API call to narrow down the conferences better to get the specific conference we wish to moderate. The key parameter to change is to set the “active” boolean to “true”, which will only show conferences that are currently live and running, culling all finished conferences from the output. We could additionally use the “alias” string if we know the conference’s alias is unique, which will help us get the specific one. In the Postman example below, I am demonstrating it a bit differently for illustrative purposes, instead checking if the “live” parameter of the output is true. What matters is that we are able to obtain the conferenceId variable and save it to refer in future API calls.
curl --request GET \
--url 'https://comms.api.dolby.io/v1/monitor/conferences?alias=<alias>&active=true' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'authorization: Bearer <token>'
Finding the User IDs
With the Conference ID in hand, we can now obtain the list of participants within the webinar or stream we are looking to moderate. This is done with the get information about conference participants endpoint within the Monitor API, passing in the conferenceId collected. Like the Conferences endpoint we used before, this will also output a list of all participants in the conference. This list can also be further reduced with parameters, however in this case it is up to your preference, as we can kick one or many participants all at the same time. What is important is formatting the output properly: we need to obtain an array of all externalIDs of the users we wish to kick from our conference.
Note that this is an optional parameter when building your conference application, but is required if you want to use the API moderation tools. We suggest reviewing your participant management code in your conference application to ensure these parameter is included upon users joining your conference.
curl --request GET \
--url https://comms.api.dolby.io/v1/monitor/conferences/<conferenceId>/participants \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'authorization: Bearer <token>'
Issuing the Moderation Tool Command
With the list of externalIds in hand, we can now perform the kick event! This is done with one final POST API call in the Conference API, passing in both our conferenceId and our list of externalIds. Once again, this example is using Kick, but you can also invite users to your webinar, update permissions of participants in a call, or send a message to users in a live stream. Something to note here is that this request on a successful POST will only return a 200 OK header with no body, so don’t be worried if you don’t see one! A typical error body will show if the call fails.
curl --request POST \
--url https://comms.api.dolby.io/v2/conferences/<CconferenceId>/kick \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'authorization: Bearer <token>' \
--data '
{
"externalIds": [
"<externalId1>",
"<externalId2>"
]
}
'
Continued Reading of Moderation Commands
This post was demonstrated as a workflow using Postman flows, which you can visit and fork for yourself. The final flow looks like the following as an example of the steps taken to get our final result:
As for next steps, there are plenty of ways this idea can be expanded further as a fully featured moderation tool suite. For example, creating a user interface to abstract this chain of API calls into something like a simple button or two placed in a GUI, or translate these to a CLI tool. This is the beauty of REST APIs: they’re extremely portable and versatile for all use cases. Show us the tools you make with our APIs, we’d love to see some examples on GitHub. Tweet them to us @DolbyIO!
If you are curious about how to get started building with Postman Flows, you can see a previous blog post that goes in more detail.
Additionally, if you would like to learn how to perform actions like muting specific users, read this post. Or you can learn more about other features in the Monitor API with this post demonstrating how to pull conference recordings directly from the API.
