Szybki start: wykonywanie wywołań wychodzących przy użyciu usługi Call Automation

Artykuł
2024-04-07

Interfejsy API usługi Azure Communication Services Call Automation to zaawansowany sposób tworzenia interaktywnych środowisk wywołujących. W tym przewodniku Szybki start omówimy sposób na wywołanie ruchu wychodzącego i rozpoznawanie różnych zdarzeń w wywołaniu.

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Wdrożony zasób usług komunikacyjnych. Utwórz zasób usług komunikacyjnych.
Numer telefonu w zasobie usług Azure Communication Services, który może wykonywać połączenia wychodzące. Jeśli masz bezpłatną subskrypcję, możesz uzyskać numer telefonu w wersji próbnej.
Tworzenie i hostowanie aplikacji Azure Dev Tunnel. Instrukcje znajdują się tutaj.
Utwórz i połącz usługi Azure AI z wieloma usługami z zasobem usług Azure Communication Services.
Utwórz niestandardową poddomenę dla zasobu usług Azure AI.
(Opcjonalnie) Użytkownik usługi Microsoft Teams z włączoną licencją voice na telefon. Licencja na telefon usługi Teams jest wymagana do dodawania użytkowników usługi Teams do połączenia. Dowiedz się więcej o licencjach usługi Teams tutaj. Dowiedz się więcej o włączaniu systemu voice telefonicznego tutaj.

Przykładowy kod

Pobierz lub sklonuj przykładowy kod szybki start z usługi GitHub.

Przejdź do CallAutomation_OutboundCalling folderu i otwórz rozwiązanie w edytorze kodu.

Konfigurowanie i hostowanie usługi Azure DevTunnel

Azure DevTunnels to usługa platformy Azure, która umożliwia udostępnianie lokalnych usług internetowych hostowanych w Internecie. Uruchom polecenia, aby połączyć lokalne środowisko programistyczne z publicznym Internetem. Usługa DevTunnels tworzy trwały adres URL punktu końcowego i umożliwia dostęp anonimowy. Ten punkt końcowy służy do powiadamiania aplikacji o wywoływaniu zdarzeń z usługi Azure Communication Services Call Automation.

devtunnel create --allow-anonymous
devtunnel port create -p 8080
devtunnel host

Alternatywnie postępuj zgodnie z instrukcjami, aby skonfigurować usługę Azure DevTunnel w programie Visual Studio

Aktualizowanie konfiguracji aplikacji

Następnie zaktualizuj Program.cs plik przy użyciu następujących wartości:

acsConnectionString: parametry połączenia dla zasobu usług Azure Communication Services. Usługi Azure Communication Services parametry połączenia można znaleźć, korzystając z instrukcji dostępnych tutaj.
callbackUriHost: Po zainicjowaniu hosta Usługi DevTunnel zaktualizuj to pole za pomocą tego identyfikatora URI.
acsPhonenumber: zaktualizuj to pole przy użyciu uzyskanego numeru telefonu usług Azure Communication Services. Ten numer telefonu powinien używać formatu numeru telefonu E164 (np. +18881234567)
targetPhonenumber: zaktualizuj pole przy użyciu numeru telefonu, który ma być wywoływany przez aplikację. Ten numer telefonu powinien używać formatu numeru telefonu E164 (np. +18881234567)
cognitiveServiceEndpoint: zaktualizuj pole za pomocą punktu końcowego usług Azure AI.
targetTeamsUserId: (Opcjonalnie) pole aktualizacji przy użyciu identyfikatora użytkownika usługi Microsoft Teams, które chcesz dodać do wywołania. Zobacz Uzyskiwanie identyfikatora użytkownika aplikacji Teams przy użyciu interfejsu API programu Graph.

// Your ACS resource connection string 
var acsConnectionString = "<ACS_CONNECTION_STRING>"; 

// Your ACS resource phone number will act as source number to start outbound call 
var acsPhonenumber = "<ACS_PHONE_NUMBER>"; 
 
// Target phone number you want to receive the call. 
var targetPhonenumber = "<TARGET_PHONE_NUMBER>";

// Base url of the app 
var callbackUriHost = "<CALLBACK_URI_HOST_WITH_PROTOCOL>"; 

// Your cognitive service endpoint 
var cognitiveServiceEndpoint = "<COGNITIVE_SERVICE_ENDPOINT>";

// (Optional) User Id of the target teams user you want to receive the call.
var targetTeamsUserId = "<TARGET_TEAMS_USER_ID>";

Nawiązywanie połączenia wychodzącego

Aby wykonać wywołanie wychodzące z usług Azure Communication Services, w tym przykładzie użyto zdefiniowanego targetPhonenumber wcześniej w aplikacji wywołania przy użyciu interfejsu CreateCallAsync API. Ten kod wykona połączenie wychodzące przy użyciu docelowego numeru telefonu.

PhoneNumberIdentifier target = new PhoneNumberIdentifier(targetPhonenumber);
PhoneNumberIdentifier caller = new PhoneNumberIdentifier(acsPhonenumber);
var callbackUri = new Uri(callbackUriHost + "/api/callbacks");
CallInvite callInvite = new CallInvite(target, caller);
var createCallOptions = new CreateCallOptions(callInvite, callbackUri) {
  CallIntelligenceOptions = new CallIntelligenceOptions() {
    CognitiveServicesEndpoint = new Uri(cognitiveServiceEndpoint)
  }
};
CreateCallResult createCallResult = await callAutomationClient.CreateCallAsync(createCallOptions);

Obsługa zdarzeń automatyzacji wywołań

