Adicionar um usuário do Microsoft Teams a uma chamada existente usando a Automação de Chamadas

Neste início rápido, usamos as APIs de Automação de Chamadas dos Serviços de Comunicação do Azure para adicionar, remover e transferir chamadas para um usuário do Teams.

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa.
• Uma licença de telefone do Microsoft Teams e um locatário do Teams com privilégios administrativos. A licença por telefone do Teams é obrigatória para usar esse recurso, saiba mais sobre as licenças do Teams aqui. O usuário do Microsoft Teams também deve estar voice habilitado, consulte Configuração do sistema do seu telefone. Os privilégios administrativos são necessários para autorizar o recurso dos Serviços de Comunicação a chamar usuários do Teams, explicados mais adiante na Etapa 1.
• Um recurso do Serviço de Comunicação implantado e uma cadeia de conexão válida encontrados selecionando Chaves no menu do lado esquerdo no portal do Azure.
• Adquira um número de telefone PSTN do recurso Serviço de Comunicação. Anote o número de telefone que você adquiriu para usar neste início rápido.
• Uma assinatura da Grade de Eventos do Azure para receber o IncomingCall evento.
• A biblioteca de API de Automação de Chamadas do Serviço de Comunicação do Azure mais recente para seu sistema operacional.
• Um serviço Web que implementa a biblioteca de API de automação de chamadas, siga este tutorial.

Etapa 1: Autorização para seu recurso dos Serviços de Comunicação do Azure para habilitar chamadas para usuários do Microsoft Teams

Para habilitar chamadas por meio de APIs de Automação de Chamadas, um Administrador do Microsoft Teams ou um Administrador Global deve habilitar explicitamente o acesso do(s) recurso(s) dos Serviços de Comunicação ao seu locatário para permitir chamadas.

Set-CsTeamsAcsFederationConfiguration (MicrosoftTeamsPowerShell) Configuração de nível de locatário que habilita/desabilita a federação entre seu locatário e recursos específicos dos Serviços de Comunicação.

Set-CsExternalAccessPolicy (SkypeForBusiness) Política de usuário que permite ao administrador controlar ainda mais quais usuários em sua organização podem participar de comunicações federadas com usuários dos Serviços de Comunicação.

Observe que o usuário do Teams precisa ter uma licença de telefone para usar esse recurso. Para atribuir a licença, use o cmdlet Set-CsPhoneNumberAssignment e defina o parâmetro EnterpriseVoiceEnabled como $true. Para obter informações adicionais, consulte Configurar o Teams Phone na sua organização.

Etapa 2: Use a API do Graph para obter a ID do objeto do Microsoft Entra para usuários do Teams e, opcionalmente, verificar sua presença

A ID de objeto (OID) do Microsoft Entra de um usuário do Teams é necessária para adicioná-los ou transferi-los a partir de uma chamada dos Serviços de Comunicação. O OID pode ser recuperado através de 1) Portal do Office, 2) Centro de administração do Microsoft Entra, 3) Microsoft Entra Connect; ou 4) Graph API. O exemplo abaixo usa a Graph API.

O consentimento deve ser concedido por um administrador do Microsoft Entra antes que o Graph possa ser usado para pesquisar usuários, saiba mais seguindo o documento de visão geral da API de Segurança do Microsoft Graph. O OID pode ser recuperado usando a API de lista de usuários para pesquisar usuários. A seguir mostra uma pesquisa por nome para exibição, mas outras propriedades também podem ser pesquisadas:

Listar usuários usando o Microsoft Graph v1.0:

Request:
	https://graph.microsoft.com/v1.0/users?$search="displayName:Art Anderson"
Permissions:
	Application and delegated. Refer to documentation.
