call: answer
Namespace: microsoft.graph
Important
APIs under the /beta
version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
Enable a bot to answer an incoming call. The incoming call request can be an invite from a participant in a group call or a peer-to-peer call. If an invite to a group call is received, the notification contains the chatInfo and meetingInfo parameters.
The bot is expected to answer, reject or redirect the call before the call times out. The current timeout value is 15 seconds. The current timeout value is 15 seconds for regular scenarios, and 5 seconds for policy-based recording scenarios.
This API is available in the following national cloud deployments.
Global service | US Government L4 | US Government L5 (DOD) | China operated by 21Vianet |
---|---|---|---|
✅ | ❌ | ❌ | ❌ |
Permissions
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
Permission type | Least privileged permissions | Higher privileged permissions |
---|---|---|
Delegated (work or school account) | Not supported. | Not supported. |
Delegated (personal Microsoft account) | Not supported. | Not supported. |
Application | Calls.JoinGroupCall.All | Calls.JoinGroupCallAsGuest.All |
Note: For a call that uses application-hosted media, you also need the Calls.AccessMedia.All permission. You must have at least one of the following permissions to ensure that the
source
in the incoming call notification is decrypted: Calls.AccessMedia.All, Calls.Initiate.All, Calls.InitiateGroupCall.All, Calls.JoinGroupCall.All, Calls.JoinGroupCallAsGuest.All. Thesource
is the caller info in the incoming call notification. Without at least one of these permissions, thesource
will remain encrypted.
HTTP request
POST /app/calls/{id}/answer
POST /communications/calls/{id}/answer
Note: The
/app
path is deprecated. Going forward, use the/communications
path.
Request headers
Name | Description |
---|---|
Authorization | Bearer {token}. Required. Learn more about authentication and authorization. |
Content-type | application/json. Required. |
Request body
In the request body, provide a JSON object with the following parameters.
Parameter | Type | Description |
---|---|---|
callbackUri | String | Allows bots to provide a specific callback URI for the concurrent call to receive later notifications. If this property hasn't been set, the bot's global callback URI is used instead. This must be https . |
acceptedModalities | String collection | The list of accept modalities. Possible values are: audio , video , videoBasedScreenSharing . Required for answering a call. |
callOptions | incomingCallOptions | The call options. |
mediaConfig | appHostedMediaConfig or serviceHostedMediaConfig | The media configuration. Required. |
participantCapacity | Int | The number of participants that the application can handle for the call, for Teams policy-based recording scenario. |
Response
This method returns a 202 Accepted
response code.
Examples
The following example shows how to call this API.
Request
The following example shows the request.
POST https://graph.microsoft.com/beta/communications/calls/{id}/answer
Content-Type: application/json
Content-Length: 211
{
"callbackUri": "callbackUri-value",
"mediaConfig": {
"@odata.type": "#microsoft.graph.appHostedMediaConfig",
"blob": "<Media Session Configuration Blob>"
},
"acceptedModalities": [
"audio"
],
"callOptions": {
"@odata.type": "#microsoft.graph.incomingCallOptions",
"isContentSharingNotificationEnabled": true
},
"participantCapacity": 200
}
Response
The following example shows the response.
HTTP/1.1 202 Accepted
Example 1: Answer a Peer-to-Peer VoIP call with service hosted media
Notification - incoming
POST https://bot.contoso.com/api/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "created",
"resourceUrl": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896",
"resourceData": {
"@odata.type": "#microsoft.graph.call",
"@odata.id": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896",
"@odata.etag": "W/\"5445\"",
"state": "incoming",
"direction": "incoming",
"callRoutes": [
{
"routingType": "lookup",
"original": {
"phone": {
"id": "+14258828080"
}
},
"final": {
"user": {
"id": "29362BD4-CD58-4ED0-A206-0E4A33DBB0B6",
"displayName": "Heidi Steen"
}
}
}
],
"source": {
"identity": {
"user": {
"displayName": "Test User",
"id": "8A34A46B-3D17-4ADC-8DCE-DC4E7D572698"
}
},
"region": "westus",
"languageId": "en-US"
},
"targets": [
{
"identity": {
"application": {
"displayName": "Test BOT",
"id": "8A34A46B-3D17-4ADC-8DCE-DC4E7D572698"
}
},
"languageId": "en-US"
}
],
"requestedModalities": [ "audio" ]
}
}
]
}
Request
POST /communications/calls/57DAB8B1894C409AB240BD8BEAE78896/answer
Content-Type: application/json
{
"callbackUri": "https://bot.contoso.com/api/calls",
"acceptedModalities": [ "audio" ],
"mediaConfig": {
"@odata.type": "#microsoft.graph.serviceHostedMediaConfig",
"preFetchMedia": [
{
"uri": "https://cdn.contoso.com/beep.wav",
"resourceId": "1D6DE2D4-CD51-4309-8DAA-70768651088E"
},
{
"uri": "https://cdn.contoso.com/cool.wav",
"resourceId": "1D6DE2D4-CD51-4309-8DAA-70768651088F"
}
]
}
}
Response
HTTP/1.1 202 Accepted
Notification - establishing
POST https://bot.contoso.com/api/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "updated",
"resourceUrl": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896",
"resourceData": {
"@odata.type": "#microsoft.graph.call",
"@odata.id": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896",
"@odata.etag": "W/\"5445\"",
"state": "establishing"
}
}
]
}
Note: Call establishing/established notifications may arrive out of order.
Notification - established
POST https://bot.contoso.com/api/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "updated",
"resourceUrl": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896",
"resourceData": {
"@odata.type": "#microsoft.graph.call",
"@odata.id": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896",
"@odata.etag": "W/\"5445\"",
"state": "established"
}
}
]
}
Note: Call establishing/established notifications may arrive out of order.
Example 2: Answer VOIP call with application hosted media
Notification - incoming
POST https://bot.contoso.com/api/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "created",
"resourceUrl": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896",
"resourceData": {
"@odata.type": "#microsoft.graph.call",
"@odata.id": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896",
"@odata.etag": "W/\"5445\"",
"state": "incoming",
"direction": "incoming",
"source": {
"@odata.type": "#microsoft.graph.participantInfo",
"identity": {
"user": {
"displayName": "Test User",
"id": "8A34A46B-3D17-4ADC-8DCE-DC4E7D572698"
}
},
"region": "westus",
"languageId": "en-US"
},
"targets": [
{
"@odata.type": "#microsoft.graph.invitationParticipantInfo",
"identity": {
"application": {
"displayName": "Test BOT",
"id": "8A34A46B-3D17-4ADC-8DCE-DC4E7D572698"
}
},
"region": "westus",
"languageId": "en-US"
}
],
"requestedModalities": [ "audio" ]
}
}
]
}
Request
POST https://graph.microsoft.com/beta/communications/calls/57DAB8B1894C409AB240BD8BEAE78896/answer
Content-Type: application/json
{
"callbackUri": "https://bot.contoso.com/api/calls",
"acceptedModalities": [ "audio" ],
"mediaConfig": {
"@odata.type": "#microsoft.graph.appHostedMediaConfig",
"blob": "<Media Session Configuration Blob>"
}
}
Response
HTTP/1.1 202 Accepted
Notification - establishing
POST https://bot.contoso.com/api/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "updated",
"resourceUrl": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896",
"resourceData": {
"@odata.type": "#microsoft.graph.call",
"@odata.id": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896",
"@odata.etag": "W/\"5445\"",
"state": "establishing"
}
}
]
}
Note: Call establishing/established notifications may arrive out of order.
Notification - established
POST https://bot.contoso.com/api/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "updated",
"resourceUrl": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896",
"resourceData": {
"@odata.type": "#microsoft.graph.call",
"@odata.id": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896",
"@odata.etag": "W/\"5445\"",
"state": "established"
}
}
]
}
Note: Call establishing/established notifications may arrive out of order.
Notification - content sharing started
POST https://bot.contoso.com/api/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "created",
"resourceUrl": "/communications/calls/421f4c00-4436-4c3a-9d9a-c4924cf98e67/contentsharingsessions/2765eb15-01f8-47c6-b12b-c32111a4a86f"
}
]
}
Notification - content sharing ended
POST https://bot.contoso.com/api/calls
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.commsNotifications",
"value": [
{
"@odata.type": "#microsoft.graph.commsNotification",
"changeType": "deleted",
"resourceUrl": "/communications/calls/421f4c00-4436-4c3a-9d9a-c4924cf98e67/contentsharingsessions/2765eb15-01f8-47c6-b12b-c32111a4a86f"
}
]
}
Example 3: Answer a policy-based recording call
Under the Policy-based recording scenario, before a participant under policy joins a call, an incoming call notification is sent to the bot associated with the policy. The join information can be found under the botData property. The bot can then choose to answer the call and update the recording status accordingly.
When participantCpapacity
is specified in the Answer
request for a policy-based recording notification, subsequent participant joining event belonging to the same policy group will be sent out as participantJoiningNotification instead of
new incoming call notification, until number of participants that current call instance is handling has reached the number specified in participantCapacity
.
Here's an example of the incoming call notification that a bot would receive in this case.
{
"@odata.type":"#microsoft.graph.commsNotifications",
"value":[
{
"@odata.type":"#microsoft.graph.commsNotification",
"changeType":"created",
"resource":"/app/calls/e71f0300-9c1f-4d99-b5f4-2722e877d497",
"resourceUrl":"/communications/calls/e71f0300-9c1f-4d99-b5f4-2722e877d497",
"resourceData":{
"@odata.type":"#microsoft.graph.call",
"state":"incoming",
"direction":"incoming",
"source":{
"@odata.type":"#microsoft.graph.participantInfo",
"id":"90fad2ce-8989-41a1-8a66-f6636e629a2a",
"identity":{
"@odata.type":"#microsoft.graph.identitySet",
"user":{
"@odata.type":"#microsoft.graph.identity",
"id":"8A34A46B-3D17-4ADC-8DCE-DC4E7D572698",
"identityProvider":"AAD"
}
},
"endpointType":"default",
"region":"amer"
},
"targets":[
{
"@odata.type":"#microsoft.graph.invitationParticipantInfo",
"identity":{
"@odata.type":"#microsoft.graph.identitySet",
"applicationInstance":{
"@odata.type":"#microsoft.graph.identity",
"id":"832899f8-2ea1-4604-8413-27bd2892079f",
"identityProvider":"AAD"
}
},
"endpointType":"default",
"id":"4520a1a5-5394-5a41-aa12-9ee6fa18cfc8",
"region":null,
"languageId":null
}
],
"meetingInfo":{
"@odata.type":"#microsoft.graph.tokenMeetingInfo",
"token":"join token"
},
"tenantId":"932899f8-2ea1-4604-8413-27bd2892079f",
"myParticipantId":"1520a1a5-5394-4a41-aa72-9ee6fa18cfc8",
"callChainId":"05f2f70f-3a9c-47c1-80a9-cc79e91d8cec",
"incomingContext":{
"@odata.type":"#microsoft.graph.incomingContext",
"sourceParticipantId":"30fad2ce-8989-41a1-8a66-f6636e629a2a",
"observedParticipantId":"30fad2ce-8989-41a1-8a66-f6636e629a2a"
},
"id":"e71f0300-9c1f-4d99-b5f4-2722e877d497",
"applicationMetadata":{
"botData":{
"mediaHostedRegion":"USEA",
"user":{
"participationMethod":"callee",
"clientLocation":"US"
},
"otherSideUser":{
"id":"971f0300-9c1f-4d99-b5f4-2722e877d490",
"participantId":"3520a1a5-5394-4a41-aa72-9ee6fa18cfc8",
"tenantId":"1540a1a5-2394-4a41-aa72-9ee6fa18cfc8",
"onBehalfOf":{
"id":"871f0300-9c1f-4d99-b5f4-2722e877d490"
},
"participationMethod":"caller",
"clientLocation":"EUNO"
},
"inviteReasons":[
"PolicyBasedRecording"
],
"policyIdentifier":"Test Policy",
"pairedRecorders":[
{
"id":"471f0300-5c1f-4d99-b5f4-2722e877d490",
"participantId":"371f0300-2c1f-4d99-b5f4-2722e877d490"
}
],
"otherRecorders":[
{
"id":"671f0300-9c1f-4d99-b5f4-2722e877d490",
"participantId":"a71f0300-ec1f-4d99-b5f4-2722e877d490"
}
]
}
}
}
}
]
}
Feedback
https://aka.ms/ContentUserFeedback.
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i:Skicka och visa feedback för