Wcześniej w naszej aplikacji zarejestrowaliśmy callbackUriHost usługę Call Automation Service. Host wskazuje punkt końcowy, którego usługa wymaga powiadomienia o zdarzeniach wywołujących, które się zdarzają. Następnie możemy iterować zdarzenia i wykrywać określone zdarzenia, które chcemy zrozumieć w naszej aplikacji. W poniższym kodzie odpowiadamy na CallConnected zdarzenie.

app.MapPost("/api/callbacks", async (CloudEvent[] cloudEvents, ILogger < Program > logger) => {
  foreach(var cloudEvent in cloudEvents) {
    logger.LogInformation($"Event received: {JsonConvert.SerializeObject(cloudEvent)}");
    CallAutomationEventBase parsedEvent = CallAutomationEventParser.Parse(cloudEvent);
    logger.LogInformation($"{parsedEvent?.GetType().Name} parsedEvent received for call connection id: {parsedEvent?.CallConnectionId}");
    var callConnection = callAutomationClient.GetCallConnection(parsedEvent.CallConnectionId);
    var callMedia = callConnection.GetCallMedia();
    if (parsedEvent is CallConnected) {
      //Handle Call Connected Event
    }
  }
});

(Opcjonalnie) Dodawanie użytkownika aplikacji Microsoft Teams do wywołania

Możesz dodać użytkownika usługi Microsoft Teams do wywołania przy użyciu AddParticipantAsync metody z identyfikatorem MicrosoftTeamsUserIdentifier użytkownika usługi Teams i identyfikatorem użytkownika usługi Teams. Najpierw należy wykonać krok wymagań wstępnych Autoryzacja zasobu usług Azure Communication Services, aby umożliwić wywoływanie użytkowników usługi Microsoft Teams. Opcjonalnie możesz również przekazać element , SourceDisplayName aby kontrolować tekst wyświetlany w wyskakującym powiadomieniu użytkownika usługi Teams.

await callConnection.AddParticipantAsync(
    new CallInvite(new MicrosoftTeamsUserIdentifier(targetTeamsUserId))
    {
        SourceDisplayName = "Jack (Contoso Tech Support)"
    });

Rozpoczynanie nagrywania połączenia

Usługa Call Automation umożliwia również rozpoczęcie nagrywania i przechowywania nagrań połączeń głosowych i wideo. Więcej informacji na temat różnych funkcji można znaleźć w interfejsach API nagrywania wywołań tutaj.

CallLocator callLocator = new ServerCallLocator(parsedEvent.ServerCallId);
var recordingResult = await callAutomationClient.GetCallRecording().StartAsync(new StartRecordingOptions(callLocator));
recordingId = recordingResult.Value.RecordingId;

Odtwórz wiadomość powitalną i rozpoznaj

TextSourceKorzystając z elementu , możesz udostępnić usłudze tekst, który ma zostać zsyntetyzowany i użyty na potrzeby wiadomości powitalnej. Usługa Azure Communication Services Call Automation odtwarza ten komunikat podczas CallConnected zdarzenia.

Następnie przekazujemy tekst do elementu , a następnie wywołujemy metodę CallMediaRecognizeChoiceOptions StartRecognizingAsync. Dzięki temu aplikacja może rozpoznać opcję wybraną przez obiekt wywołujący.

if (parsedEvent is CallConnected callConnected) {
  logger.LogInformation($"Start Recording...");
  CallLocator callLocator = new ServerCallLocator(parsedEvent.ServerCallId);
  var recordingResult = await callAutomationClient.GetCallRecording().StartAsync(new StartRecordingOptions(callLocator));
  recordingId = recordingResult.Value.RecordingId;

  var choices = GetChoices();

  // prepare recognize tones 
  var recognizeOptions = GetMediaRecognizeChoiceOptions(mainMenu, targetPhonenumber, choices);

  // Send request to recognize tones 
  await callMedia.StartRecognizingAsync(recognizeOptions);
}

CallMediaRecognizeChoiceOptions GetMediaRecognizeChoiceOptions(string content, string targetParticipant, List < RecognitionChoice > choices, string context = "") {
  var playSource = new TextSource(content) {
    VoiceName = SpeechToTextVoice
  };

  var recognizeOptions = new CallMediaRecognizeChoiceOptions(targetParticipant: new PhoneNumberIdentifier(targetParticipant), choices) {
    InterruptCallMediaOperation = false,
      InterruptPrompt = false,
      InitialSilenceTimeout = TimeSpan.FromSeconds(10),
      Prompt = playSource,
      OperationContext = context
  };
  return recognizeOptions;
}

List < RecognitionChoice > GetChoices() {
  return new List < RecognitionChoice > {
    new RecognitionChoice("Confirm", new List < string > {
      "Confirm",
      "First",
      "One"
    }) {
      Tone = DtmfTone.One
    },
    new RecognitionChoice("Cancel", new List < string > {
      "Cancel",
      "Second",
      "Two"
    }) {
      Tone = DtmfTone.Two
    }
  };
}

Obsługa zdarzeń wyboru

Usługa Azure Communication Services Call Automation wyzwala element api/callbacks webhook, który skonfigurowaliśmy i powiadomi nas o zdarzeniu RecognizeCompleted . Zdarzenie daje nam możliwość reagowania na odebrane dane wejściowe i wyzwalanie akcji. Następnie aplikacja odtwarza komunikat do obiekt wywołujący na podstawie określonych odebranych danych wejściowych.

