Graph Calling SDK

Important

Documentation has moved here. This site will be decommissioned shortly.

Introduction

The Graph Calling SDK simplifies the creation of calling and meetings bots that use the Microsoft Graph Calling APIs. The Graph Calling SDK provides the functionality to manage states of resources in memory and takes care of tasks like call setup and media session establishment. The Graph Calling SDK provides interfaces for bot service-to-service interactions with calls and meetings, including an optional Media Extension SDK that enables a bot developer to host media locally and gain access to low level Audio/Video sockets and media streams.

SDK

The Graph Calling SDK is built on top of the Microsoft Graph API and distributed as NuGet packages.

Example Scenarios

To illustrate functionality of the Graph Calling SDK, the below examples demonstrate 2 common scenarios: how to make an outbound call to a Microsoft Teams user and how to join an existing Microsoft Teams meeting.

Making an Outbound Call

Assuming a bot has been properly registered and deployed, the IStatefulClient configured and built.

The bot needs to create the Call object with the corresponding parameters and pass the object to the CallCollectionExtensions.AddAsync method as follows:

var call = new Call
{
    Subject = "**Subject**",
    Targets = new List<ParticipantInfo>
                {
                    new InvitationParticipantInfo
                    {
                        Identity = new IdentitySet
                        {
                            User = new Identity
                            {
                                Id = "**Target's AAD ObjectId GUID**"
                            },
                        },
                    }
                }
};

var mediaSession = this.Client.CreateMediaSession(**custom media session settings**);

var statefulCall = await this.Client.Calls().AddAsync(call, mediaSession);

SDK will store the state of the call in memory after calling AddAsync. The returned statefulCall above contains the call Id set by the service.

Making an Outbound Call to Join an Existing Microsoft Teams Meeting

The above example shows how to create an outbound call to single or multiple participants to create a new conversation. If the bot needs to join an existing conversation, the SDK provides an overload of AddAsync that takes JoinMeetingParameters as input. The bot needs to create the JoinMeetingParameters object with the corresponding meeting parameters and pass the object to the CallCollectionExtensions.AddAsync method as follows:

var mediaSession = this.Client.CreateMediaSession(**custom media session settings**);
var joinCallParameters = new JoinMeetingParameters(
new ChatInfo
{
    MessageId = "**Message Id**",
    ThreadId = "**Thread Id**",
    ReplyChainMessageId = "**Reply Chain Message Id**"
},
new OrganizerMeetingInfo
{
    Organizer = new IdentitySet
                {
                    User = new Identity
                    {
                        Id = "**Meeting Organizer's AAD ObjectId GUID**"
                    },
                },    
    TenantId = **OrganizerId Guid**
},
mediaSession);

var statefulCall = await this.Client.Calls().AddAsync(joinCallParameters);

SDK will store the state of the call in memory after calling AddAsync. The returned statefulCall above contains the callId set by the service.

State Management

Graph Calling SDK can be used to store state of all resources of the call in memory. This has 2 implications:

1. The instance hosting the call needs to be up throughout the lifetime of the call.
2. Any subsequent asynchronous notifications triggered by the service need to be directed to the instance hosting the call.

Any bot that hosts its own media stack needs to be built using the Graph Calling SDK given that the media stream has a requirement that it needs to persist in memory throughout the lifetime of the call.