Create call
Namespace: microsoft.graph
Create call enables your bot to create a new outgoing peer-to-peer or group call, or join an existing meeting. You will need to register the calling bot and go through the list of permissions needed as mentioned below.
Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.
| Permission type | Permissions (from least to most privileged) |
|---|---|
| Delegated (work or school account) | Not Supported |
| Delegated (personal Microsoft account) | Not Supported |
| Application | Calls.JoinGroupCallsasGuest.All, Calls.JoinGroupCalls.All, Calls.Initiate.All, Calls.InitiateGroupCalls.All |
Note: For a call with app-hosted media, you need the Calls.AccessMedia.All permission in addition to one of the permissions listed in the table above.
HTTP request
POST /communications/calls
Request headers
| Name | Description |
|---|---|
| Authorization | Bearer {token}. Required. |
| Content-type | application/json. Required. |
Request body
In the request body, supply a JSON representation of a call object.
Response
If successful, this method returns a 201 Created response code and a call object in the response body.
Examples
Example 1: Create peer-to-peer VoIP call with service hosted media
Note: This call needs the Calls.Initiate.All permission.
Request
The following example shows the request which makes a peer-to-peer call between the bot and the specified user. In this example, the media is hosted by the service. The values of authorization token, callback URL, application ID, application name, user ID, user name, and tenant ID must be replaced with actual values to make the example work.
POST https://graph.microsoft.com/v1.0/communications/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"callbackUri": "https://bot.contoso.com/callback",
"targets": [
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "John",
"id": "112f7296-5fa4-42ca-bae8-6a692b15d4b8"
}
}
}
],
"requestedModalities": [
"audio"
],
"mediaConfig": {
"@odata.type": "#microsoft.graph.serviceHostedMediaConfig"
}
}
Response
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Location: https://graph.microsoft.com/v1.0/communications/calls/2e1a0b00-2db4-4022-9570-243709c565ab
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"state": "establishing",
"direction": "outgoing",
"callbackUri": "https://bot.contoso.com/callback",
"callChainId": "d8217646-3110-40b1-bae6-e9ac6c3a9f74",
"source": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"application": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "Calling Bot",
"id": "2891555a-92ff-42e6-80fa-6e1300c6b5c6"
}
},
"countryCode": null,
"endpointType": null,
"region": null,
"languageId": null
},
"targets": [
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "John",
"id": "112f7296-5fa4-42ca-bae8-6a692b15d4b8"
}
},
"endpointType": null,
"replacesCallId": null,
}
],
"requestedModalities": [
"audio"
],
"mediaConfig": {
"@odata.type": "#microsoft.graph.serviceHostedMediaConfig",
"preFetchMedia": [
{
"uri": "https://cdn.contoso.com/beep.wav",
"resourceId": "f8971b04-b53e-418c-9222-c82ce681a582"
},
{
"uri": "https://cdn.contoso.com/cool.wav",
"resourceId": "86dc814b-c172-4428-9112-60f8ecae1edb"
}
],
},
"myParticipantId": "499ff390-7a72-40e8-83a0-8fac6295ae7e",
"id": "2e1a0b00-2db4-4022-9570-243709c565ab",
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#app/calls/$entity",
"subject": null,
"ringingTimeoutInSeconds": null,
"mediaState": null,
"resultInfo": null,
"answeredBy": null,
"chatInfo": null,
"meetingInfo": null,
"transcription": null,
"toneInfo": null
}
Notification - establishing
POST https://bot.contoso.com/callback
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "updated",
"resourceUrl": "/communications/calls/2e1a0b00-2db4-4022-9570-243709c565ab",
"callbackUri": "https://bot.contoso.com/callback",
"resourceData": {
"@odata.type": "#microsoft.graph.call",
"state": "establishing",
"id": "2e1a0b00-2db4-4022-9570-243709c565ab"
}
}
]
}
Notification - established
POST https://bot.contoso.com/callback
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "updated",
"resourceUrl": "/communications/calls/2e1a0b00-b3c5-4b0f-99b3-c133bc1e6116",
"callbackUri": "https://bot.contoso.com/callback",
"resourceData": {
"@odata.type": "#microsoft.graph.call",
"state": "established",
"direction": "outgoing",
"id": "2e1a0b00-b3c5-4b0f-99b3-c133bc1e6116"
}
}
]
}
Example 2: Create peer-to-peer VoIP call with application hosted media
Note: This example needs Calls.Initiate.All and Calls.AccessMedia.All permissions.
Request
The following example shows the request which makes a peer-to-peer call between the bot and the specified user. In this example the media is hosted locally by the application. The values of authorization token, callback url, application id, application name, user id, user name and tenant id must be replaced with actual values to make the example work.
POST https://graph.microsoft.com/v1.0/communications/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"callbackUri": "https://bot.contoso.com/callback",
"source": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"application": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "Calling Bot",
"id": "2891555a-92ff-42e6-80fa-6e1300c6b5c6"
}
},
"region": null,
"languageId": null
},
"targets": [
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "John",
"id": "112f7296-5fa4-42ca-bae8-6a692b15d4b8"
}
}
}
],
"requestedModalities": [
"audio"
],
"mediaConfig": {
"@odata.type": "#microsoft.graph.appHostedMediaConfig",
"blob": "<Media Session Configuration>"
}
}
Note: For peer-to-peer calls, the expected notifications are for call state changes only.
Response
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Location: https://graph.microsoft.com/v1.0/communications/calls/2e1a0b00-2db4-4022-9570-243709c565ab
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"state": "establishing",
"direction": "outgoing",
"callbackUri": "https://bot.contoso.com/callback",
"callChainId": "d8217646-3110-40b1-bae6-e9ac6c3a9f74",
"source": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"application": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "Calling Bot",
"id": "2891555a-92ff-42e6-80fa-6e1300c6b5c6"
}
},
"region": null,
"languageId": null
},
"targets": [
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "John",
"id": "112f7296-5fa4-42ca-bae8-6a692b15d4b8"
}
}
}
],
"requestedModalities": [
"audio"
],
"mediaConfig": {
"@odata.type": "#microsoft.graph.appHostedMediaConfig",
"blob": "<Media Session Configuration>",
},
"myParticipantId": "499ff390-7a72-40e8-83a0-8fac6295ae7e",
"id": "2e1a0b00-2db4-4022-9570-243709c565ab",
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#app/calls/$entity",
"subject": null,
"ringingTimeoutInSeconds": null,
"mediaState": null,
"resultInfo": null,
"answeredBy": null,
"chatInfo": null,
"meetingInfo": null,
"transcription": null,
"toneInfo": null
}
Example 3: Create a group call with service hosted media
This supports up to 5 VoIP users. The example shows how to create a group call with two VoIP users.
Note: This example call needs the
Calls.InitiateGroupCalls.Allpermission. The group call created doesn't support chat or recording.
Request
POST https://graph.microsoft.com/v1.0/communications/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"direction": "outgoing",
"subject": "Create a group call with service hosted media",
"callbackUri": "https://bot.contoso.com/callback",
"source": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"application": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "TestBot",
"id": "dd3885da-f9ab-486b-bfae-85de3d445555"
}
}
},
"targets": [
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "user1",
"id": "98da8a1a-1b87-452c-a713-65d3f10b5555"
}
}
},
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "user2",
"id": "bf5aae9a-d11d-47a8-93b1-782504c95555"
}
}
}
],
"requestedModalities": [
"audio"
],
"mediaConfig": {
"@odata.type": "#microsoft.graph.serviceHostedMediaConfig",
"removeFromDefaultAudioGroup": false
}
}
Example 4: Create a group call with application hosted media
This supports up to 5 VoIP users. The example shows how to create a group call with two VoIP users.
Note: This example call needs the
Calls.InitiateGroupCalls.Allpermission. The group call created doesn't support chat or recording.
Request
POST https://graph.microsoft.com/v1.0/communications/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"direction": "outgoing",
"subject": "Create a group call with application hosted media",
"callbackUri": "https://bot.contoso.com/callback",
"source": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"application": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "TestBot",
"id": "dd3885da-f9ab-486b-bfae-85de3d445555"
}
}
},
"targets": [
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "user1",
"id": "98da8a1a-1b87-452c-a713-65d3f10b5555"
}
}
},
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "user2",
"id": "bf5aae9a-d11d-47a8-93b1-782504c95555"
}
}
}
],
"requestedModalities": [
"audio"
],
"mediaConfig": {
"@odata.type": "#microsoft.graph.appHostedMediaConfig",
"removeFromDefaultAudioGroup": false
}
}
Example 5: Join scheduled meeting with service hosted media
To join the scheduled meeting we will need to get the thread id, message id, organizer id and the tenant id in which the meeting is scheduled. This information can be obtained from the Get Online Meetings API (VTC-based meetings only).
The values of authorization token, callback url, application id, application name, user id, user name and tenant id must be replaced along with the details obtained from Get Online Meetings API (VTC-based meetings only) with actual values to make the example work.
Note: This example needs the
Calls.JoinGroupCalls.Allpermission.
Request
POST https://graph.microsoft.com/v1.0/communications/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"callbackUri": "https://bot.contoso.com/callback",
"requestedModalities": [
"audio"
],
"mediaConfig": {
"@odata.type": "#microsoft.graph.serviceHostedMediaConfig",
"preFetchMedia": [
{
"uri": "https://cdn.contoso.com/beep.wav",
"resourceId": "f8971b04-b53e-418c-9222-c82ce681a582"
},
{
"uri": "https://cdn.contoso.com/cool.wav",
"resourceId": "86dc814b-c172-4428-9112-60f8ecae1edb"
}
],
},
"chatInfo": {
"@odata.type": "#microsoft.graph.chatInfo",
"threadId": "19:meeting_Win6Ydo4wsMijFjZS00ZGVjLTk5MGUtOTRjNWY2NmNkYTFm@thread.v2",
"messageId": "0"
},
"meetingInfo": {
"@odata.type": "#microsoft.graph.organizerMeetingInfo",
"organizer": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"id": "5810cede-f3cc-42eb-b2c1-e9bd5d53ec96",
"displayName": "Bob",
"tenantId":"86dc81db-c112-4228-9222-63f3esaa1edb"
}
},
"allowConversationWithoutHost": true
},
"tenantId":"86dc81db-c112-4228-9222-63f3esaa1edb"
}
Response
HTTP/1.1 201 Created
Location: https://graph.microsoft.com/v1.0/communications/calls/2f1a1100-b174-40a0-aba7-0b405e01ed92
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"state": "establishing",
"direction": "outgoing",
"callbackUri": "https://bot.contoso.com/callback",
"callChainId": "d8217646-3110-40b1-bae6-e9ac6c3a9f74",
"source": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"application": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "Calling Bot",
"id": "2891555a-92ff-42e6-80fa-6e1300c6b5c6"
}
},
"region": null,
"languageId": null
},
"targets": [],
"requestedModalities": [
"audio"
],
"mediaConfig": {
"@odata.type": "#microsoft.graph.serviceHostedMediaConfig",
"preFetchMedia": [
{
"uri": "https://cdn.contoso.com/beep.wav",
"resourceId": "f8971b04-b53e-418c-9222-c82ce681a582"
},
{
"uri": "https://cdn.contoso.com/cool.wav",
"resourceId": "86dc814b-c172-4428-9112-60f8ecae1edb"
}
],
},
"chatInfo": {
"@odata.type": "#microsoft.graph.chatInfo",
"threadId": "19:meeting_Win6Ydo4wsMijFjZS00ZGVjLTk5MGUtOTRjNWY2NmNkYTFm@thread.v2",
"messageId": "0",
"replyChainMessageId": null
},
"meetingInfo": {
"@odata.type": "#microsoft.graph.organizerMeetingInfo",
"organizer": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"id": "5810cede-f3cc-42eb-b2c1-e9bd5d53ec96",
"displayName": "Bob"
}
},
"allowConversationWithoutHost": true
},
"transcription": null,
"myParticipantId": "05491616-385f-44a8-9974-18cc5f9933c1",
"id": "2f1a1100-b174-40a0-aba7-0b405e01ed92",
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#app/calls/$entity",
"ringingTimeoutInSeconds": null,
"mediaState": null,
"subject": null,
"resultInfo": null,
"answeredBy": null,
"toneInfo": null
}
Notification - establishing
POST https://bot.contoso.com/callback
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "updated",
"resourceUrl": "/communications/calls/2f1a1100-b174-40a0-aba7-0b405e01ed92",
"callbackUri": "https://bot.contoso.com/callback",
"resourceData": {
"@odata.type": "#microsoft.graph.call",
"state": "establishing",
"chatInfo": {
"@odata.type": "#microsoft.graph.chatInfo",
"threadId": "19:meeting_Win6Ydo4wsMijFjZS00ZGVjLTk5MGUtOTRjNWY2NmNkYTFm@thread.v2",
"messageId": "0"
},
"meetingInfo": {
"@odata.type": "#microsoft.graph.organizerMeetingInfo",
"organizer": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"id": "5810cede-f3cc-42eb-b2c1-e9bd5d53ec96",
"displayName": "Bob"
}
},
"allowConversationWithoutHost": true
},
"id": "2f1a1100-b174-40a0-aba7-0b405e01ed92"
}
}
]
}
Notification - established
POST https://bot.contoso.com/callback
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "updated",
"resourceUrl": "/communications/calls/2f1a1100-b174-40a0-aba7-0b405e01ed92",
"callbackUri": "https://bot.contoso.com/callback",
"resourceData": {
"@odata.type": "#microsoft.graph.call",
"state": "established",
"chatInfo": {
"@odata.type": "#microsoft.graph.chatInfo",
"threadId": "19:meeting_Win6Ydo4wsMijFjZS00ZGVjLTk5MGUtOTRjNWY2NmNkYTFm@thread.v2",
"messageId": "0"
},
"meetingInfo": {
"@odata.type": "#microsoft.graph.organizerMeetingInfo",
"organizer": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"id": "5810cede-f3cc-42eb-b2c1-e9bd5d53ec96",
"displayName": "Bob"
}
},
"allowConversationWithoutHost": true
},
"id": "2f1a1100-b174-40a0-aba7-0b405e01ed92"
}
}
]
}
Notification - roster
POST https://bot.contoso.com/callback
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "updated",
"resourceUrl": "/communications/calls/2f1a1100-b174-40a0-aba7-0b405e01ed92/participants",
"callbackUri": "https://bot.contoso.com/callback",
"resourceData": [
{
"@odata.type": "#microsoft.graph.participant",
"info": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "John",
"id": "112f7296-5fa4-42ca-bae8-6a692b15d4b8"
}
},
"languageId": "en-US"
},
"mediaStreams": [
{
"@odata.type": "#microsoft.graph.mediaStream",
"mediaType": "audio",
"sourceId": "1",
"direction": "sendReceive",
"serverMuted": false
},
{
"@odata.type": "#microsoft.graph.mediaStream",
"mediaType": "video",
"sourceId": "2",
"direction": "receiveOnly",
"serverMuted": false
},
{
"@odata.type": "#microsoft.graph.mediaStream",
"mediaType": "videoBasedScreenSharing",
"sourceId": "8",
"direction": "receiveOnly",
"serverMuted": false
}
],
"isMuted": true,
"isInLobby": false,
"id": "0d7664b6-6432-43ed-8d27-d9e7adec188c"
},
{
"@odata.type": "#microsoft.graph.participant",
"info": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"application": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "Calling Bot",
"id": "2891555a-92ff-42e6-80fa-6e1300c6b5c6"
}
}
},
"mediaStreams": [
{
"@odata.type": "#microsoft.graph.mediaStream",
"mediaType": "audio",
"sourceId": "10",
"direction": "sendReceive",
"serverMuted": false
}
],
"isMuted": false,
"isInLobby": false,
"id": "05491616-385f-44a8-9974-18cc5f9933c1"
}
]
}
]
}
Note: For join meeting scenarios apart from call state notifications, we receive roster notifications.
Example 6: Join scheduled meeting with application hosted media
Update the media config with the AppHostedMediaConfig as shown below.
POST https://graph.microsoft.com/v1.0/communications/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"direction": "outgoing",
"callbackUri": "https://bot.contoso.com/callback",
"requestedModalities": [
"audio"
],
"mediaConfig": {
"@odata.type": "#microsoft.graph.appHostedMediaConfig"
},
"chatInfo": {
"@odata.type": "#microsoft.graph.chatInfo",
"threadId": "19:meeting_Win6Ydo4wsMijFjZS00ZGVjLTk5MGUtOTRjNWY2NmNkYTFm@thread.v2",
"messageId": "0"
},
"meetingInfo": {
"@odata.type": "#microsoft.graph.organizerMeetingInfo",
"organizer": {
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"id": "5810cede-f3cc-42eb-b2c1-e9bd5d53ec96",
"tenantId": "aa67bd4c-8475-432d-bd41-39f255720e0a",
"displayName": "Bob"
}
},
"allowConversationWithoutHost": true
},
"tenantId": "aa67bd4c-8475-432d-bd41-39f255720e0a"
}
Example 7: Create peer-to-peer PSTN call with service hosted media
Note: This call requires the Calls.Initiate.All permission.
This call requires an application instance with a PSTN number assigned. For details, see Assign a phone number to your bot.
Request
The following example shows the request to make a peer-to-peer call between the bot and a PSTN number. In this example, the media is hosted by the service. The values of authorization token, callback URL, application instance ID, application instance display name, phone ID and tenant ID must be replaced with actual values to make the example work.
Note: Application instance ID is the object ID of application instance. The application ID that application instance links to should match the one in authorization token. Phone ID is the phone number in E.164 format.
POST https://graph.microsoft.com/v1.0/communications/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"callbackUri": "https://bot.contoso.com/callback",
"source": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"applicationInstance": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "Calling Bot",
"id": "3d913abb-aec0-4964-8fa6-3c6850c4f278"
},
},
"countryCode": null,
"endpointType": null,
"region": null,
"languageId": null
},
"targets": [
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"phone": {
"@odata.type": "#microsoft.graph.identity",
"id": "+12345678901"
}
}
}
],
"requestedModalities": [
"audio"
],
"mediaConfig": {
"@odata.type": "#microsoft.graph.serviceHostedMediaConfig"
},
"tenantId": "aa67bd4c-8475-432d-bd41-39f255720e0a"
}
Response
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Location: https://graph.microsoft.com/v1.0/communications/calls/2e1a0b00-2db4-4022-9570-243709c565ab
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"state": "establishing",
"direction": "outgoing",
"callbackUri": "https://bot.contoso.com/callback",
"callChainId": "d8217646-3110-40b1-bae6-e9ac6c3a9f74",
"callRoutes": [],
"source": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"applicationInstance": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "Calling Bot",
"id": "3d913abb-aec0-4964-8fa6-3c6850c4f278"
},
},
"countryCode": null,
"endpointType": null,
"region": null,
"languageId": null
},
"targets": [
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"phone": {
"@odata.type": "#microsoft.graph.identity",
"id": "+12345678901"
}
},
"endpointType": null,
"region": null,
"replacesCallId": null,
"languageId": null
}
],
"requestedModalities": [
"audio"
],
"activeModalities": [],
"mediaConfig": {
"@odata.type": "#microsoft.graph.serviceHostedMediaConfig",
"preFetchMedia": [
{
"uri": "https://cdn.contoso.com/beep.wav",
"resourceId": "f8971b04-b53e-418c-9222-c82ce681a582"
},
{
"uri": "https://cdn.contoso.com/cool.wav",
"resourceId": "86dc814b-c172-4428-9112-60f8ecae1edb"
}
],
},
"routingPolicies": [],
"tenantId": "aa67bd4c-8475-432d-bd41-39f255720e0a",
"myParticipantId": "499ff390-7a72-40e8-83a0-8fac6295ae7e",
"id": "2e1a0b00-2db4-4022-9570-243709c565ab",
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#app/calls/$entity",
"subject": null,
"terminationReason": null,
"ringingTimeoutInSeconds": null,
"mediaState": null,
"resultInfo": null,
"answeredBy": null,
"chatInfo": null,
"meetingInfo": null,
"transcription": null,
"meetingCapability": null,
"toneInfo": null
}
Example 8: Create peer-to-peer PSTN call with application hosted media
Note: This example requires Calls.Initiate.All and Calls.AccessMedia.All permissions.
This call requires an application instance with a PSTN number assigned. For details, see Assign a phone number to your bot.
Request
The following example shows a request to make a peer-to-peer call between the bot and a PSTN number. In this example, the media is hosted locally by the application. The values of authorization token, callback URL, application instance ID, application instance display name, phone ID and tenant ID must be replaced with actual values to make the example work.
Note: Application instance ID is the object ID of application instance. The application ID that application instance links to should match the one in authorization token. Phone ID is the phone number in E.164 format.
POST https://graph.microsoft.com/v1.0/communications/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"callbackUri": "https://bot.contoso.com/callback",
"source": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"applicationInstance": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "Calling Bot",
"id": "3d913abb-aec0-4964-8fa6-3c6850c4f278"
},
},
"countryCode": null,
"endpointType": null,
"region": null,
"languageId": null
},
"targets": [
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"phone": {
"@odata.type": "#microsoft.graph.identity",
"id": "+12345678901"
}
}
}
],
"requestedModalities": [
"audio"
],
"mediaConfig": {
"@odata.type": "#microsoft.graph.appHostedMediaConfig",
"blob": "<Media Session Configuration>"
},
"tenantId": "aa67bd4c-8475-432d-bd41-39f255720e0a"
}
Response
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Location: https://graph.microsoft.com/v1.0/communications/calls/2e1a0b00-2db4-4022-9570-243709c565ab
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.call",
"state": "establishing",
"direction": "outgoing",
"callbackUri": "https://bot.contoso.com/callback",
"callChainId": "d8217646-3110-40b1-bae6-e9ac6c3a9f74",
"callRoutes": [],
"source": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"applicationInstance": {
"@odata.type": "#microsoft.graph.identity",
"displayName": "Calling Bot",
"id": "3d913abb-aec0-4964-8fa6-3c6850c4f278"
},
},
"countryCode": null,
"endpointType": null,
"region": null,
"languageId": null
},
"targets": [
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"@odata.type": "#microsoft.graph.identitySet",
"phone": {
"@odata.type": "#microsoft.graph.identity",
"id": "+12345678901"
}
},
"endpointType": null,
"region": null,
"replacesCallId": null,
"languageId": null
}
],
"requestedModalities": [
"audio"
],
"activeModalities": [],
"mediaConfig": {
"@odata.type": "#microsoft.graph.appHostedMediaConfig",
"blob": "<Media Session Configuration>",
},
"routingPolicies": [],
"tenantId": "aa67bd4c-8475-432d-bd41-39f255720e0a",
"myParticipantId": "499ff390-7a72-40e8-83a0-8fac6295ae7e",
"id": "2e1a0b00-2db4-4022-9570-243709c565ab",
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#app/calls/$entity",
"subject": null,
"terminationReason": null,
"ringingTimeoutInSeconds": null,
"mediaState": null,
"resultInfo": null,
"answeredBy": null,
"chatInfo": null,
"meetingInfo": null,
"transcription": null,
"meetingCapability": null,
"toneInfo": null
}
Feedback
Submit and view feedback for