if (parsedEvent is RecognizeCompleted recognizeCompleted) {
  var choiceResult = recognizeCompleted.RecognizeResult as ChoiceResult;
  var labelDetected = choiceResult?.Label;
  var phraseDetected = choiceResult?.RecognizedPhrase;

  // If choice is detected by phrase, choiceResult.RecognizedPhrase will have the phrase detected,  
  // If choice is detected using dtmf tone, phrase will be null  
  logger.LogInformation("Recognize completed successfully, labelDetected={labelDetected}, phraseDetected={phraseDetected}", labelDetected, phraseDetected);

  var textToPlay = labelDetected.Equals(ConfirmChoiceLabel, StringComparison.OrdinalIgnoreCase) ? ConfirmedText : CancelText;

  await HandlePlayAsync(callMedia, textToPlay);
}

async Task HandlePlayAsync(CallMedia callConnectionMedia, string text) {
  // Play goodbye message 
  var GoodbyePlaySource = new TextSource(text) {
    VoiceName = "en-US-NancyNeural"
  };
  await callConnectionMedia.PlayToAllAsync(GoodbyePlaySource);
}

Zawieszanie się i zatrzymywanie nagrywania

Na koniec, gdy wykryjemy warunek, który ma sens, aby zakończyć wywołanie, możemy użyć HangUpAsync metody , aby zawiesić wywołanie.

if ((parsedEvent is PlayCompleted) || (parsedEvent is PlayFailed))
{
    logger.LogInformation($"Stop recording and terminating call.");
    callAutomationClient.GetCallRecording().Stop(recordingId);
    await callConnection.HangUpAsync(true);
}

Aby uruchomić aplikację za pomocą programu VS Code, otwórz okno terminalu i uruchom następujące polecenie

dotnet run

Otwórz http://localhost:8080/swagger/index.html adres URL tunelu deweloperskiego w przeglądarce. Adres URL tunelu wygląda następująco: <YOUR DEV TUNNEL ENDPOINT>/swagger/index.html

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Wdrożony zasób usług komunikacyjnych. Utwórz zasób usług komunikacyjnych.
Numer telefonu w zasobie usług Azure Communication Services, który może wykonywać połączenia wychodzące. Jeśli masz bezpłatną subskrypcję, możesz uzyskać numer telefonu w wersji próbnej.
Tworzenie i hostowanie aplikacji Azure Dev Tunnel. Instrukcje znajdują się tutaj.
Utwórz i połącz usługi Azure AI z wieloma usługami z zasobem usług Azure Communication Services.
Utwórz niestandardową poddomenę dla zasobu usług Azure AI.
Zestaw Java Development Kit (JDK) w wersji 11 lub nowszej.
Apache Maven.
(Opcjonalnie) Użytkownik usługi Microsoft Teams z włączoną licencją voice na telefon. Licencja na telefon usługi Teams jest wymagana do dodawania użytkowników usługi Teams do połączenia. Dowiedz się więcej o licencjach usługi Teams tutaj. Aby uzyskać więcej informacji na temat włączania voice w systemie telefonicznym, zobacz Konfigurowanie systemu telefonicznego.

Przykładowy kod

Pobierz lub sklonuj przykładowy kod szybki start z usługi GitHub.

Przejdź do CallAutomation_OutboundCalling folderu i otwórz rozwiązanie w edytorze kodu.

Konfigurowanie i hostowanie usługi Azure DevTunnel

Azure DevTunnels to usługa platformy Azure, która umożliwia udostępnianie lokalnych usług internetowych hostowanych w Internecie. Uruchom polecenia DevTunnel, aby połączyć lokalne środowisko programistyczne z publicznym Internetem. Usługa DevTunnels tworzy następnie tunel z trwałym adresem URL punktu końcowego i umożliwia dostęp anonimowy. Usługi Azure Communication Services używają tego punktu końcowego do powiadamiania aplikacji o wywołaniach zdarzeń z usługi Azure Communication Services Call Automation.

devtunnel create --allow-anonymous
devtunnel port create -p MY_SPRINGAPP_PORT
devtunnel host

Aktualizowanie konfiguracji aplikacji

Następnie otwórz application.yml plik w folderze /resources , aby skonfigurować następujące wartości:

connectionstring: parametry połączenia dla zasobu usług Azure Communication Services. Usługi Azure Communication Services parametry połączenia można znaleźć, korzystając z instrukcji dostępnych tutaj.
basecallbackuri: Po zainicjowaniu hosta Usługi DevTunnel zaktualizuj to pole za pomocą tego identyfikatora URI.
callerphonenumber: zaktualizuj to pole przy użyciu uzyskanego numeru telefonu usług Azure Communication Services. Ten numer telefonu powinien używać formatu numeru telefonu E164 (np. +18881234567)
targetphonenumber: zaktualizuj pole przy użyciu numeru telefonu, który ma być wywoływany przez aplikację. Ten numer telefonu powinien używać formatu numeru telefonu E164 (np. +18881234567)
cognitiveServiceEndpoint: zaktualizuj pole za pomocą punktu końcowego usług Azure AI.
targetTeamsUserId: (Opcjonalnie) pole aktualizacji przy użyciu identyfikatora użytkownika usługi Microsoft Teams, które chcesz dodać do wywołania. Zobacz Uzyskiwanie identyfikatora użytkownika aplikacji Teams przy użyciu interfejsu API programu Graph.

acs:
  connectionstring: <YOUR ACS CONNECTION STRING> 
  basecallbackuri: <YOUR DEV TUNNEL ENDPOINT> 
  callerphonenumber: <YOUR ACS PHONE NUMBER ex. "+1425XXXAAAA"> 
  targetphonenumber: <YOUR TARGET PHONE NUMBER ex. "+1425XXXAAAA"> 
  cognitiveServiceEndpoint: <YOUR COGNITIVE SERVICE ENDPOINT>
  targetTeamsUserId: <(OPTIONAL) YOUR TARGET TEAMS USER ID ex. "00aa00aa-bb11-cc22-dd33-44ee44ee44ee">

