Compartilhar via

chamada: atender

  • Artigo

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Ative um bot para atender uma chamada recebida. O pedido de chamada recebido pode ser um convite de um participante numa chamada de grupo ou de uma chamada ponto a ponto. Se for recebido um convite para uma chamada de grupo, a notificação contém os parâmetros chatInfo e meetingInfo .

Espera-se que o bot responda, rejeite ou redirecione a chamada antes de a chamada exceder o limite de tempo. O valor de tempo limite atual é de 15 segundos. O valor de tempo limite atual é de 15 segundos para cenários regulares e 5 segundos para cenários de gravação baseados em políticas.

Esta API suporta os seguintes cenários RTPC:

  • Chamada recebida para o número RTPC do bot e, em seguida, o bot convida outra RTPC.
  • Chamada recebida para o número RTPC do bot e, em seguida, transferência do bot para outra RTPC.
  • Chamada recebida para o número RTPC do bot e, em seguida, o bot redireciona para outra RTPC.
  • Chamada recebida para o identificador de instância do bot e, em seguida, o bot convida outra RTPC.
  • Chamada recebida para o identificador de instância do bot e, em seguida, transferência do bot para outra RTPC.
  • Chamada recebida para o identificador de instância do bot e, em seguida, o bot redireciona para outra RTPC.
  • Chamada recebida para o identificador de instância do bot a partir da Reunião Agendada e, em seguida, o bot convida a RTPC.
  • Chamada efetuada do bot (com identificador de instância) para uma RTPC.
  • Chamada P2P entre o bot e outro elemento da rede (utilizador do Teams, RTPC), o bot convida outra RTPC.
  • Chamada P2P entre o bot e outro elemento da rede (utilizador do Teams, RTPC), o bot convida outro utilizador do Teams.
  • O bot participa na reunião agendada e, em seguida, convida a RTPC.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global US Government L4 US Government L5 (DOD) China operada pela 21Vianet
✅ ❌ ❌ ❌

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão Permissões com menos privilégios Permissões com privilégios superiores
Delegado (conta corporativa ou de estudante) Sem suporte. Sem suporte.
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application Calls.JoinGroupCall.All Calls.JoinGroupCallAsGuest.All

Nota: Para uma chamada que utiliza suportes de dados alojados na aplicação, também precisa da permissão Calls.AccessMedia.All. Tem de ter, pelo menos, uma das seguintes permissões para garantir que a source notificação de chamada recebida está desencriptada: Calls.AccessMedia.All, Calls.Initiate.All, Calls.InitiateGroupCall.All, Calls.JoinGroupCall.All, Calls.JoinGroupCallAsGuest.All. São source as informações do autor da chamada na notificação de chamada recebida. Sem, pelo menos, uma destas permissões, o source permanecerá encriptado.

Solicitação HTTP

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

Observação: o caminho /app foi preterido. Daqui em diante, use o caminho /communications.

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
callbackUri String Permite que os bots forneçam um URI de chamada de retorno específico para a chamada simultânea para receber notificações posteriores. Se esta propriedade não tiver sido definida, é utilizado o URI de chamada de retorno global do bot. Tem de ser https.
acceptedModalities Coleção String A lista de modalidades de aceitação. Os valores possíveis são: audio, video, videoBasedScreenSharing. Necessário para atender uma chamada.
callOptions incomingCallOptions As opções de chamada.
mediaConfig appHostedMediaConfig ou serviceHostedMediaConfig A configuração de mídia. Obrigatório.
participantCapacity Int O número de participantes que a aplicação pode processar para a chamada, para o cenário de gravação baseado em políticas do Teams .

Resposta

Este método devolve um código de 202 Accepted resposta.

Exemplos

O exemplo a seguir mostra como chamar essa API.

Solicitação

O exemplo a seguir mostra a solicitação.

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

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 202 Accepted

Exemplo 1: atender uma chamada VoIP ponto a ponto com suporte de dados alojado pelo serviço

Notificação - a receber

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",
        "callRoutes": [
          {
            "routingType": "lookup",
            "original": {
              "phone": {
                "id": "+14258828080"
              }
            },
            "final": {
              "user": {
                "id": "29362BD4-CD58-4ED0-A206-0E4A33DBB0B6",
                "displayName": "Heidi Steen"
              }
            }
          }
        ],
        "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"
              }
            },
            "languageId": "en-US"
          }
        ],
        "requestedModalities": [ "audio" ]
      }
    }
  ]
}

Solicitação

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

Resposta

HTTP/1.1 202 Accepted

Notificação – estabelecer

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

Nota: As notificações estabelecidas/estabelecidas de chamadas podem ficar fora de ordem.

Notificação - estabelecida

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

Nota: As notificações estabelecidas/estabelecidas de chamadas podem ficar fora de ordem.

Exemplo 2: Atender chamada VOIP com suportes de dados alojados na aplicação

Notificação - a receber

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"
              }
            },
            "region": "westus",
            "languageId": "en-US"
          }
        ],
        "requestedModalities": [ "audio" ]
      }
    }
  ]
}

Solicitação

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

Resposta

HTTP/1.1 202 Accepted

Notificação – estabelecer

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

Nota: As notificações estabelecidas/estabelecidas de chamadas podem ficar fora de ordem.

Notificação - estabelecida

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

Nota: As notificações estabelecidas/estabelecidas de chamadas podem ficar fora de ordem.

Notificação – a partilha de conteúdos foi iniciada

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

Notificação – a partilha de conteúdos terminou

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

Exemplo 3: atender uma chamada de gravação baseada em políticas

No cenário de gravação baseada em políticas, antes de um participante em política aderir a uma chamada, é enviada uma notificação de chamada recebida para o bot associado à política. As informações de associação podem ser encontradas na propriedade botData . Em seguida, o bot pode optar por atender a chamada e atualizar a gravação status em conformidade.

Quando participantCpapacity for especificado no pedido para uma notificação de gravação baseada em Answer políticas, o evento de participação subsequente pertencente ao mesmo grupo de políticas será enviado como participanteJoiningNotification em vez de uma nova notificação de chamada recebida, até que o número de participantes que a instância de chamada atual está a processar tenha atingido o número especificado em participantCapacity.

Eis um exemplo da notificação de chamada recebida que um bot receberia neste caso.

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