调用:转移

命名空间:microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。

转移活动的对等呼叫或组呼叫。

注意: 仅当受让者和转移目标都是属于同一租户的 Microsoft Teams 用户时,才支持此操作。 仅应用程序实例支持转移到 PSTN 号码。 若要详细了解转让人、受让人和转移目标,请参阅 RFC 5589

咨询转接是指转让人可以在转接前通知要转接电话的人, (受让人) 。 这与直接转移呼叫相反。

此 API 可用于以下国家级云部署

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考

权限类型 最低特权权限 更高特权权限
委派(工作或学校帐户) 不支持。 不支持。
委派(个人 Microsoft 帐户) 不支持。 不支持。
应用程序 Calls.Initiate.All 不可用。

HTTP 请求

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

注意:/app 路径已弃用。 今后将使用 /communications 路径。

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权
Content-type application/json. 必需。

请求正文

在请求正文中,提供具有以下参数的 JSON 对象。

参数 类型 说明
transferTarget invitationParticipantInfo 传输目标的参与者。
participantInfo 是转移的受让人的参与者。 仅当从组呼叫转接时才需要它。

响应

如果成功,此方法返回 202 Accepted 响应代码。

示例

这些示例演示传入呼叫一直流到不同类型的传输通知。

示例 1:从对等呼叫转移

请求

下面为请求示例。

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

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 202 Accepted

通知 - 传输

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

通知 - 已接受传输

注意: 接受传输可能在媒体状态音频处于非活动状态之后或之前发生。

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

通知 - 传输已完成

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

通知 - 传输失败

注意: 当呼叫转移失败时,呼叫状态将为 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/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>"
        }
      }
    }
  ]
}

示例 2:从对等呼叫进行咨询转移

请求

下面为请求示例。

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

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 202 Accepted

通知 - 传输

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

通知 - 已接受传输

注意: 接受传输可能在媒体状态音频处于非活动状态之后或之前发生。

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

通知 - 传输已完成

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

通知 - 传输失败

注意: 当呼叫转移失败时,呼叫状态将为 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/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>"
      }
    }
  ]
}

示例 3:从对等呼叫转移到 PSTN 号码的呼叫

此调用需要分配了 PSTN 号码的应用程序实例。 有关详细信息,请参阅 为机器人分配电话号码

注意: 电话 ID 是 E.164 格式的电话号码。

请求

下面为请求示例。

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

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 202 Accepted

通知 - 传输

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

通知 - 已接受传输

注意: 接受传输可能在媒体状态音频处于非活动状态之后或之前发生。

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

通知 - 传输已完成

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

通知 - 传输失败

注意: 当呼叫转移失败时,呼叫状态将为 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/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>"
        }
      }
    }
  ]
}

示例 4:从对等呼叫到 PSTN 号码的咨询转移

此调用需要分配了 PSTN 号码的应用程序实例。 有关详细信息,请参阅 为机器人分配电话号码

注意: 电话 ID 是 E.164 格式的电话号码。

请求

下面为请求示例。

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

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 202 Accepted

通知 - 传输

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

通知 - 已接受传输

注意: 接受传输可能在媒体状态音频处于非活动状态之后或之前发生。

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

通知 - 传输已完成

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

通知 - 传输失败

注意: 当呼叫转移失败时,呼叫状态将为 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/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>"
        }
      }
    }
  ]
}

示例 5:从组呼叫转接呼叫

注意: 若要从组调用转接,需要转接方参数。 所有其他参数与从对等调用传输的参数相同。 从组呼叫进行咨询转接或从组呼叫转移到 PSTN 类似于示例 1-4,并指定了转接方参数。

请求

下面为请求示例。

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

响应

HTTP/1.1 202 Accepted

通知 - 传输

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

通知 - 已接受传输

注意: 接受传输可能在媒体状态音频处于非活动状态之后或之前发生。

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

通知 - 传输已完成

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

通知 - 传输失败

注意: 当呼叫转移失败时,呼叫状态将为 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/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>"
        }
      }
    }
  ]
}