Nawiązywanie połączenia wychodzącego i odtwarzanie multimediów

Aby wykonać wywołanie wychodzące z usług Azure Communication Services, w tym przykładzie targetphonenumber użyto zdefiniowanego application.yml w pliku w celu utworzenia wywołania przy użyciu interfejsu createCallWithResponse API.

PhoneNumberIdentifier caller = new PhoneNumberIdentifier(appConfig.getCallerphonenumber());
PhoneNumberIdentifier target = new PhoneNumberIdentifier(appConfig.getTargetphonenumber());
CallInvite callInvite = new CallInvite(target, caller);
CreateCallOptions createCallOptions = new CreateCallOptions(callInvite, appConfig.getCallBackUri());
CallIntelligenceOptions callIntelligenceOptions = new CallIntelligenceOptions().setCognitiveServicesEndpoint(appConfig.getCognitiveServiceEndpoint());
createCallOptions = createCallOptions.setCallIntelligenceOptions(callIntelligenceOptions);
Response<CreateCallResult> result = client.createCallWithResponse(createCallOptions, Context.NONE);

(Opcjonalnie) Dodawanie użytkownika aplikacji Microsoft Teams do wywołania

Możesz dodać użytkownika usługi Microsoft Teams do wywołania przy użyciu addParticipant metody z identyfikatorem MicrosoftTeamsUserIdentifier użytkownika usługi Teams i identyfikatorem użytkownika usługi Teams. Najpierw należy wykonać krok wymagań wstępnych Autoryzacja zasobu usług Azure Communication Services, aby umożliwić wywoływanie użytkowników usługi Microsoft Teams. Opcjonalnie możesz również przekazać element , SourceDisplayName aby kontrolować tekst wyświetlany w wyskakującym powiadomieniu użytkownika usługi Teams.

client.getCallConnection(callConnectionId).addParticipant(
    new CallInvite(new MicrosoftTeamsUserIdentifier(targetTeamsUserId))
        .setSourceDisplayName("Jack (Contoso Tech Support)"));

Rozpoczynanie nagrywania połączenia

ServerCallLocator serverCallLocator = new ServerCallLocator(
    client.getCallConnection(callConnectionId)
        .getCallProperties()
        .getServerCallId());
        
StartRecordingOptions startRecordingOptions = new StartRecordingOptions(serverCallLocator);

Response<RecordingStateResult> response = client.getCallRecording()
    .startWithResponse(startRecordingOptions, Context.NONE);

recordingId = response.getValue().getRecordingId();

Reagowanie na zdarzenia wywołujące

Wcześniej w naszej aplikacji zarejestrowaliśmy basecallbackuri usługę Call Automation Service. Identyfikator URI wskazuje punkt końcowy, którego usługa będzie używać do powiadamiania nas o zdarzeniach wywołujących, które się zdarzają. Następnie możemy iterować zdarzenia i wykrywać określone zdarzenia, które chcemy zrozumieć w naszej aplikacji. W poniższym kodzie odpowiadamy na CallConnected zdarzenie.

List<CallAutomationEventBase> events = CallAutomationEventParser.parseEvents(reqBody);
for (CallAutomationEventBase event : events) {
    String callConnectionId = event.getCallConnectionId();
    if (event instanceof CallConnected) {
        log.info("CallConnected event received");
    }
    else if (event instanceof RecognizeCompleted) {
        log.info("Recognize Completed event received");
    }
}

Odtwórz wiadomość powitalną i rozpoznaj

var playSource = new TextSource().setText(content).setVoiceName("en-US-NancyNeural");

var recognizeOptions = new CallMediaRecognizeChoiceOptions(new PhoneNumberIdentifier(targetParticipant), getChoices())
  .setInterruptCallMediaOperation(false)
  .setInterruptPrompt(false)
  .setInitialSilenceTimeout(Duration.ofSeconds(10))
  .setPlayPrompt(playSource)
  .setOperationContext(context);

client.getCallConnection(callConnectionId)
  .getCallMedia()
  .startRecognizing(recognizeOptions);

private List < RecognitionChoice > getChoices() {
  var choices = Arrays.asList(
    new RecognitionChoice().setLabel(confirmLabel).setPhrases(Arrays.asList("Confirm", "First", "One")).setTone(DtmfTone.ONE),
    new RecognitionChoice().setLabel(cancelLabel).setPhrases(Arrays.asList("Cancel", "Second", "Two")).setTone(DtmfTone.TWO)
  );

  return choices;
}

Obsługa zdarzeń wyboru

else if (event instanceof RecognizeCompleted) {
  log.info("Recognize Completed event received");

  RecognizeCompleted acsEvent = (RecognizeCompleted) event;

  var choiceResult = (ChoiceResult) acsEvent.getRecognizeResult().get();

  String labelDetected = choiceResult.getLabel();

  String phraseDetected = choiceResult.getRecognizedPhrase();

  log.info("Recognition completed, labelDetected=" + labelDetected + ", phraseDetected=" + phraseDetected + ", context=" + event.getOperationContext());

  String textToPlay = labelDetected.equals(confirmLabel) ? confirmedText : cancelText;

  handlePlay(callConnectionId, textToPlay);
}

private void handlePlay(final String callConnectionId, String textToPlay) {
  var textPlay = new TextSource()
    .setText(textToPlay)
    .setVoiceName("en-US-NancyNeural");

  client.getCallConnection(callConnectionId)
    .getCallMedia()
    .playToAll(textPlay);
}

Zawieszanie połączenia

Na koniec, gdy wykryjemy warunek, który ma sens, aby zakończyć wywołanie, możemy użyć hangUp metody , aby zawiesić wywołanie.

