Anruf: Umleitungcall: redirect

Wichtig

APIs unter der /beta Version in Microsoft Graph können Änderungen unterworfen werden.APIs under the /beta version in Microsoft Graph are subject to change. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt.Use of these APIs in production applications is not supported.

Umleiten eines eingehenden Anrufs, der noch nicht beantwortet oder abgelehnt wurde.Redirect an incoming call that hasn't been answered or rejected yet. Die Begriffe "umleiten" und "Weiterleiten" eines Anrufs werden synonym verwendet.The terms "redirecting" and "forwarding" a call are used interchangeably.

Der Bot wird erwartet, dass der Anruf umgeleitet, bevor der Anruf Timeout. Der aktuelle Timeoutwert beträgt 15 Sekunden.The bot is expected to redirect the call before the call times out. The current timeout value is 15 seconds.

BerechtigungenPermissions

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie im Artikel zum Thema Berechtigungen.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

BerechtigungstypPermission type Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)Permissions (from least to most privileged)
Delegiert (Geschäfts-, Schul- oder Unikonto)Delegated (work or school account) Nicht unterstütztNot Supported
Delegiert (persönliches Microsoft-Konto)Delegated (personal Microsoft account) Nicht unterstütztNot Supported
AnwendungApplication Calls.Initiate.AllCalls.Initiate.All

HTTP-AnforderungHTTP request

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

Hinweis: Der /app-Pfad ist veraltet.Note: The /app path is deprecated. Verwenden Sie in Zukunft den /communications-Pfad.Going forward, use the /communications path.

AnforderungsheaderRequest headers

NameName BeschreibungDescription
AuthorizationAuthorization Bearer {token}. Erforderlich.Bearer {token}. Required.

AnforderungstextRequest body

Geben Sie im Anforderungstext ein JSON-Objekt mit den folgenden Parametern an.In the request body, provide a JSON object with the following parameters.

ParameterParameter TypType BeschreibungDescription
targetstargets invitationParticipantInfo -SammlunginvitationParticipantInfo collection Die Ziel Teilnehmer der Umleitungs Operation.The target participants of the redirect operation. Wenn mehr als ein Ziel angegeben ist, handelt es sich um einen gleich-Aufruf.If more than one target is specified, it's a simulring call. Dies bedeutet, dass alle Ziele gleichzeitig erreicht werden und nur das erste abgeholte Ziel verbunden wird.This means that all of the targets will be rang at the same time and only the first target that picks up will be connected. Wir unterstützen bis zu 25 Ziele für gleich.We support up to 25 targets for simulring.
targetDispositiontargetDisposition ZeichenfolgeString Veraltet Mögliche Werte sind: default , simultaneousRing ,. forward(Deprecated) The possible values are: default , simultaneousRing , forward. Dieser Parameter ist veraltet, wir werden automatisch erkennen, ob es sich um einen Anruf-oder gleich-Aufruf von der Anzahl der bereitgestellten Ziele handelt.This parameter is deprecated, we will automatically identify whether it's a forward call or simulring call from the number of targets provided.
timeouttimeout Int32Int32 Das Timeout (in Sekunden) für die Umleitungs Operation.The timeout (in seconds) for the redirect operation. Der Bereich des Timeoutwerts liegt zwischen 15 und 90 Sekunden einschließlich.The range of the timeout value is between 15 and 90 seconds inclusive. Der Standardwert für Timeout beträgt 55 Sekunden für ein Ziel und 60 Sekunden für mehrere Ziele (Änderungen vorbehalten).The default timeout value is 55 seconds for one target and 60 seconds for multiple targets (subject to change).
maskCalleemaskCallee BooleschBoolean Gibt an, ob der angerufene für den Anrufer ausgeblendet werden soll.Indicates whether the callee is to be hidden from the caller. Bei true ist die Identität des angerufenen die bot-Identität.If true, then the callee identity is the bot identity. Default: false.Default: false.
maskCallermaskCaller BooleschBoolean Gibt an, ob der Aufrufer für den angerufenen ausgeblendet werden soll.Indicates whether the caller is to be hidden from the callee. Bei true ist die Identität des Anrufers die bot-Identität.If true, then the caller identity is the bot identity. Default: false.Default: false.
callbackUricallbackUri ZeichenfolgeString Auf diese Weise können Bots einen bestimmten Rückruf-URI für den aktuellen Anruf für den Empfang späterer Benachrichtigungen bereitstellen.This allows bots to provide a specific callback URI for the current call to receive later notifications. Wenn diese Eigenschaft nicht festgelegt wurde, wird stattdessen der globale Callback-URI des bot verwendet.If this property has not been set, the bot's global callback URI will be used instead. Dies muss sein https.This must be https.

AntwortResponse