Response:
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
    "value": [
        {
            "displayName": "Art Anderson",
            "mail": "artanderson@contoso.com",
            "id": "fc4ccb5f-8046-4812-803f-6c344a5d1560"
        }

Opcionalmente, a presença de um usuário pode ser recuperada usando a API get presence e o usuário ObjectId. Saiba mais na documentação do Microsoft Graph v1.0.

Request:
https://graph.microsoft.com/v1.0/users/fc4ccb5f-8046-4812-803f-6c344a5d1560/presence
Permissions:
Delegated only. Application not supported.  Refer to documentation.
Response:
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('fc4ccb5f-8046-4812-803f-6c344a5d1560')/presence/$entity",
    "id": "fc4ccb5f-8046-4812-803f-6c344a5d1560",
    "availability": "Offline",
    "activity": "Offline"

Etapa 3: Adicionar um usuário do Teams a uma chamada existente do Communication Services controlada por APIs de automação de chamadas

Você precisa concluir a etapa de pré-requisito e ter um aplicativo de serviço Web para controlar uma chamada dos Serviços de Comunicação. Usando o objeto callConnection, adicione um participante à chamada.

CallAutomationClient client = new CallAutomationClient('<Connection_String>');
AnswerCallResult answer = await client.AnswerCallAsync(incomingCallContext, new Uri('<Callback_URI>'));
await answer.Value.CallConnection.AddParticipantAsync(
    new CallInvite(new MicrosoftTeamsUserIdentifier('<Teams_User_Guid>'))
    {
        SourceDisplayName = "Jack (Contoso Tech Support)"
    });

CallAutomationClient client = new CallAutomationClientBuilder().connectionString("<resource_connection_string>").buildClient();
AnswerCallResult answer = client.answerCall(incomingCallContext, "<Callback_URI>"));
answer.getCallConnection().addParticipant(
    new CallInvite(new MicrosoftTeamsUserIdentifier("<Teams_User_Guid>"))
        .setSourceDisplayName("Jack (Contoso Tech Support)"));

const client = new CallAutomationClient("<resource_connection_string>");
const answer = await client.answerCall(incomingCallContext, "<Callback_URI>"));
answer.callConnection.addParticipant({
    targetParticipant: { microsoftTeamsUserId: "<Teams_User_Guid>" },
    sourceDisplayName: "Jack (Contoso Tech Support)"
});

call_automation_client = CallAutomationClient.from_connection_string("<resource_connection_string>")
answer = call_automation_client.answer_call(incoming_call_context = incoming_call_context, callback_url = "<Callback_URI>")
call_connection_client = call_automation_client.get_call_connection(answer.call_connection_id)
call_connection_client.add_participant(target_participant = CallInvite(
    target = MicrosoftTeamsUserIdentifier(user_id="<USER_ID>"),
    source_display_name = "Jack (Contoso Tech Support)"))

---

No cliente de desktop do Microsoft Teams, a chamada de Jack será enviada ao usuário do Microsoft Teams por meio de uma notificação do sistema de chamada de entrada.

Depois que o usuário do Microsoft Teams aceitar a chamada, a experiência na chamada para o usuário do Microsoft Teams terá todos os participantes exibidos na lista do Microsoft Teams. Observe que seu aplicativo que está gerenciando a chamada usando a API de automação de chamadas permanecerá oculto para o usuário do Teams na tela de chamada, exceto no caso em que você iniciar uma chamada 1:1 com o usuário do Teams.

Etapa 4: Remover um usuário do Teams de uma chamada existente do Communication Services controlada por APIs de automação de chamadas

await answer.Value.CallConnection.RemoveParticipantAsync(new MicrosoftTeamsUserIdentifier('<Teams_User_Guid>'));

answer.getCallConnection().removeParticipant(new MicrosoftTeamsUserIdentifier("<Teams_User_Guid>"));

answer.callConnection.removeParticipant({ microsoftTeamsUserId: "<Teams_User_Guid>" });

call_connection_client.remove_participant(target_participant = MicrosoftTeamsUserIdentifier(user_id="<USER_ID>"))

---

Recurso opcional: transferir para um usuário do Teams a partir de uma chamada existente dos Serviços de Comunicação controlada por APIs de automação de chamadas

await answer.Value.CallConnection.TransferCallToParticipantAsync(new MicrosoftTeamsUserIdentifier('<Teams_User_Guid>'));

answer.getCallConnection().transferCallToParticipant(new MicrosoftTeamsUserIdentifier("<Teams_User_Guid>"));

answer.callConnection.transferCallToParticipant({ microsoftTeamsUserId: "<Teams_User_Guid>" });

call_connection_client.transfer_call_to_participant(target_participant = MicrosoftTeamsUserIdentifier(user_id = "<USER_ID>"))

---

Clean up resources (Limpar recursos)

Se quiser limpar e remover uma assinatura dos Serviços de Comunicação, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele. Saiba mais sobre a limpeza de recursos.

Próximos passos

• Saiba como gravar as suas chamadas.
• Saiba mais sobre a Automação de Chamadas e seus recursos.
• Saiba mais sobre os recursos do suporte de interoperabilidade do Teams com a Automação de Chamadas dos Serviços de Comunicação do Azure
• Saiba mais sobre a ação Reproduzir para reproduzir áudio numa chamada.
• Saiba como criar um fluxo de trabalho de chamada para um cenário de suporte ao cliente.