client.getCallConnection(callConnectionId).hangUp(true);

Uruchamianie kodu

Przejdź do katalogu zawierającego plik pom.xml i użyj następujących poleceń mvn:

Skompiluj aplikację: mvn compile
Skompiluj pakiet: mvn package
Wykonaj aplikację: mvn exec:java

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Wdrożony zasób usług komunikacyjnych. Utwórz zasób usług komunikacyjnych.
Numer telefonu w zasobie usług Azure Communication Services, który może wykonywać połączenia wychodzące. Jeśli masz bezpłatną subskrypcję, możesz uzyskać numer telefonu w wersji próbnej.
Tworzenie i hostowanie aplikacji Azure Dev Tunnel. Instrukcje znajdują się tutaj.
- Utwórz i połącz usługi Azure AI z wieloma usługami z zasobem usług Azure Communication Services.
Utwórz niestandardową poddomenę dla zasobu usług Azure AI.
instalacja Node.js LTS.
Zainstalowany program Visual Studio Code .
(Opcjonalnie) Użytkownik usługi Microsoft Teams z włączoną licencją voice na telefon. Licencja na telefon usługi Teams jest wymagana do dodawania użytkowników usługi Teams do połączenia. Dowiedz się więcej o licencjach usługi Teams tutaj. Aby uzyskać więcej informacji na temat włączania voice w systemie telefonicznym, zobacz Konfigurowanie systemu telefonicznego.

Przykładowy kod

Pobierz lub sklonuj przykładowy kod szybki start z usługi GitHub.

Przejdź do CallAutomation_OutboundCalling folderu i otwórz rozwiązanie w edytorze kodu.

Konfigurowanie środowiska

Pobierz przykładowy kod i przejdź do katalogu projektu i uruchom npm polecenie, które instaluje niezbędne zależności i konfiguruje środowisko deweloperskie.

npm install

Konfigurowanie i hostowanie usługi Azure DevTunnel

Azure DevTunnels to usługa platformy Azure, która umożliwia udostępnianie lokalnych usług internetowych hostowanych w Internecie. Użyj poleceń interfejsu wiersza polecenia usługi DevTunnel, aby połączyć lokalne środowisko programistyczne z publicznym Internetem. Ten punkt końcowy służy do powiadamiania aplikacji o wywoływaniu zdarzeń z usługi Azure Communication Services Call Automation.

devtunnel create --allow-anonymous
devtunnel port create -p 8080
devtunnel host

Aktualizowanie konfiguracji aplikacji

Następnie zaktualizuj .env plik przy użyciu następujących wartości:

CONNECTION_STRING: parametry połączenia dla zasobu usług Azure Communication Services. Usługi Azure Communication Services parametry połączenia można znaleźć, korzystając z instrukcji dostępnych tutaj.
CALLBACK_URI: Po zainicjowaniu hosta Usługi DevTunnel zaktualizuj to pole za pomocą tego identyfikatora URI.
TARGET_PHONE_NUMBER: zaktualizuj pole przy użyciu numeru telefonu, który ma być wywoływany przez aplikację. Ten numer telefonu powinien używać formatu numeru telefonu E164 (np. +18881234567)
ACS_RESOURCE_PHONE_NUMBER: zaktualizuj to pole przy użyciu uzyskanego numeru telefonu usług Azure Communication Services. Ten numer telefonu powinien używać formatu numeru telefonu E164 (np. +18881234567)
COGNITIVE_SERVICES_ENDPOINT: zaktualizuj pole za pomocą punktu końcowego usług Azure AI.
TARGET_TEAMS_USER_ID: (Opcjonalnie) pole aktualizacji przy użyciu identyfikatora użytkownika usługi Microsoft Teams, które chcesz dodać do wywołania. Zobacz Uzyskiwanie identyfikatora użytkownika aplikacji Teams przy użyciu interfejsu API programu Graph.

CONNECTION_STRING="<YOUR_CONNECTION_STRING>" 
ACS_RESOURCE_PHONE_NUMBER ="<YOUR_ACS_NUMBER>" 
TARGET_PHONE_NUMBER="<+1XXXXXXXXXX>" 
CALLBACK_URI="<VS_TUNNEL_URL>" 
COGNITIVE_SERVICES_ENDPOINT="<COGNITIVE_SERVICES_ENDPOINT>" 
TARGET_TEAMS_USER_ID="<TARGET_TEAMS_USER_ID>"

Nawiązywanie połączenia wychodzącego i odtwarzanie multimediów

Aby nawiązać połączenie wychodzące z usług Azure Communication Services, użyj numeru telefonu podanego w środowisku. Upewnij się, że numer telefonu jest w formacie E164 (np. +18881234567)

Kod wykonuje wywołanie wychodzące przy użyciu podanego target_phone_number i umieść wywołanie wychodzące do tego numeru:

const callInvite: CallInvite = {
	targetParticipant: callee,
	sourceCallIdNumber: {
		phoneNumber: process.env.ACS_RESOURCE_PHONE_NUMBER || "",
	},
};

const options: CreateCallOptions = {
	cognitiveServicesEndpoint: process.env.COGNITIVE_SERVICES_ENDPOINT
};

console.log("Placing outbound call...");
acsClient.createCall(callInvite, process.env.CALLBACK_URI + "/api/callbacks", options);

(Opcjonalnie) Dodawanie użytkownika aplikacji Microsoft Teams do wywołania

