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

Artigo
11/25/2024

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, para obter detalhes, consulte Criar uma conta gratuitamente..
Uma licença do Microsoft Teams Phone e um locatário do Teams com privilégios administrativos. A licença do Teams Phone é 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 dos recursos dos Serviços de Comunicação ao 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.

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 a seguir usa Graph API.

Um administrador do Microsoft Entra deve dar o seu consentimento 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. O exemplo a seguir mostra uma pesquisa por nome para exibição, mas você também pode pesquisar outras propriedades:

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 é enviada ao usuário do Microsoft Teams por meio de uma notificação do sistema de chamada de entrada.

Captura de tela do cliente de desktop do Microsoft Teams, a chamada de Jack é 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 aceita a chamada, a experiência na chamada para o usuário do Microsoft Teams exibe todos os participantes na lista do Microsoft Teams. Seu aplicativo que está gerenciando a chamada usando a API de automação de chamadas permanece oculto para o usuário do Teams na tela de chamada. Captura de ecrã do utilizador do Microsoft Teams a aceitar a chamada e a introduzir a experiência na chamada para o utilizador do Microsoft 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.

Partilhar via