Anruf: Weiterleiten

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Weiterleiten eines aktiven Peer-to-Peer-Anrufs oder Gruppenanrufs.

Hinweis: Dies wird nur unterstützt, wenn sowohl der Transferee als auch das Übertragungsziel Microsoft Teams-Benutzer sind, die zum selben Mandanten gehören. Die Übertragung an die PSTN-Nummer wird nur für die Anwendungs-Instance unterstützt. Weitere Informationen zu Übertragender, Übertragungsnehmer und Übertragungsziel finden Sie in RFC 5589.

Eine beratende Übertragung bedeutet, dass der Übertragende die Person, an die er den Anruf weiterleiten möchte (den Erwerber), informieren kann, bevor die Übertragung vorgenommen wird. Dies steht im Gegensatz zur direkten Übertragung des Anrufs.

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 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
Application Calls.Initiate.All Nicht verfügbar.

HTTP-Anforderung

POST /app/calls/{id}/transfer
POST /communications/calls/{id}/transfer

Hinweis: Der /app-Pfad ist veraltet. Verwenden Sie in Zukunft den /communications-Pfad.

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
Content-type application/json. Erforderlich.

Anforderungstext

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

Parameter Typ Beschreibung
transferTarget invitationParticipantInfo Der Teilnehmer, der das Ziel der Übertragung ist.
Übernehmer participantInfo Der Teilnehmer, der der Empfänger der Übertragung ist. Er ist nur bei der Übertragung von einem Gruppenanruf erforderlich.

Antwort

Wenn die Methode erfolgreich verläuft, wird der Antwortcode 202 Accepted zurückgegeben.

Beispiele

Diese Beispiele zeigen den Ablauf eines eingehenden Anrufs bis hin zu den verschiedenen Arten von Übertragungsbenachrichtigungen.

Beispiel 1: Anrufübergabe aus einem Peer-to-Peer-Anruf

Anforderung

Das folgende Beispiel zeigt die Antwort.

POST https://graph.microsoft.com/beta/communications/calls/{id}/transfer
Content-Type: application/json
Content-Length: 430

{
  "transferTarget": {
    "endpointType": "default",
    "identity": {
      "user": {
        "id": "550fae72-d251-43ec-868c-373732c2704f",
        "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
        "displayName": "Heidi Steen"
      }
    },
    "languageId": "languageId-value",
    "region": "region-value"
  }
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 202 Accepted

Benachrichtigung – Übertragung

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "transferring"
      }
    }
  ]
}

Benachrichtigung – Übertragung akzeptiert

Hinweis: Die akzeptierte Übertragung kann nach oder vor der Inaktivität des Medienstatus Audio erfolgen.

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "transferAccepted"
      }
    }
  ]
}

Benachrichtigung – Übertragung abgeschlossen

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "terminated",
        "resultInfo": {
          "@odata.type": "#microsoft.graph.resultInfo",
          "code": 0,
          "subcode": 7015,
          "message": "GracefulTransferCompleted"
        }
      }
    }
  ]
}

Benachrichtigung – Übertragung fehlgeschlagen

Hinweis: Wenn eine Anrufübergabe fehlschlägt, lautet establishedder Anrufstatus .

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "established",
        "resultInfo": {
          "@odata.type": "#microsoft.graph.resultInfo",
          "code": 500,
          "subCode": 7000,
          "message": "<message>"
        }
      }
    }
  ]
}

Beispiel 2: Konsultative Weiterleitung aus einem Peer-to-Peer-Anruf

Anforderung

Das folgende Beispiel zeigt die Antwort.

POST https://graph.microsoft.com/beta/communications/calls/341a0500-d4bf-4224-8b19-1581168d328b/transfer
Content-Type: application/json

{
  "transferTarget": {
    "@odata.type": "#microsoft.graph.invitationParticipantInfo",
    "endpointType": "default",
    "identity": {
      "@odata.type": "#microsoft.graph.identitySet",
      "user": {
        "@odata.type": "#microsoft.graph.identity",
        "id": "550fae72-d251-43ec-868c-373732c2704f",
        "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
        "displayName": "Heidi Steen"
      }
    },
    "languageId": "en-us",
    "region": "amer",
    "replacesCallId": "e5d39592-99bd-4db8-bca8-30fb894ec51d"
  }
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 202 Accepted

Benachrichtigung – Übertragung

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "transferring"
      }
    }
  ]
}

Benachrichtigung – Übertragung akzeptiert

Hinweis: Die akzeptierte Übertragung kann nach oder vor der Inaktivität des Medienstatus Audio erfolgen.

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "transferAccepted"
      }
    }
  ]
}

Benachrichtigung – Übertragung abgeschlossen

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "terminated",
        "terminationReason": "AppTransferred"
      }
    }
  ]
}

Benachrichtigung – Übertragung fehlgeschlagen

Hinweis: Wenn eine Anrufübergabe fehlschlägt, lautet establishedder Anrufstatus .

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "established",
        "resultInfo": {
          "@odata.type": "#microsoft.graph.resultInfo",
          "code": 500,
          "subCode": 7700,
          "message": "<message>"
        },
        "replacesContext": "<replacesContext>"
      }
    }
  ]
}

Beispiel 3: Anrufweiterleitung von einem Peer-to-Peer-Anruf an PSTN-Nummer

Für diesen Aufruf ist eine Anwendungs-instance mit einer zugewiesenen PSTN-Nummer erforderlich. Ausführliche Informationen finden Sie unter Zuweisen einer Telefonnummer zu Ihrem Bot.

Hinweis: Die Telefon-ID ist die Telefonnummer im E.164-Format.

Anforderung

Das folgende Beispiel zeigt die Antwort.