Możesz dodać użytkownika aplikacji Microsoft Teams do wywołania przy użyciu addParticipant metody z właściwością microsoftTeamsUserId . Najpierw należy wykonać krok wymagań wstępnych Autoryzacja zasobu usług Azure Communication Services, aby umożliwić wywoływanie użytkowników usługi Microsoft Teams. Opcjonalnie możesz również przekazać element , sourceDisplayName aby kontrolować tekst wyświetlany w wyskakującym powiadomieniu użytkownika usługi Teams.

await acsClient.getCallConnection(callConnectionId).addParticipant({
    targetParticipant: { microsoftTeamsUserId: process.env.TARGET_TEAMS_USER_ID },
    sourceDisplayName: "Jack (Contoso Tech Support)"
});

Rozpoczynanie nagrywania połączenia

const callLocator: CallLocator = {
    id: serverCallId,
    kind: "serverCallLocator",
};

const recordingOptions: StartRecordingOptions = {
    callLocator: callLocator,
};

const response = await acsClient.getCallRecording().start(recordingOptions);

recordingId = response.recordingId;

Reagowanie na zdarzenia wywołujące

Wcześniej w naszej aplikacji zarejestrowaliśmy CALLBACK_URI usługę Call Automation Service. Identyfikator URI wskazuje punkt końcowy używany przez usługę do powiadamiania nas o zdarzeniach wywołujących, które się zdarzają. Następnie możemy iterować zdarzenia i wykrywać określone zdarzenia, które chcemy zrozumieć w naszej aplikacji. Reagujemy na zdarzenie, aby otrzymywać CallConnected powiadomienia i inicjować operacje podrzędne. TextSourceKorzystając z elementu , możesz udostępnić usłudze tekst, który ma zostać zsyntetyzowany i użyty na potrzeby wiadomości powitalnej. Usługa Azure Communication Services Call Automation odtwarza ten komunikat podczas CallConnected zdarzenia.

callConnectionId = eventData.callConnectionId;
serverCallId = eventData.serverCallId;
console.log("Call back event received, callConnectionId=%s, serverCallId=%s, eventType=%s", callConnectionId, serverCallId, event.type);
callConnection = acsClient.getCallConnection(callConnectionId);
const callMedia = callConnection.getCallMedia();

if (event.type === "Microsoft.Communication.CallConnected") {
 	console.log("Received CallConnected event");
 	await startRecording();
	await startRecognizing(callMedia, mainMenu, "");
}

async function startRecognizing(callMedia: CallMedia, textToPlay: string, context: string) {
	const playSource: TextSource = {
 		text: textToPlay,
 		voiceName: "en-US-NancyNeural",
 		kind: "textSource"
 	};

 	const recognizeOptions: CallMediaRecognizeChoiceOptions = {
 		choices: await getChoices(),
 		interruptPrompt: false,
 		initialSilenceTimeoutInSeconds: 10,
 		playPrompt: playSource,
 		operationContext: context,
 		kind: "callMediaRecognizeChoiceOptions"
 	};

 	await callMedia.startRecognizing(callee, recognizeOptions)
 }

Obsługa zdarzeń wyboru

else if (event.type === "Microsoft.Communication.RecognizeCompleted") { 
	if(eventData.recognitionType === "choices"){ 
        	console.log("Recognition completed, event=%s, resultInformation=%s",eventData, eventData.resultInformation); 
        	var context = eventData.operationContext; 
            	const labelDetected = eventData.choiceResult.label;  
            	const phraseDetected = eventData.choiceResult.recognizedPhrase; 
            	console.log("Recognition completed, labelDetected=%s, phraseDetected=%s, context=%s", labelDetected, phraseDetected, eventData.operationContext); 
            	const textToPlay = labelDetected === confirmLabel ? confirmText : cancelText;            
            	await handlePlay(callMedia, textToPlay); 
        } 
}  
 
async function handlePlay(callConnectionMedia:CallMedia, textContent:string){ 
	const play : TextSource = { text:textContent , voiceName: "en-US-NancyNeural", kind: "textSource"} 
	await callConnectionMedia.playToAll([play]); 
}

Zawieszanie połączenia

Na koniec, gdy wykryjemy warunek, który ma sens, aby zakończyć wywołanie, możemy użyć hangUp() metody , aby zawiesić wywołanie.

  await acsClient.getCallRecording().stop(recordingId);
  callConnection.hangUp(true);

Uruchamianie kodu

Aby uruchomić aplikację, otwórz okno terminalu i uruchom następujące polecenie:

  npm run dev

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Wdrożony zasób usług komunikacyjnych. Utwórz zasób usług komunikacyjnych.
Numer telefonu w zasobie usług Azure Communication Services, który może wykonywać połączenia wychodzące. Jeśli masz bezpłatną subskrypcję, możesz uzyskać numer telefonu w wersji próbnej.
Tworzenie i hostowanie aplikacji Azure Dev Tunnel. Instrukcje znajdują się tutaj.
Utwórz i połącz usługi Azure AI z wieloma usługami z zasobem usług Azure Communication Services.
Utwórz niestandardową poddomenę dla zasobu usług Azure AI.
Python 3.7+.
(Opcjonalnie) Użytkownik usługi Microsoft Teams z włączoną licencją voice na telefon. Licencja na telefon usługi Teams jest wymagana do dodawania użytkowników usługi Teams do połączenia. Dowiedz się więcej o licencjach usługi Teams tutaj. Aby uzyskać więcej informacji na temat włączania voice w systemie telefonicznym, zobacz Konfigurowanie systemu telefonicznego.

Przykładowy kod

Pobierz lub sklonuj przykładowy kod szybki start z usługi GitHub.

Przejdź do CallAutomation_OutboundCalling folderu i otwórz rozwiązanie w edytorze kodu.

Konfigurowanie środowiska języka Python

