Compartilhar via


chamada: transferência

Namespace: microsoft.graph

Transfira uma chamada ponto a ponto ou uma chamada de grupo ativa.

Nota: Isso só terá suporte se o destino transferido e de transferência for usuários do Microsoft Teams que pertencem ao mesmo locatário. A transferência para o número PSTN só tem suporte para a instância do aplicativo. Para saber mais sobre transferor, transferee e destino de transferência, consulte RFC 5589.

Uma transferência consultiva significa que o transferidor pode informar a pessoa para a qual deseja transferir a chamada (o transferido), antes que a transferência seja feita. Isso se opõe à transferência direta da chamada.

Essa API está disponível nas seguintes implantações nacionais de nuvem.

Serviço global Governo dos EUA L4 GOVERNO DOS EUA L5 (DOD) China operada pela 21Vianet

Permissões

Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões privilegiadas mais altas
Delegado (conta corporativa ou de estudante) Sem suporte. Sem suporte.
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application Calls.Initiate.All Indisponível.

Solicitação HTTP

POST /communications/calls/{id}/transfer

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-type application/json. Obrigatório.

Corpo da solicitação

Forneça um objeto JSON com os seguintes parâmetros no corpo da solicitação.

Parâmetro Tipo Descrição
transferTarget invitationParticipantInfo O participante que é o destino da transferência.
Cessionário participantInfo O participante que é o transferido da transferência. Ela só é necessária quando é transferida de uma chamada em grupo.

Resposta

Se tiver êxito, este método retornará um código de resposta 202 Accepted.

Exemplos

Esses exemplos mostram o fluxo de uma chamada de entrada até os diferentes tipos de notificações de transferência.

Exemplo 1: Chamar transferência de uma chamada ponto a ponto

Solicitação

O exemplo a seguir mostra a solicitação.

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

{
  "transferTarget": {
    "endpointType": "default",
    "identity": {
      "user": {
        "id": "550fae72-d251-43ec-868c-373732c2704f",
        "displayName": "Heidi Steen"
      }
    }
  }
}
Resposta

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 202 Accepted
Notificação – transferência
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"
      }
    }
  ]
}
Notificação – transferência aceita

Nota: A transferência aceita pode ocorrer após ou antes de inativar o áudio de estado da mídia.

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"
      }
    }
  ]
}
Notificação – transferência concluída
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"
        }
      }
    }
  ]
}
Notificação – falha na transferência

Nota: Quando uma transferência de chamada falhar, o estado de chamada será 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>"
        }
      }
    }
  ]
}

Exemplo 2: transferência consultiva de uma chamada ponto a ponto

Solicitação

O exemplo a seguir mostra a solicitação.

POST https://graph.microsoft.com/v1.0/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",
        "displayName": "Heidi Steen"
      }
    },
    "replacesCallId": "e5d39592-99bd-4db8-bca8-30fb894ec51d"
  }
}
Resposta

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 202 Accepted
Notificação – transferência
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"
      }
    }
  ]
}
Notificação – transferência aceita

Nota: A transferência aceita pode ocorrer após ou antes de inativar o áudio de estado da mídia.

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"
      }
    }
  ]
}
Notificação – transferência concluída
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"
      }
    }
  ]
}
Notificação – falha na transferência

Nota: Quando uma transferência de chamada falhar, o estado de chamada será 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>"
      }
    }
  ]
}

Exemplo 3: chamar transferência de uma chamada ponto a ponto para o número PSTN

Essa chamada requer uma instância de aplicativo com um número PSTN atribuído. Para obter detalhes, consulte Atribuir um número de telefone ao bot.

Nota: A ID do telefone é o número de telefone no formato E.164.

Solicitação

O exemplo a seguir mostra a solicitação.

POST https://graph.microsoft.com/v1.0/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"
  },
  "clientContext": "9e90d1c1-f61e-43e7-9f75-d420159aae08"
}

Resposta

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 202 Accepted

Notificação – transferência

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

Notificação – transferência aceita

Nota: A transferência aceita pode ocorrer após ou antes de inativar o áudio de estado da mídia.

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

Notificação – transferência concluída

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

Notificação – falha na transferência

Nota: Quando uma transferência de chamada falhar, o estado de chamada será 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>"
        }
      }
    }
  ]
}

Exemplo 4: transferência consultiva de uma chamada ponto a ponto para o número PSTN

Essa chamada requer uma instância de aplicativo com um número PSTN atribuído. Para obter detalhes, consulte Atribuir um número de telefone ao bot.

Nota: A ID do telefone é o número de telefone no formato E.164.

Solicitação

O exemplo a seguir mostra a solicitação.

POST https://graph.microsoft.com/v1.0/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"
  },
  "clientContext": "9e90d1c1-f61e-43e7-9f75-d420159aae08"
}

Resposta

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 202 Accepted

Notificação – transferência

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

Notificação – transferência aceita

Nota: A transferência aceita pode ocorrer após ou antes de inativar o áudio de estado da mídia.

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

Notificação – transferência concluída

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

Notificação – falha na transferência

Nota: Quando uma transferência de chamada falhar, o estado de chamada será 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>"
        }
      }
    }
  ]
}

Exemplo 5: Chamar transferência de uma chamada em grupo

Nota: Para transferir de uma chamada em grupo, o parâmetro transferee é necessário. Todos os outros parâmetros são iguais aos de uma transferência de uma chamada ponto a ponto. Uma transferência consultiva de uma chamada de grupo ou uma transferência para PSTN de uma chamada de grupo é semelhante aos exemplos 1-4, com o parâmetro transferee especificado.

Solicitação

O exemplo a seguir mostra a solicitação.

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

{
  "transferTarget": {
    "endpointType": "default",
    "identity": {
      "user": {
        "id": "550fae72-d251-43ec-868c-373732c2704f",
        "displayName": "Heidi Steen"
      }
    },
  },
  "transferee": {
    "identity": {
      "user": {
        "id": "751f6800-3180-414d-bd94-333364659951",
        "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47"
      }
    },
    "participantId": "909c6581-5130-43e9-88f3-fcb3582cde37"
  }
}
Resposta
HTTP/1.1 202 Accepted
Notificação – transferência
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"
      }
    }
  ]
}
Notificação – transferência aceita

Nota: A transferência aceita pode ocorrer após ou antes de inativar o áudio de estado da mídia.

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"
      }
    }
  ]
}
Notificação – transferência concluída
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"
        }
      }
    }
  ]
}
Notificação – falha na transferência

Nota: Quando uma transferência de chamada falhar, o estado de chamada será 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>"
        }
      }
    }
  ]
}