September 6th, 2024

Microsoft Graph APIs for Teams town hall now generally available

Microsoft Teams supports multiple types of scheduled real-time voice and video experiences. These range from ad hoc meetings suitable for a small number of participants to large structured virtual events like webinars and town halls with thousands of attendees. 

The following table provides a comparison of the types of meetings that Teams supports.   

Meeting type  Use cases 
Online meeting 
  • Hosting a meeting for up to 1,000 participants who can be inside or outside of your organization. Everyone can interact via audio, video, chat, and screensharing.  
  • Meetings are either scheduled, ad hoc, or channel meetings. 
Webinar  
  • Hosting a meeting where one or several experts (presenters) share their ideas or provide training to an audience (attendees inside or outside of your organization) with a maximum of 1,000 participants on the call.   
  • Registration is needed before attendees can join the meeting.  
Town hall  
  • Automatic streaming event for a limited number of presenters to a large group of attendees, capping at 10,000 or 20,000 participants (with Teams Premium).  
  • Attendees don’t need to register for the event but are invited and use Q&A to engage with presenters and organizers instead of direct interaction via chat or audio.  

 To learn more about the differences between each meeting type to help you choose the one that is best suited for your use case, see the feature comparison chart.  

Microsoft Graph for online meetings are already generally available. Developers can use these APIs to programmatically schedule online meetings with the appropriate meeting options. Today, we’re announcing the general availability of new Teams town hall APIs. 

What’s new?  

The following resources are now generally available: 

  • virtualEventTownhall – Used to create, get, update, publish, and cancel a Teams town hall.  
  • virtualEventPresenter – Used to create, get, list, update, and delete a presenter for a Teams town hall.  
  • virtualEventSession – A town hall created via Microsoft Graph APIs has one session that inherits the properties of online meetings.  

Town hall personas 

To make the best use of the Teams town hall APIs, it’s helpful to understand the personas for the users who access the Teams town hall experience:  

  • Organizers are employees (in your organization) who manage the town hall. They are the authority on when town halls take place and who participates. They configure town hall details such as title, theme, attendee experience, and email rules. 
  • Presenters are employees (in your organization) or external participants who lead the town hall. 
  • Attendees are either employees (in your organization) or external users who join the town hall and are either invited via email or the link to the town hall event is shared with them.  
  • Teams tenant administrator must authorize custom applications with appropriate permissions.   

Solutions you can build  

The following table lists some solutions you can build by using the Teams client and Microsoft Graph town hall APIs. 

Custom application use case   Description  
Data sync  Pull Teams town hall data into a custom application. 
Create/update/delete   Programmatically create, update, and delete Teams town halls. 
Email communication   Use your own email infrastructure to send out town hall-related notification emails. 

Data sync  

The following table lists the Teams client setup and the Microsoft Graph APIs to use to implement a town hall data sync solution.  

Teams client  Microsoft Graph town hall APIs  
The town hall is hosted in Teams.  Use the Get townhall API to pull data regarding a specific town hall. such as who is invited, who created the town hall, and who are the co-organizers.  

Create/update/delete 

The following table lists the Teams client setup and the Microsoft Graph APIs to use to implement a custom application to programmatically create, update, or delete town halls.   

Teams client  Microsoft Graph town hall APIs  
The town hall created via Microsoft Graph APIs will be a Teams town hall visible and editable in the Teams client.  
  • Just like in Teams, organizers can only create town hall events. The Create town hall API can only be called with delegated permissions on behalf of the organizer.  
  • Only organizers and co-organizers can update and delete town halls.  

Email communication 

The following table lists the Teams client setup and the Microsoft Graph APIs to use to implement a customized email communication experience for town halls.  

Teams client  Microsoft Graph town hall APIs  
  • Email communications to attendees are turned off at the time of creation of the town hall.  
  • Teams will still send email/invites to organizers, co-organizers, and presenters (internal and external).  

 

Turn off isAttendeeEmailNotificationEnabled in the settings property when you use the Create town hall API.   

 

To learn how to authenticate and get your app authorized to use Microsoft Graph, see Authentication and authorization basics. 

Author

Annie Wang
Program Manager
Sheri Mehmood
Senior Product Manager

0 comments