Utwórz i aktywuj środowisko języka Python i zainstaluj wymagane pakiety przy użyciu następującego polecenia. Więcej informacji na temat zarządzania pakietami można znaleźć tutaj

pip install -r requirements.txt

Konfigurowanie i hostowanie usługi Azure DevTunnel

Azure DevTunnels to usługa platformy Azure, która umożliwia udostępnianie lokalnych usług internetowych hostowanych w Internecie. Użyj poleceń , aby połączyć lokalne środowisko programistyczne z publicznym Internetem. Usługa DevTunnels tworzy tunel z trwałym adresem URL punktu końcowego i umożliwia dostęp anonimowy. Ten punkt końcowy służy do powiadamiania aplikacji o wywoływaniu zdarzeń z usługi Azure Communication Services Call Automation.

devtunnel create --allow-anonymous
devtunnel port create -p 8080
devtunnel host

Aktualizowanie konfiguracji aplikacji

Następnie zaktualizuj main.py plik przy użyciu następujących wartości:

ACS_CONNECTION_STRING: parametry połączenia dla zasobu usług Azure Communication Services. Usługi Azure Communication Services parametry połączenia można znaleźć, korzystając z instrukcji dostępnych tutaj.
CALLBACK_URI_HOST: Po zainicjowaniu hosta Usługi DevTunnel zaktualizuj to pole za pomocą tego identyfikatora URI.
TARGET_PHONE_NUMBER: zaktualizuj pole przy użyciu numeru telefonu, który ma być wywoływany przez aplikację. Ten numer telefonu powinien używać formatu numeru telefonu E164 (np. +18881234567)
ACS_PHONE_NUMBER: zaktualizuj to pole przy użyciu uzyskanego numeru telefonu usług Azure Communication Services. Ten numer telefonu powinien używać formatu numeru telefonu E164 (np. +18881234567)
COGNITIVE_SERVICES_ENDPOINT: zaktualizuj pole za pomocą punktu końcowego usług Azure AI.
TARGET_TEAMS_USER_ID: (Opcjonalnie) pole aktualizacji przy użyciu identyfikatora użytkownika usługi Microsoft Teams, które chcesz dodać do wywołania. Zobacz Uzyskiwanie identyfikatora użytkownika aplikacji Teams przy użyciu interfejsu API programu Graph.

# Your ACS resource connection string 
ACS_CONNECTION_STRING = "<ACS_CONNECTION_STRING>" 

# Your ACS resource phone number will act as source number to start outbound call 
ACS_PHONE_NUMBER = "<ACS_PHONE_NUMBER>" 

# Target phone number you want to receive the call. 
TARGET_PHONE_NUMBER = "<TARGET_PHONE_NUMBER>" 

# Callback events URI to handle callback events. 
CALLBACK_URI_HOST = "<CALLBACK_URI_HOST_WITH_PROTOCOL>" 
CALLBACK_EVENTS_URI = CALLBACK_URI_HOST + "/api/callbacks" 

#Your Cognitive service endpoint 
COGNITIVE_SERVICES_ENDPOINT = "<COGNITIVE_SERVICES_ENDPOINT>" 

#(OPTIONAL) Your target Microsoft Teams user Id ex. "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
TARGET_TEAMS_USER_ID = "<TARGET_TEAMS_USER_ID>"

Nawiązywanie połączenia wychodzącego

Aby nawiązać połączenie wychodzące z usług Azure Communication Services, najpierw podaj numer telefonu, który chcesz odebrać. Aby ułatwić sobie to, możesz zaktualizować target_phone_number numer telefonu przy użyciu numeru telefonu w formacie E164 (np. +18881234567)

Wykonaj wywołanie wychodzące przy użyciu podanego target_phone_number:

target_participant = PhoneNumberIdentifier(TARGET_PHONE_NUMBER) 
source_caller = PhoneNumberIdentifier(ACS_PHONE_NUMBER) 
call_invite = CallInvite(target=target_participant, source_caller_id_number=source_caller) 
call_connection_properties = call_automation_client.create_call(call_invite, CALLBACK_EVENTS_URI, 
cognitive_services_endpoint=COGNITIVE_SERVICES_ENDPOINT) 
    app.logger.info("Created call with connection id: %s",
call_connection_properties.call_connection_id) 
return redirect("/")

(Opcjonalnie) Dodawanie użytkownika aplikacji Microsoft Teams do wywołania

Możesz dodać użytkownika usługi Microsoft Teams do wywołania przy użyciu add_participant metody z identyfikatorem MicrosoftTeamsUserIdentifier użytkownika usługi Teams i identyfikatorem użytkownika usługi Teams. Najpierw należy wykonać krok wymagań wstępnych Autoryzacja zasobu usług Azure Communication Services, aby umożliwić wywoływanie użytkowników usługi Microsoft Teams. Opcjonalnie możesz również przekazać element , source_display_name aby kontrolować tekst wyświetlany w wyskakującym powiadomieniu użytkownika usługi Teams.

call_connection_client.add_participant(target_participant = CallInvite(
    target = MicrosoftTeamsUserIdentifier(user_id=TARGET_TEAMS_USER_ID),
    source_display_name = "Jack (Contoso Tech Support)"))

Rozpoczynanie nagrywania połączenia

recording_properties = call_automation_client.start_recording(ServerCallLocator(event.data['serverCallId']))
recording_id = recording_properties.recording_id

Reagowanie na zdarzenia wywołujące

Wcześniej w naszej aplikacji zarejestrowaliśmy CALLBACK_URI_HOST usługę Call Automation Service. Identyfikator URI wskazuje punkt końcowy używany przez usługę do powiadamiania nas o zdarzeniach wywołujących, które się zdarzają. Następnie możemy iterować zdarzenia i wykrywać określone zdarzenia, które chcemy zrozumieć w naszej aplikacji. W poniższym kodzie odpowiadamy na CallConnected zdarzenie.