Wenn die Methode erfolgreich verläuft, wird der Antwortcode 202 Accepted zurückgegeben.If successful, this method returns a 202 Accepted response code.

BeispieleExamples

In diesen Beispielen wird ein Workflow für eine Benachrichtigung über eingehende Anrufe behandelt, und es wird erläutert, wie dieser Anruf umgeleitet wird.These examples will cover a workflow of an incoming call notification and how that call will be redirected.

Hinweis: Die hier gezeigten Antwortobjekte sind möglicherweise zur Lesbarkeit gekürzt.Note: The response objects shown here might be shortened for readability. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.All the properties will be returned from an actual call.

Beispiel 1: Weiterleiten eines Anrufs an ein ZielExample 1: Forward a Call to a Target

Benachrichtigung – eingehendNotification - incoming
{
  "@odata.type": "#microsoft.graph.commsNotifications",
  "value": [
    {
      "@odata.type": "#microsoft.graph.commsNotification",
      "changeType": "created",
      "resourceUrl": "/communications/calls/491f0b00-ffff-4bc9-a43e-b226498ec22a",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "incoming",
        "direction": "incoming",
        "callbackUri": "https://bot.contoso.com/api/calls/24701998-1a73-4d42-8085-bf46ed0ae039",
        "source": {
          "@odata.type": "#microsoft.graph.participantInfo",
          "identity": {
            "@odata.type": "#microsoft.graph.identitySet",
            "user": {
              "@odata.type": "#microsoft.graph.identity",
              "id": "8d1e6ab6-26c5-4e22-a1bc-06ea7343958e",
              "tenantId": "632899f8-2ea1-4604-8413-27bd2892079f"
            }
          },
          "region": "amer",
        },
        "targets": [
          {
            "@odata.type": "#microsoft.graph.participantInfo",
            "identity": {
              "@odata.type": "#microsoft.graph.identitySet",
              "application": {
                "@odata.type": "#microsoft.graph.identity",
                "displayName": "test bot",
                "id": "24701998-1a73-4d42-8085-bf46ed0ae039"
              }
            }
          }
        ],
        "tenantId": "632899f8-2ea1-4604-8413-27bd2892079f",
        "myParticipantId": "c339cede-4bd6-4f20-ab9f-3a13e65f6d00",
        "id": "491f0b00-ffff-4bc9-a43e-b226498ec22a"
      }
    }
  ]
}
AnforderungRequest
POST https://graph.microsoft.com/beta/communications/calls/491f0b00-ffff-4bc9-a43e-b226498ec22a/redirect
Content-Type: application/json

{
  "targets": [
    {
      "@odata.type": "#microsoft.graph.invitationParticipantInfo",
      "identity": {
        "@odata.type": "#microsoft.graph.identitySet",
        "application": {
          "@odata.type": "#microsoft.graph.identity",
          "displayName": "test bot 2",
          "id": "22bfd41f-550e-477d-8789-f6f7bd2a5e8b"
        }
      }
    }
  ],
  "callbackUri": "https://bot.contoso.com/api/calls/24701998-1a73-4d42-8085-bf46ed0ae039"
}
AntwortResponse
HTTP/1.1 202 Accepted
Benachrichtigung beendetNotification - terminated
POST https://bot.contoso.com/api/calls/24701998-1a73-4d42-8085-bf46ed0ae039
Content-Type: application/json
{
  "@odata.type": "#microsoft.graph.commsNotifications",
  "value": [
    {
      "@odata.type": "#microsoft.graph.commsNotification",
      "changeType": "deleted",
      "resourceUrl": "/communications/calls/491f0b00-ffff-4bc9-a43e-b226498ec22a",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "terminated",
        "direction": "incoming",
        "callbackUri": "https://bot.contoso.com/api/calls/24701998-1a73-4d42-8085-bf46ed0ae039",
        "source": {
          "@odata.type": "#microsoft.graph.participantInfo",
          "identity": {
            "@odata.type": "#microsoft.graph.identitySet",
            "user": {
              "@odata.type": "#microsoft.graph.identity",
              "id": "8d1e6ab6-26c5-4e22-a1bc-06ea7343958e",
              "tenantId": "632899f8-2ea1-4604-8413-27bd2892079f"
            }
          },
          "region": "amer",
        },
        "targets": [
          {
            "@odata.type": "#microsoft.graph.participantInfo",
            "identity": {
              "@odata.type": "#microsoft.graph.identitySet",
              "application": {
                "@odata.type": "#microsoft.graph.identity",
                "displayName": "test bot",
                "id": "24701998-1a73-4d42-8085-bf46ed0ae039"
              }
            }
          }
        ],
        "tenantId": "632899f8-2ea1-4604-8413-27bd2892079f",
        "myParticipantId": "c339cede-4bd6-4f20-ab9f-3a13e65f6d00",
        "id": "491f0b00-ffff-4bc9-a43e-b226498ec22a"
      }
    }
  ]
}