POST https://graph.microsoft.com/beta/communications/calls/{id}/transfer
Content-Type: application/json
Content-Length: 430

{
  "transferTarget": {
    "endpointType": "default",
    "identity": {
        "phone": {
          "@odata.type": "#microsoft.graph.identity",
          "id": "+12345678901"
        }
    },
    "languageId": "languageId-value",
    "region": "region-value"
  }
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 202 Accepted

Benachrichtigung – Übertragung

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "transferring"
      }
    }
  ]
}

Benachrichtigung – Übertragung akzeptiert

Hinweis: Die akzeptierte Übertragung kann nach oder vor der Inaktivität des Medienstatus Audio erfolgen.

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "transferAccepted"
      }
    }
  ]
}

Benachrichtigung – Übertragung abgeschlossen

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "terminated",
        "resultInfo": {
          "@odata.type": "#microsoft.graph.resultInfo",
          "code": 0,
          "subcode": 7015,
          "message": "GracefulTransferCompleted"
        }
      }
    }
  ]
}

Benachrichtigung – Übertragung fehlgeschlagen

Hinweis: Wenn eine Anrufübergabe fehlschlägt, lautet establishedder Anrufstatus .

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "established",
        "resultInfo": {
          "@odata.type": "#microsoft.graph.resultInfo",
          "code": 500,
          "subCode": 7000,
          "message": "<message>"
        }
      }
    }
  ]
}

Beispiel 4: Beratungsübergabe von einem Peer-to-Peer-Anruf an PSTN-Nummer

Für diesen Aufruf ist eine Anwendungs-instance mit einer zugewiesenen PSTN-Nummer erforderlich. Ausführliche Informationen finden Sie unter Zuweisen einer Telefonnummer zu Ihrem Bot.

Hinweis: Die Telefon-ID ist die Telefonnummer im E.164-Format.

Anforderung

Das folgende Beispiel zeigt die Antwort.

POST https://graph.microsoft.com/beta/communications/calls/341a0500-d4bf-4224-8b19-1581168d328b/transfer
Content-Type: application/json

{
  "transferTarget": {
    "@odata.type": "#microsoft.graph.invitationParticipantInfo",
    "endpointType": "default",
    "identity": {
      "@odata.type": "#microsoft.graph.identitySet",
        "phone": {
          "@odata.type": "#microsoft.graph.identity",
          "id": "+12345678901"
        }
    },
    "languageId": "en-us",
    "region": "amer",
    "replacesCallId": "e5d39592-99bd-4db8-bca8-30fb894ec51d"
  }
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 202 Accepted

Benachrichtigung – Übertragung

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "transferring"
      }
    }
  ]
}

Benachrichtigung – Übertragung akzeptiert

Hinweis: Die akzeptierte Übertragung kann nach oder vor der Inaktivität des Medienstatus Audio erfolgen.

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "transferAccepted"
      }
    }
  ]
}

Benachrichtigung – Übertragung abgeschlossen

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "terminated",
        "terminationReason": "AppTransferred"
      }
    }
  ]
}

Benachrichtigung – Übertragung fehlgeschlagen

Hinweis: Wenn eine Anrufübergabe fehlschlägt, lautet establishedder Anrufstatus .

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "established",
        "resultInfo": {
          "@odata.type": "#microsoft.graph.resultInfo",
          "code": 500,
          "subCode": 7700,
          "message": "<message>"
        }
      }
    }
  ]
}

Beispiel 5: Anrufübergabe aus einem Gruppenanruf

Hinweis: Um aus einem Gruppenanruf zu wechseln, ist der Parameter für den Übertragungsempfänger erforderlich. Alle anderen Parameter sind die gleichen wie bei einer Übertragung aus einem Peer-to-Peer-Anruf. Eine beratende Überweisung von einem Gruppenanruf oder eine Übertragung an PSTN von einem Gruppenanruf ähneln den Beispielen 1 bis 4, wobei der Parameter für den Übertragungsempfänger angegeben ist.

Anforderung

Das folgende Beispiel zeigt die Antwort.

POST https://graph.microsoft.com/beta/communications/calls/{id}/transfer
Content-Type: application/json
Content-Length: 430

{
  "transferTarget": {
    "endpointType": "default",
    "identity": {
      "user": {
        "id": "550fae72-d251-43ec-868c-373732c2704f",
        "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
        "displayName": "Heidi Steen"
      }
    },
  },
  "transferee": {
    "identity": {
      "user": {
        "id": "751f6800-3180-414d-bd94-333364659951",
        "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47"
      }
    },
    "participantId": "909c6581-5130-43e9-88f3-fcb3582cde37"
  },
  "languageId": "languageId-value",
  "region": "region-value"
}

Antwort

HTTP/1.1 202 Accepted

Benachrichtigung – Übertragung

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "transferring"
      }
    }
  ]
}

Benachrichtigung – Übertragung akzeptiert

Hinweis: Die akzeptierte Übertragung kann nach oder vor der Inaktivität des Medienstatus Audio erfolgen.

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "transferAccepted"
      }
    }
  ]
}

Benachrichtigung – Übertragung abgeschlossen

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "terminated",
        "resultInfo": {
          "@odata.type": "#microsoft.graph.resultInfo",
          "code": 0,
          "subcode": 7015,
          "message": "GracefulTransferCompleted"
        }
      }
    }
  ]
}

Benachrichtigung – Übertragung fehlgeschlagen

Hinweis: Wenn eine Anrufübergabe fehlschlägt, lautet establishedder Anrufstatus .

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/341a0500-d4bf-4224-8b19-1581168d328b",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "established",
        "resultInfo": {
          "@odata.type": "#microsoft.graph.resultInfo",
          "code": 500,
          "subCode": 7000,
          "message": "<message>"
        }
      }
    }
  ]
}