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.

SMS notifications

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.  Recently, 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.

SMS notifications can be enabled for a bookingService and at a bookingAppointment level as well, with the bookingAppointment level setting taking precedence.

Online meetings

Support for online meetings was launched for our web and Team’s 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’s meeting link will be auto generated. This link is part of the appointment resource type and can be accessed via APIs.

Staff and customer time zones

The bookingAppointment resource type has an attribute for customer timezone and the bookingStaffMember resource type has an attribute for the staff timezone.

Enhanced bookingCustomer resource type

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.

Custom questions

Custom questions are one of the key features of Bookings. It can be used to collect additional information in an appointment.

Custom questions are created for a ‘bookingBusiness’ 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.

CRUD operations can be done on custom questions via APIs.

Example of CRUD operations for custom questions

Retrieve a custom question object

GET https://graph.microsoft.com/beta/bookingBusinesses/<businessId>/customQuestions/<questionId>

HTTP/1.1 200 OK
{
  "id": "3bc6fde0-4ad3-445d-ab17-0fc15dba0774",
  "displayName": "What is your age",
  "answerInputType": "text",
  "answerOptions": []
}

List all custom questions in a business

GET https://graph.microsoft.com/beta/bookingBusinesses/<businessId>/customQuestions

HTTP/1.1 200 OK
[
  {
    "id": "",
    "displayName": "What’s your faviourite color",
    "answerInputType": "text",
    "answerOptions": []
  },
  {
    "id": "",
    "displayName": "What do you want to get from this session?",
    "answerInputType": "text",
    "answerOptions": []
  }
]

Create a custom question

POST https://graph.microsoft.com/beta/bookingBusinesses/<businessId>/customQuestions
{
  "displayName": "What is your age",
  "answerInputType": "text",
  "answerOptions": []
}

HTTP/1.1 201 Created
{
  "id": "3bc6fde0-4ad3-445d-ab17-0fc15dba0774",
  "displayName": "What is your age",
  "answerInputType": "text",
  "answerOptions": []
}

Update a custom question

PATCH https://graph.microsoft.com/beta/bookingBusinesses/<businessId>/customQuestions/<questionId>
{
  "displayName": "What is your date of Birth"
}

HTTP/1.1 204 No Content

DELETE https://graph.microsoft.com/beta/bookingBusinesses/<businessId>/customQuestions/<questionId>

HTTP/1.1 204 NO CONTENT

Custom questions in a bookingService

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 “isRequired” field indicates if it is mandatory to have a value for this custom field in an appointment.

POST https://graph.microsoft.com/beta/bookingBusinesses/Contosolunchdelivery@M365B489948.onmicrosoft.com/services
Content-type: application/json

{
    "@odata.type":"#microsoft.graph.bookingService",
    ..
    ..
    ..
    
    "customQuestions": [
        {
            "questionId": "75fc2eaf-624f-40b2-a289-63e51a56fcf2",
            "isRequired": true
        },
        {
            "questionId": "b90e7840-4c0c-430f-b96f-74ad9d2f64f7",
            "isRequired": false
        }
    ]
}

Custom questions in an appointment

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.

Here, a snippet is shown where an appointment is being created with custom questions.

POST https://graph.microsoft.com/beta/bookingBusinesses/Contosolunchdelivery@M365B489948.onmicrosoft.com/appointments
Content-type: application/json

{
    "@odata.type":"#microsoft.graph.bookingAppointment",
     ...
     ...
     ...
    "customers": [
        {
            "@odata.type":"#microsoft.graph.bookingCustomerInformation",
            "customerName":"Jordan Miller",
           
           ...
           ...
            "customQuestionAnswers": [
                {
                    "questionId": "75fc2eaf-624f-40b2-a289-63e51a56fcf2",
                    "answer": "Bread",
                    "selectedOptions": ["Bread"]
                }
            ],
             ...
             ...
            }
        }
    ],
    ...
    ...
    ...

}

Here is another example where an appointment is being retrieved