Beispiel 2: Weiterleiten eines Anrufs an mehrere Ziele mit gleichzeitigem KlingelnExample 2: Forward a call to multiple targets with simultaneous ring

Benachrichtigung – eingehendNotification - 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/481f0b00-ffff-4ca1-8c67-a5f1e31e8e82",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "incoming",
        "direction": "incoming",
        "callbackUri": "https://bot.contoso.com/api/calls/24701998-1a73-4d42-8085-bf46ed0ae039",
        "source": {
          "@odata.type": "#microsoft.graph.participantInfo",
          "identity": {
            "@odata.type": "#microsoft.graph.identitySet",
            "user": {
              "@odata.type": "#microsoft.graph.identity",
              "id": "ec040873-8235-45fd-a403-c7259a5a548e",
              "tenantId": "632899f8-2ea1-4604-8413-27bd2892079f"
            }
          },
          "region": "amer"
        },
        "targets": [
          {
            "@odata.type": "#microsoft.graph.participantInfo",
            "identity": {
              "@odata.type": "#microsoft.graph.identitySet",
              "application": {
                "@odata.type": "#microsoft.graph.identity",
                "displayName": "test bot",
                "id": "24701998-1a73-4d42-8085-bf46ed0ae039"
              }
            }
          }
        ],
        "tenantId": "632899f8-2ea1-4604-8413-27bd2892079f",
        "myParticipantId": "f540f1b6-994b-4866-be95-8aad34c4f4dc",
        "id": "481f0b00-ffff-4ca1-8c67-a5f1e31e8e82"
      }
    }
  ]
}
AnforderungRequest
POST https://graph.microsoft.com/beta/communications/calls/481f0b00-ffff-4ca1-8c67-a5f1e31e8e82/redirect
Content-Type: application/json

{
  "targets": [
    {
      "@odata.type": "#microsoft.graph.invitationParticipantInfo",
      "identity": {
        "@odata.type": "#microsoft.graph.identitySet",
        "user": {
          "@odata.type": "#microsoft.graph.identity",
          "displayName": "test user",
          "id": "98da8a1a-1b87-452c-a713-65d3f10b1253"
        }
      }
    },
    {
      "@odata.type": "#microsoft.graph.invitationParticipantInfo",
      "identity": {
        "@odata.type": "#microsoft.graph.identitySet",
        "user": {
          "@odata.type": "#microsoft.graph.identity",
          "displayName": "test user 2",
          "id": "bf5aae9a-d11d-47a8-93b1-782504c9c3f3"
        }
      }
    }
  ],
  "routingPolicies": [
    "disableForwarding"
  ],
  "callbackUri": "https://bot.contoso.com/api/calls/24701998-1a73-4d42-8085-bf46ed0ae039"
}
AntwortResponse
HTTP/1.1 202 Accepted
Benachrichtigung beendetNotification - terminated
POST https://bot.contoso.com/api/calls/24701998-1a73-4d42-8085-bf46ed0ae039
Content-Type: application/json

{
  "@odata.type": "#microsoft.graph.commsNotifications",
  "value": [
    {
      "@odata.type": "#microsoft.graph.commsNotification",
      "changeType": "deleted",
      "resourceUrl": "/communications/calls/491f0b00-ffff-4bc9-a43e-b226498ec22a",
      "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "terminated",
        "direction": "incoming",
        "callbackUri": "https://bot.contoso.com/api/calls/24701998-1a73-4d42-8085-bf46ed0ae039",
        "source": {
          "@odata.type": "#microsoft.graph.participantInfo",
          "identity": {
            "@odata.type": "#microsoft.graph.identitySet",
            "user": {
              "@odata.type": "#microsoft.graph.identity",
              "id": "ec040873-8235-45fd-a403-c7259a5a548e",
              "tenantId": "632899f8-2ea1-4604-8413-27bd2892079f"
            }
          },
          "region": "amer"
        },
        "targets": [
          {
            "@odata.type": "#microsoft.graph.participantInfo",
            "identity": {
              "@odata.type": "#microsoft.graph.identitySet",
              "application": {
                "@odata.type": "#microsoft.graph.identity",
                "displayName": "test bot",
                "id": "24701998-1a73-4d42-8085-bf46ed0ae039"
              }
            }
          }
        ],
        "tenantId": "632899f8-2ea1-4604-8413-27bd2892079f",
        "myParticipantId": "f540f1b6-994b-4866-be95-8aad34c4f4dc",
        "id": "481f0b00-ffff-4ca1-8c67-a5f1e31e8e82"
      }
    }
  ]
}