Freigeben über

Anruf: Antwort

Namespace: microsoft.graph

Ermöglichen Sie es einem Bot, einen eingehenden Anruf entgegennehmen zu können. Bei der eingehenden Anrufanforderung kann es sich um eine Einladung eines Teilnehmers an einem Gruppenanruf oder um einen Peer-to-Peer-Anruf handeln. Wenn eine Einladung zu einem Gruppenanruf empfangen wird, enthält die Benachrichtigung die Parameter chatInfo und meetingInfo .

Es wird erwartet, dass der Bot den Anruf beantwortet, ablehnt oder umleitet , bevor für den Anruf ein Zeitüberschreitungsout erfolgt. Der aktuelle Timeoutwert beträgt für reguläre Szenarien 15 Sekunden und für richtlinienbasierte Aufzeichnungsszenarien 5 Sekunden.

Diese API unterstützt die folgenden PSTN-Szenarien:

  • Eingehender Anruf an die PSTN-Nummer des Bots und dann lädt der Bot ein weiteres PSTN ein.
  • Eingehender Anruf an die PSTN-Nummer des Bots und anschließende Übertragung des Bots an ein anderes PSTN.
  • Eingehender Anruf an die PSTN-Nummer des Bots und dann wird der Bot an ein anderes PSTN umgeleitet.
  • Eingehender Aufruf an den instance Bezeichner des Bots und dann lädt der Bot ein weiteres PSTN ein.
  • Eingehender Aufruf an den instance Bezeichner des Bots und anschließende Übertragung des Bots an ein anderes PSTN.
  • Eingehender Aufruf an den instance-Bezeichner des Bots und dann wird der Bot an ein anderes PSTN umgeleitet.
  • Eingehender Aufruf des Bots instance Bezeichners aus der geplanten Besprechung und der Bot lädt dann PSTN ein.
  • Ausgehender Anruf vom Bot (mit instance Bezeichner) an ein PSTN.
  • P2P-Aufruf zwischen Bot und einem anderen Peer (Teams-Benutzer, PSTN): Bot lädt ein anderes PSTN ein.
  • P2P-Aufruf zwischen Bot und einem anderen Peer (Teams-Benutzer, PSTN): Bot lädt einen anderen Teams-Benutzer ein.
  • Der Bot tritt an der geplanten Besprechung teil und lädt dann PSTN ein.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Weltweiter Service US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet
✅ ✅ ✅ ❌

Berechtigungen

Wählen Sie die Berechtigung oder Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Nicht unterstützt Nicht unterstützt
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung Calls.JoinGroupCall.All Calls.JoinGroupCallAsGuest.All

Anmerkung: Für einen Anruf, der von der Anwendung gehostete Medien verwendet, benötigen Sie auch die Berechtigung Calls.AccessMedia.All. Sie benötigen mindestens eine der folgenden Berechtigungen, um sicherzustellen, dass die source in der eingehenden Anrufbenachrichtigung entschlüsselt wird: Calls.AccessMedia.All, Calls.Initiate.All, Calls.InitiateGroupCall.All, Calls.JoinGroupCall.All, Calls.JoinGroupCallAsGuest.All. ist source die Anruferinformation in der Benachrichtigung über eingehende Anrufe. Ohne mindestens eine dieser Berechtigungen bleibt verschlüsselt source .

HTTP-Anforderung

POST /communications/calls/{id}/answer

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Weitere Informationen zu Authentifizierung und Autorisierung.
Content-type application/json. Erforderlich.

Anforderungstext

Geben Sie im Anforderungstext ein JSON-Objekt mit den folgenden Parametern an.

Parameter Typ Beschreibung
callbackUri Zeichenfolge Ermöglicht Bots, einen bestimmten Rückruf-URI für den gleichzeitigen Aufruf bereitzustellen, um spätere Benachrichtigungen zu empfangen. Wenn diese Eigenschaft nicht festgelegt ist, wird stattdessen der globale Rückruf-URI des Bots verwendet. Ich muss sein https.
acceptedModalities String collection Die Liste der akzeptierten Modalitäten. Mögliche Werte sind: audio, video und videoBasedScreenSharing. Erforderlich für die Entgegennehmen eines Anrufs.
callOptions incomingCallOptions Die Anrufoptionen.
mediaConfig appHostedMediaConfig oder serviceHostedMediaConfig Die Medienkonfiguration. (Erforderlich)
participantCapacity Int32 Die Anzahl der Teilnehmer, die die Anwendung für den Anruf verarbeiten kann, für teams richtlinienbasiertes Aufzeichnungsszenario .

