Introducing the Webex Messaging Announcement Mode API

December 10, 2021
Phil Bellanti
Phil BellantiProduct Manager - Webex innovations
Introducing the Webex Messaging Announcement Mode API

Announcement mode in Webex messaging allow bots and integrations to share important information inside a Webex space, without the distractions from other conversations. For example, announcement spaces are a great way to send automated alerts and notifications that won’t get buried by other messages. From there, it can perhaps guide to users to the appropriate conversation spaces to follow up on the notifications.

These type of announcement spaces can now be created by Webex bots and integrations in one step, allowing a streamlined approach for developers to enable this functionality in their apps. This new API method also allows the quicker creation of moderated spaces, so there is much to like!

How an App Creates a Webex Space in Announcement Mode

Bots and integrations can create a Webex messaging space in announcement mode with some new parameters that have been added to the rooms API: isLocked and isAnnouncementOnly.

  • First, since a Webex space is required to be locked to enable announcement-mode, the value for isLocked must be set to true. This will tell Webex to create a locked space, with the authenticated user/bot assigned as the default moderator.
  • Next, by also setting the isAnnouncementOnly value to true, the locked space will be created in announcement mode, where only the assigned moderators can post messages.

Using those two parameters, the API request to create an announcement space named “ALERTS” might look something like this:

https://webexapis.com/v1/rooms -H "Content-type: application/json" -d '{"title":"ALERTS","isLocked":true,"isAnnouncementOnly":true}'

More Webex Announcement Space Tidbits

As you see, the APIs for creating a Webex space in announcement-mode is rather straightforward. However, there are a few other things to keep in mind when leveraging this in an application:

  • The ability to create a locked Webex messaging space or act as moderator is not available in accounts under the Cisco Webex Free Plan, from either the Webex app or the corresponding APIs.
  • Bots and integrations can add or update the moderators in announcement spaces just like traditional group messaging spaces - through the isModeratorparameter in the Memberships API. Prior to this update, this was the only way to even create a locked Webex space.
  • Announcement spaces can always be quickly changed back to a group space and keep the moderators by simply updating the /room isAnnouncementOnly parameter to false.

As always, you can count on the awesome Webex Developer Support team to assist with any questions or challenges that come up. In the meantime, happy developing!