GET https://graph.microsoft.com/beta/bookingBusinesses/Contosolunchdelivery@M365B489948.onmicrosoft.com/appointments/AAMkADKnAAA=

Response

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#bookingBusinesses('Contosolunchdelivery%40M365B489948.onmicrosoft.com')/appointments/$entity",
    "id": "AAMkADKnAAA=",
    "selfServiceAppointmentId": "00000000-0000-0000-0000-000000000000",
    ...
    ...
    "customers": [
        {
            "customerId": "7ed53fa5-9ef2-4f2f-975b-27447440bc09",
            "customerName": "Jordan Miller",
            ...
            ...
            "customQuestionAnswers": [
                {
                    "questionId": "75fc2eaf-624f-40b2-a289-63e51a56fcf2",
                    "question": "What's your favourite food",
                    "answerInputType": "radioButton",
                    "answerOptions": [
                        "Banana Bread",
                        "Apple Pie",
                        "Cheese Cake"
                    ],
                    "isRequired": true,
                    "answer": "Apple Pie",
                    "selectedOptions": ["Apple Pie"]
                }
            ],
            ...
            ...
            }
        }
    ]
}

Attributes and complex types of custom questions

Appointments with more than one customer (group appointments)

In the web app we support appointments in which more than one customer can attend. We call these appointments “group appointments”. 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.

Changes in customer information in a bookingAppointment resource type

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.

The difference can be seen in the two code snippets below.

Old structure of bookingAppointment

Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#bookingBusinesses('Contosolunchdelivery%40M365B489948.onmicrosoft.com')/appointments/$entity",
    "id": "AAMkADKnAAA=",
    "selfServiceAppointmentId": "00000000-0000-0000-0000-000000000000",
    "customerId": "7ed53fa5-9ef2-4f2f-975b-27447440bc09",
    "customerName": "Jordan Miller",
    "customerEmailAddress": "jordanm@contoso.com",
    "customerPhone": "213-555-0199",
    "customerNotes": null,
    "serviceId": "57da6774-a087-4d69-b0e6-6fb82c339976",
    "serviceName": "Catered bento",
  ...
  ...     
  ...
}

New structure of bookingAppointment

Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#bookingBusinesses('Contosolunchdelivery%40M365B489948.onmicrosoft.com')/appointments/$entity",
    "id": "AAMkADKnAAA=",
    "selfServiceAppointmentId": "00000000-0000-0000-0000-000000000000",
    ...
    ...
    ...
   
    "customers": [
        {
            "customerId": "7ed53fa5-9ef2-4f2f-975b-27447440bc09",
            "customerName": "Jordan Miller",
            "customerEmailAddress": "jordanm@contoso.com",
            "customerPhone": "213-555-0199",
            "customerNotes": "notes",
            "customQuestionAnswers": [
                {
                    "questionId": "75fc2eaf-624f-40b2-a289-63e51a56fcf2",
                    "question": "What's your favourite food",
                    "answerInputType": "radioButton",
                    "answerOptions": [
                        "KFC",
                        "McDonald's",
                        "BurgerKing"
                    ],
                    "isRequired": true,
                    "answer": "KFC",
                    "selectedOptions": ["KFC"]
                }
            ],
            "customerLocation": {
                "displayName": "home",
                "locationEmailAddress": null,
                "locationUri": "",
                "locationType": null,
                "uniqueId": null,
                "uniqueIdType": null,
                "address": {
                    "type": "home",
                    "postOfficeBox": "",
                    "street": "",
                    "city": "",
                    "state": "",
                    "countryOrRegion": "",
                    "postalCode": ""
                },
                "coordinates": {
                    "altitude": null,
                    "latitude": null,
                    "longitude": null,
                    "accuracy": null,
                    "altitudeAccuracy": null
                }
            }
        }
    ]
    ...
    ...
}

The new complex type

The complex type is called bookingCustomerInformation. The “customers” attribute within appointment is a collection of this type.

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 to find resources that will help you get started.

Stay tuned and keep following our blog for updates on our APIs.

Happy coding!