{"id":9166,"date":"2021-12-21T08:00:28","date_gmt":"2021-12-21T16:00:28","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/?p=9166"},"modified":"2021-12-20T07:37:28","modified_gmt":"2021-12-20T15:37:28","slug":"new-features-in-microsoft-graph-bookings-apis-provide-enhanced-booking-infrastructure","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/new-features-in-microsoft-graph-bookings-apis-provide-enhanced-booking-infrastructure\/","title":{"rendered":"New features in Microsoft Graph Bookings APIs provide enhanced booking infrastructure"},"content":{"rendered":"

The Microsoft Graph team is committed to providing booking infrastructure through the Bookings APIs so that customers can build robust customized solutions. We have been listening to customers and have received many requests for new features. Based on this feedback, we have launched some key new features such as SMS notifications, online meetings, group appointments and custom questions.<\/p>\n

SMS notifications<\/h3>\n

SMS notifications have always been one of the major asks of customers across industries like healthcare, retail, and finance because reaching consumers is often more convenient through SMS notifications. \u00a0Recently, we went GA with a SMS notification feature in the United States and Canada. Today, we are excited to announce the addition of SMS notification support in the Bookings API. Currently, this feature is only available for customers in US and Canada on Bookings Calendars created in the NAM region. We will look to expand availability to other countries in the future.<\/p>\n

SMS notifications can be enabled for a bookingService and at a bookingAppointment level as well, with the bookingAppointment level setting taking precedence.<\/p>\n\n\n\n\n\n
Attribute<\/strong><\/td>\nResource Type<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
smsNotificationsEnabled<\/strong><\/td>\nbookingService<\/td>\nIndicates if SMS is enabled for the service<\/td>\n<\/tr>\n
smsNotificationsEnabled<\/strong><\/td>\nbookingAppointment<\/td>\nIndicates if SMS is enabled for the appointment<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

<\/h3>\n

Online meetings<\/h3>\n

Support for online meetings was launched for our web and Team\u2019s apps. It has been one of the key features of Bookings and has seen tremendous growth over the last couple of years. Now, one can enable online meetings for a bookingService via APIs. For an appointment of such a service, a Team\u2019s meeting link will be auto generated. This link is part of the appointment resource type and can be accessed via APIs.<\/p>\n\n\n\n\n\n
Attribute<\/strong><\/td>\nResource Type<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
isLocationOnline<\/strong><\/td>\nbookingService<\/td>\nIndicates if the meeting is online<\/td>\n<\/tr>\n
joinWebUrl<\/strong><\/td>\nbookingAppointment<\/td>\nThe URL to join the online meeting<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n

Staff and customer time zones<\/h3>\n

The bookingAppointment resource type has an attribute for customer timezone and the bookingStaffMember resource type has an attribute for the staff timezone.<\/p>\n\n\n\n\n\n
Attribute<\/strong><\/td>\nResource Type<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
customerTimeZone<\/strong><\/td>\nbookingAppointment<\/td>\nTimezone of the customer for the appointment<\/td>\n<\/tr>\n
timeZone<\/strong><\/td>\nbookingStaffMember<\/td>\nTimezone of the staff member<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n

Enhanced bookingCustomer resource type<\/h3>\n

We have enhanced the resource type to bring it at par with our webapp in which one can add and view additional customer properties such as address and phone number. The following new attributes have been added.<\/p>\n\n\n\n\n\n
Attribute<\/strong><\/td>\nResource Type<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
location<\/strong><\/td>\nbookingCustomer<\/td>\nThe address of the customer. Location is of type physicalAddress. However only the \u201cother\u201d address type is supported.<\/td>\n<\/tr>\n
phone<\/strong><\/td>\nbookingCustomer<\/td>\nThe phone number of the customer<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n

Custom questions<\/h3>\n

Custom questions are one of the key features of Bookings. It can be used to collect additional information in an appointment.<\/p>\n

Custom questions are created for a \u2018bookingBusiness\u2019 resource type. They can be attached to bookingServices resource type of that bookingBusiness. Finally, a bookingAppointment of these bookingServices will contain the custom questions and answers to those question.<\/p>\n

CRUD operations can be done on custom questions via APIs.<\/p>\n

Example of CRUD operations for custom questions<\/h4>\n

Retrieve a custom question object<\/strong><\/p>\n

GET https:\/\/graph.microsoft.com\/beta\/bookingBusinesses\/<businessId>\/customQuestions\/<questionId>\r\n\r\nHTTP\/1.1 200 OK\r\n{\r\n  \"id\": \"3bc6fde0-4ad3-445d-ab17-0fc15dba0774\",\r\n  \"displayName\": \"What is your age\",\r\n  \"answerInputType\": \"text\",\r\n  \"answerOptions\": []\r\n}<\/pre>\n
List all custom questions in a business<\/strong><\/p>\n
GET https:\/\/graph.microsoft.com\/beta\/bookingBusinesses\/<businessId>\/customQuestions\r\n\r\nHTTP\/1.1 200 OK\r\n[\r\n  {\r\n    \"id\": \"\",\r\n    \"displayName\": \"What\u2019s your faviourite color\",\r\n    \"answerInputType\": \"text\",\r\n    \"answerOptions\": []\r\n  },\r\n  {\r\n    \"id\": \"\",\r\n    \"displayName\": \"What do you want to get from this session?\",\r\n    \"answerInputType\": \"text\",\r\n    \"answerOptions\": []\r\n  }\r\n]<\/pre>\n
Create a custom question<\/strong><\/p>\n
POST https:\/\/graph.microsoft.com\/beta\/bookingBusinesses\/<businessId>\/customQuestions\r\n{\r\n  \"displayName\": \"What is your age\",\r\n  \"answerInputType\": \"text\",\r\n  \"answerOptions\": []\r\n}\r\n\r\nHTTP\/1.1 201 Created\r\n{\r\n  \"id\": \"3bc6fde0-4ad3-445d-ab17-0fc15dba0774\",\r\n  \"displayName\": \"What is your age\",\r\n  \"answerInputType\": \"text\",\r\n  \"answerOptions\": []\r\n}<\/pre>\n
<\/pre>\n
Update a custom question<\/strong><\/p>\n
PATCH https:\/\/graph.microsoft.com\/beta\/bookingBusinesses\/<businessId>\/customQuestions\/<questionId>\r\n{\r\n  \"displayName\": \"What is your date of Birth\"\r\n}\r\n\r\nHTTP\/1.1 204 No Content\r\n\r\nDELETE https:\/\/graph.microsoft.com\/beta\/bookingBusinesses\/<businessId>\/customQuestions\/<questionId>\r\n\r\nHTTP\/1.1 204 NO CONTENT<\/pre>\n
Custom questions in a bookingService<\/h3>\n
One can associate any custom question in a bookingService. It can be done by using a complex type called custom questions. An example is shown below in which a service is being created with custom fields. The \u201cisRequired\u201d field indicates if it is mandatory to have a value for this custom field in an appointment.<\/p>\n
POST https:\/\/graph.microsoft.com\/beta\/bookingBusinesses\/Contosolunchdelivery@M365B489948.onmicrosoft.com\/services\r\nContent-type: application\/json\r\n\r\n{\r\n    \"@odata.type\":\"#microsoft.graph.bookingService\",\r\n    ..\r\n    ..\r\n    ..\r\n    \r\n    \"customQuestions\": [\r\n        {\r\n            \"questionId\": \"75fc2eaf-624f-40b2-a289-63e51a56fcf2\",\r\n            \"isRequired\": true\r\n        },\r\n        {\r\n            \"questionId\": \"b90e7840-4c0c-430f-b96f-74ad9d2f64f7\",\r\n            \"isRequired\": false\r\n        }\r\n    ]\r\n}<\/pre>\n
Custom questions in an appointment<\/h4>\n
Within a bookingAppointment, answers to custom questions can be added for an individual customer within a customer collection. Note that depending on the setting in the service some of the answers may be mandatory.<\/p>\n
Here, a snippet is shown where an appointment is being created with custom questions.<\/p>\n
POST https:\/\/graph.microsoft.com\/beta\/bookingBusinesses\/Contosolunchdelivery@M365B489948.onmicrosoft.com\/appointments\r\nContent-type: application\/json\r\n\r\n{\r\n    \"@odata.type\":\"#microsoft.graph.bookingAppointment\",\r\n     ...\r\n     ...\r\n     ...\r\n    \"customers\": [\r\n        {\r\n            \"@odata.type\":\"#microsoft.graph.bookingCustomerInformation\",\r\n            \"customerName\":\"Jordan Miller\",\r\n           \r\n           ...\r\n           ...\r\n            \"customQuestionAnswers\": [\r\n                {\r\n                    \"questionId\": \"75fc2eaf-624f-40b2-a289-63e51a56fcf2\",\r\n                    \"answer\": \"Bread\",\r\n                    \"selectedOptions\": [\"Bread\"]\r\n                }\r\n            ],\r\n             ...\r\n             ...\r\n            }\r\n        }\r\n    ],\r\n    ...\r\n    ...\r\n    ...\r\n\r\n}<\/pre>\n
Here is another example where an appointment is being retrieved<\/p>\n
GET https:\/\/graph.microsoft.com\/beta\/bookingBusinesses\/Contosolunchdelivery@M365B489948.onmicrosoft.com\/appointments\/AAMkADKnAAA=\r\n\r\nResponse\r\n\r\nHTTP\/1.1 200 OK\r\nContent-type: application\/json\r\n\r\n{\r\n    \"@odata.context\": \"https:\/\/graph.microsoft.com\/beta\/$metadata#bookingBusinesses('Contosolunchdelivery%40M365B489948.onmicrosoft.com')\/appointments\/$entity\",\r\n    \"id\": \"AAMkADKnAAA=\",\r\n    \"selfServiceAppointmentId\": \"00000000-0000-0000-0000-000000000000\",\r\n    ...\r\n    ...\r\n    \"customers\": [\r\n        {\r\n            \"customerId\": \"7ed53fa5-9ef2-4f2f-975b-27447440bc09\",\r\n            \"customerName\": \"Jordan Miller\",\r\n            ...\r\n            ...\r\n            \"customQuestionAnswers\": [\r\n                {\r\n                    \"questionId\": \"75fc2eaf-624f-40b2-a289-63e51a56fcf2\",\r\n                    \"question\": \"What's your favourite food\",\r\n                    \"answerInputType\": \"radioButton\",\r\n                    \"answerOptions\": [\r\n                        \"Banana Bread\",\r\n                        \"Apple Pie\",\r\n                        \"Cheese Cake\"\r\n                    ],\r\n                    \"isRequired\": true,\r\n                    \"answer\": \"Apple Pie\",\r\n                    \"selectedOptions\": [\"Apple Pie\"]\r\n                }\r\n            ],\r\n            ...\r\n            ...\r\n            }\r\n        }\r\n    ]\r\n}<\/pre>\n
<\/pre>\n
Attributes and complex types of custom questions<\/h3>\n\n\n\n\n\n\n\n\n\n\n
Attribute<\/strong><\/td>\nResource Type<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
Id<\/strong><\/td>\nbookingCustomQuestions<\/td>\nThe unique id<\/td>\n<\/tr>\n
displayName<\/strong><\/td>\nbookingCustomQuestions<\/td>\nThe display name for the custom question<\/td>\n<\/tr>\n
answerInputType<\/strong><\/td>\nbookingCustomQuestions<\/td>\nThe answer type. The data type is graph.answerInputType. Supported values are radio button and text.<\/td>\n<\/tr>\n
answerOptions<\/strong><\/td>\nbookingCustomQuestions<\/td>\nThis field is applicable if the answer type is radio button. This is a collection of strings<\/td>\n<\/tr>\n
\u00a0<\/strong><\/td>\n<\/td>\n<\/td>\n<\/tr>\n
customQuestions<\/strong><\/td>\nbookingService<\/td>\nCollection of bookingQuestionAssignment for the service<\/td>\n<\/tr>\n
customQuestionAnswers<\/strong><\/td>\nbookingAppointment<\/td>\nCollection of bookingQuestionAnswer. This collection is an attribute within a complex type bookingCustomerInformation, which itself is present in bookingAppointment.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
 <\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n
Attribute<\/strong><\/td>\nComplexType<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
questionId<\/strong><\/td>\nbookingQuestionAssignment<\/p>\n
 <\/td>\n
The id of the custom question which is being attached to the service.<\/td>\n<\/tr>\n
isRequired<\/strong><\/td>\nbookingQuestionAssignment<\/td>\nIndicates if the custom question answer is mandatory in the service<\/td>\n<\/tr>\n
questionId<\/strong><\/td>\nbookingQuestionAnswer<\/td>\nThe is of custom question<\/td>\n<\/tr>\n
question<\/strong><\/td>\nbookingQuestionAnswer<\/td>\nThe display name of the question when the appointment was created<\/td>\n<\/tr>\n
answerInputType<\/strong><\/td>\nbookingQuestionAnswer<\/td>\nThe answer Input type of the question at the time of creation of appointment<\/td>\n<\/tr>\n
answerOptions<\/strong><\/td>\nbookingQuestionAnswer<\/td>\nThe possible answer options of the question at the time of creation of an appointment<\/td>\n<\/tr>\n
isRequired<\/strong><\/td>\nbookingQuestionAnswer<\/td>\nIf the answer is mandatory. It reflects the value at the time of appointment creation<\/td>\n<\/tr>\n
answer<\/strong><\/td>\nbookingQuestionAnswer<\/td>\nThe answer for the question<\/td>\n<\/tr>\n
selectedOptions<\/strong><\/td>\nbookingQuestionAnswer<\/td>\nThe selected option for the question if the question was of non-text type<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
 <\/p>\n
Appointments with more than one customer (group appointments)<\/h3>\n
In the web app we support appointments in which more than one customer can attend. We call these appointments \u201cgroup appointments\u201d. One can set a service to support group appointments by increasing the count of attribute maximumAttendeesCount. In the bookingAppointment resource type, maximumAttendeesCount, indicates the maximum number of allowed attendees and is inherited from the same-named attribute in the bookingService resource type. The filledAttendeesCount attribute denotes the current number of customers in an appointment.<\/p>\n\n\n\n\n\n\n
Attribute<\/strong><\/td>\nResource Type<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
maximumAttendeesCount<\/strong><\/td>\nbookingService<\/td>\nMax allowed number of customers in an appointment<\/td>\n<\/tr>\n
maximumAttendeesCount<\/strong><\/td>\nbookingAppointment<\/td>\nMax allowed number of customers in an appointment<\/td>\n<\/tr>\n
filledAttendeesCount<\/strong><\/td>\nbookingAppointment<\/td>\nCurrent number of customers in an appointment<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
 <\/p>\n
Changes in customer information in a bookingAppointment resource type<\/h4>\n
Customer information was available at the root level in the appointment object. Since a list of customers is now supported, the information will be within a complex type. Customer information for appointments in which maximumAttendeesCount is 1 will continue to also exist at the root level in beta- however it will be deprecated.<\/p>\n
The difference can be seen in the two code snippets below.<\/p>\n
Old structure of bookingAppointment<\/strong><\/p>\n
Content-type: application\/json\r\n\r\n{\r\n    \"@odata.context\": \"https:\/\/graph.microsoft.com\/beta\/$metadata#bookingBusinesses('Contosolunchdelivery%40M365B489948.onmicrosoft.com')\/appointments\/$entity\",\r\n    \"id\": \"AAMkADKnAAA=\",\r\n    \"selfServiceAppointmentId\": \"00000000-0000-0000-0000-000000000000\",\r\n    \"customerId\": \"7ed53fa5-9ef2-4f2f-975b-27447440bc09\",\r\n    \"customerName\": \"Jordan Miller\",\r\n    \"customerEmailAddress\": \"jordanm@contoso.com\",\r\n    \"customerPhone\": \"213-555-0199\",\r\n    \"customerNotes\": null,\r\n    \"serviceId\": \"57da6774-a087-4d69-b0e6-6fb82c339976\",\r\n    \"serviceName\": \"Catered bento\",\r\n  ...\r\n  ...     \r\n  ...\r\n}<\/pre>\n
 <\/p>\n
New structure of bookingAppointment<\/strong><\/p>\n
Content-type: application\/json\r\n\r\n{\r\n    \"@odata.context\": \"https:\/\/graph.microsoft.com\/beta\/$metadata#bookingBusinesses('Contosolunchdelivery%40M365B489948.onmicrosoft.com')\/appointments\/$entity\",\r\n    \"id\": \"AAMkADKnAAA=\",\r\n    \"selfServiceAppointmentId\": \"00000000-0000-0000-0000-000000000000\",\r\n    ...\r\n    ...\r\n    ...\r\n   \r\n    \"customers\": [\r\n        {\r\n            \"customerId\": \"7ed53fa5-9ef2-4f2f-975b-27447440bc09\",\r\n            \"customerName\": \"Jordan Miller\",\r\n            \"customerEmailAddress\": \"jordanm@contoso.com\",\r\n            \"customerPhone\": \"213-555-0199\",\r\n            \"customerNotes\": \"notes\",\r\n            \"customQuestionAnswers\": [\r\n                {\r\n                    \"questionId\": \"75fc2eaf-624f-40b2-a289-63e51a56fcf2\",\r\n                    \"question\": \"What's your favourite food\",\r\n                    \"answerInputType\": \"radioButton\",\r\n                    \"answerOptions\": [\r\n                        \"KFC\",\r\n                        \"McDonald's\",\r\n                        \"BurgerKing\"\r\n                    ],\r\n                    \"isRequired\": true,\r\n                    \"answer\": \"KFC\",\r\n                    \"selectedOptions\": [\"KFC\"]\r\n                }\r\n            ],\r\n            \"customerLocation\": {\r\n                \"displayName\": \"home\",\r\n                \"locationEmailAddress\": null,\r\n                \"locationUri\": \"\",\r\n                \"locationType\": null,\r\n                \"uniqueId\": null,\r\n                \"uniqueIdType\": null,\r\n                \"address\": {\r\n                    \"type\": \"home\",\r\n                    \"postOfficeBox\": \"\",\r\n                    \"street\": \"\",\r\n                    \"city\": \"\",\r\n                    \"state\": \"\",\r\n                    \"countryOrRegion\": \"\",\r\n                    \"postalCode\": \"\"\r\n                },\r\n                \"coordinates\": {\r\n                    \"altitude\": null,\r\n                    \"latitude\": null,\r\n                    \"longitude\": null,\r\n                    \"accuracy\": null,\r\n                    \"altitudeAccuracy\": null\r\n                }\r\n            }\r\n        }\r\n    ]\r\n    ...\r\n    ...\r\n}<\/pre>\n
\u00a0<\/strong><\/p>\n
The new complex type <\/strong><\/h4>\n
The complex type is called\u00a0bookingCustomerInformation. The \u201ccustomers\u201d attribute within appointment is a collection of this type.<\/p>\n\n\n\n\n\n\n\n\n\n\n
Attribute<\/strong><\/td>\nComplex Type<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
Id<\/strong><\/td>\nbookingCustomerInformation<\/td>\nThe id of the customer<\/td>\n<\/tr>\n
name<\/strong><\/td>\nbookingCustomerInformation<\/td>\nThe name of the customer<\/td>\n<\/tr>\n
emailAddress<\/strong><\/td>\nbookingCustomerInformation<\/td>\nThe email address of the customer<\/td>\n<\/tr>\n
phone<\/strong><\/td>\nbookingCustomerInformation<\/td>\nThe phone number of the customer<\/td>\n<\/tr>\n
notes<\/strong><\/td>\nbookingCustomerInformation<\/td>\nThe notes of the customer<\/td>\n<\/tr>\n
location<\/strong><\/td>\nbookingCustomerInformation<\/td>\nThe address of the customer. Location is of type physicalAddress. However only the \u201cother\u201d address type is supported.<\/td>\n<\/tr>\n
timeZone<\/strong><\/td>\nbookingCustomerInformation<\/td>\nThe timeZone of the customer<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
 <\/p>\n
We hope that these new features will help your custom applications be more comprehensive and robust. Please give us feedback and keep reaching out to us with your use cases and requests. Check out this link<\/a> to find resources that will help you get started.<\/p>\n
Stay tuned and keep following our blog<\/a> for updates on our APIs.<\/p>\n
Happy coding!<\/p>\n","protected":false},"excerpt":{"rendered":"
We have launched some key new features to continue providing a booking infrastructure through the Bookings APIs so that customers can build robust customized solutions. <\/p>\n","protected":false},"author":69077,"featured_media":25159,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3],"tags":[160],"class_list":["post-9166","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-graph","tag-bookings-api"],"acf":[],"blog_post_summary":"
We have launched some key new features to continue providing a booking infrastructure through the Bookings APIs so that customers can build robust customized solutions. <\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/9166","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69077"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=9166"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/9166\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=9166"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=9166"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=9166"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}