@app.route('/api/callbacks', methods=['POST'])
def callback_events_handler():
    for event_dict in request.json:
        event = CloudEvent.from_dict(event_dict)
        if event.type == "Microsoft.Communication.CallConnected":
            # Handle Call Connected Event
            ...
            return Response(status=200)

Odtwórz wiadomość powitalną i rozpoznaj


get_media_recognize_choice_options( 
    call_connection_client=call_connection_client, 
    text_to_play=MainMenu,  
    target_participant=target_participant, 
    choices=get_choices(),context="") 

def get_media_recognize_choice_options(call_connection_client: CallConnectionClient, text_to_play: str, target_participant:str, choices: any, context: str): 
    play_source =  TextSource (text= text_to_play, voice_name= SpeechToTextVoice) 
    call_connection_client.start_recognizing_media( 
        input_type=RecognizeInputType.CHOICES, 

        target_participant=target_participant,
        choices=choices, 
        play_prompt=play_source, 
        interrupt_prompt=False, 
        initial_silence_timeout=10, 
        operation_context=context 
    ) 

def get_choices(): 
    choices = [ 
        RecognitionChoice(label = ConfirmChoiceLabel, phrases= ["Confirm", "First", "One"], tone = DtmfTone.ONE), 
        RecognitionChoice(label = CancelChoiceLabel, phrases= ["Cancel", "Second", "Two"], tone = DtmfTone.TWO) 
    ] 
return choices

Obsługa zdarzeń wyboru

elif event.type == "Microsoft.Communication.RecognizeCompleted":
	app.logger.info("Recognize completed: data=%s", event.data)
if event.data['recognitionType'] == "choices":
	labelDetected = event.data['choiceResult']['label'];
phraseDetected = event.data['choiceResult']['recognizedPhrase'];
app.logger.info("Recognition completed, labelDetected=%s, phraseDetected=%s, context=%s", labelDetected, phraseDetected, event.data.get('operationContext'))
if labelDetected == ConfirmChoiceLabel:
	textToPlay = ConfirmedText
else:
	textToPlay = CancelText
handle_play(call_connection_client = call_connection_client, text_to_play = textToPlay)
def handle_play(call_connection_client: CallConnectionClient, text_to_play: str):
	play_source = TextSource(text = text_to_play, voice_name = SpeechToTextVoice)
call_connection_client.play_media_to_all(play_source)

Zawieszanie połączenia

Na koniec, gdy wykryjemy warunek, który ma sens, aby zakończyć wywołanie, możemy użyć hang_up() metody , aby zawiesić wywołanie. Na koniec możemy również bezpiecznie zatrzymać operację nagrywania wywołań.

call_automation_client.stop_recording(recording_id)
call_connection_client.hang_up(is_for_everyone=True)

Uruchamianie kodu

Visual Studio Code
Program Visual Studio

Aby uruchomić aplikację za pomocą programu VS Code, otwórz okno terminalu i uruchom następujące polecenie

python main.py

Udostępnij za pośrednictwem

Szybki start: wykonywanie wywołań wychodzących przy użyciu usługi Call Automation

Wymagania wstępne

Przykładowy kod

Konfigurowanie i hostowanie usługi Azure DevTunnel

Aktualizowanie konfiguracji aplikacji

Nawiązywanie połączenia wychodzącego

Obsługa zdarzeń automatyzacji wywołań

(Opcjonalnie) Dodawanie użytkownika aplikacji Microsoft Teams do wywołania

Rozpoczynanie nagrywania połączenia

Odtwórz wiadomość powitalną i rozpoznaj

Obsługa zdarzeń wyboru

Zawieszanie się i zatrzymywanie nagrywania

Uruchamianie kodu

Wymagania wstępne

Przykładowy kod

Konfigurowanie i hostowanie usługi Azure DevTunnel

Aktualizowanie konfiguracji aplikacji

Nawiązywanie połączenia wychodzącego i odtwarzanie multimediów

(Opcjonalnie) Dodawanie użytkownika aplikacji Microsoft Teams do wywołania

Rozpoczynanie nagrywania połączenia

Reagowanie na zdarzenia wywołujące

Odtwórz wiadomość powitalną i rozpoznaj

Obsługa zdarzeń wyboru

Zawieszanie połączenia

Uruchamianie kodu

Wymagania wstępne

Przykładowy kod

Konfigurowanie środowiska

Konfigurowanie i hostowanie usługi Azure DevTunnel

Aktualizowanie konfiguracji aplikacji

Nawiązywanie połączenia wychodzącego i odtwarzanie multimediów

(Opcjonalnie) Dodawanie użytkownika aplikacji Microsoft Teams do wywołania

Rozpoczynanie nagrywania połączenia

Reagowanie na zdarzenia wywołujące

Obsługa zdarzeń wyboru

Zawieszanie połączenia

Uruchamianie kodu

Wymagania wstępne

Przykładowy kod

Konfigurowanie środowiska języka Python

Konfigurowanie i hostowanie usługi Azure DevTunnel

Aktualizowanie konfiguracji aplikacji

Nawiązywanie połączenia wychodzącego

(Opcjonalnie) Dodawanie użytkownika aplikacji Microsoft Teams do wywołania

Rozpoczynanie nagrywania połączenia

Reagowanie na zdarzenia wywołujące

Odtwórz wiadomość powitalną i rozpoznaj

Obsługa zdarzeń wyboru

Zawieszanie połączenia

Uruchamianie kodu

Opinia

Dodatkowe zasoby