Antwort

Diese Methode gibt einen 202 Accepted Antwortcode zurück.

Beispiele

Das folgende Beispiel illustriert, wie Sie diese API aufrufen können.

Anforderung

Das folgende Beispiel zeigt die Antwort.

POST https://graph.microsoft.com/v1.0/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,
    "isDeltaRosterEnabled": true
  },
  "participantCapacity": 200
}

Antwort

Das folgende Beispiel zeigt die Antwort.

HTTP/1.1 202 Accepted

Beispiel 1: Beantworten eines Peer-to-Peer-VoIP-Anrufs mit vom Dienst gehosteten Medien

Benachrichtigung – eingehend

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": {
          "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"
              }
            }
          }
        ],
        "requestedModalities": [ "audio" ]
      }
    }
  ]
}

Anforderung

POST https://graph.microsoft.com/v1.0/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"
      }
    ]
  }
}

Antwort

HTTP/1.1 202 Accepted

Benachrichtigung – Einrichtung

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"
      }
    }
  ]
}

Anmerkung: Aufrufe zur Einrichtung/Einrichtung von Benachrichtigungen können in nicht ordnungsgemäßer Reihenfolge eingehen.

Benachrichtigung – eingerichtet

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"
      }
    }
  ]
}

Anmerkung: Aufrufe zur Einrichtung/Einrichtung von Benachrichtigungen können in nicht ordnungsgemäßer Reihenfolge eingehen.

Beispiel 2: Annehmen eines VOIP-Anrufs mit von der Anwendung gehosteten Medien

Benachrichtigung – eingehend

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"
              }
            }
          }
        ],
        "requestedModalities": [ "audio" ]
      }
    }
  ]
}

Anforderung

POST https://graph.microsoft.com/v1.0/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>"
  }
}

Antwort

HTTP/1.1 202 Accepted

Benachrichtigung – Einrichtung

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"
      }
    }
  ]
}

Anmerkung: Aufrufe zur Einrichtung/Einrichtung von Benachrichtigungen können in nicht ordnungsgemäßer Reihenfolge eingehen.

Benachrichtigung – eingerichtet

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"
      }
    }
  ]
}

Anmerkung: Aufrufe zur Einrichtung/Einrichtung von Benachrichtigungen können in nicht ordnungsgemäßer Reihenfolge eingehen.

Benachrichtigung: Inhaltsfreigabe gestartet

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"
    }
  ]
}

Benachrichtigung– Inhaltsfreigabe beendet

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"
    }
  ]
}

Beispiel 3: Annehmen eines richtlinienbasierten Aufzeichnungsanrufs

Im Szenario Richtlinienbasierte Aufzeichnung wird eine Benachrichtigung über eingehende Anrufe an den Bot gesendet, der der Richtlinie zugeordnet ist, bevor ein Teilnehmer unter der Richtlinie an einen Anruf teilgibt. Die Joininformationen finden Sie unter der botData-Eigenschaft . Der Bot kann dann den Anruf annehmen und die Aufzeichnung status entsprechend aktualisieren.

Wenn participantCapacity in der Answer Anforderung für eine richtlinienbasierte Aufzeichnungsbenachrichtigung angegeben ist, werden nachfolgende Teilnehmerbeitrittsereignisse, die derselben Richtliniengruppe angehören, als participantJoiningNotification anstelle einer neuen eingehenden Anrufbenachrichtigung gesendet, bis eine Anzahl von Teilnehmern, die der aktuelle Anruf instance behandelt, die in participantCapacityangegebene Zahl erreicht hat.

Es folgt ein Beispiel für die Benachrichtigung über eingehende Anrufe, die ein Bot in diesem Fall erhalten würde.

{
   "@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"
                     }
                  ]
               }
            }
         }
      }
   ]
}