Freigeben über

Schnellstart: Tätigen eines ausgehenden Anrufs mithilfe der Anrufautomatisierung

  • Artikel

Die Azure Communication Services-APIs für die Anrufautomatisierung stellen eine leistungsstarke Möglichkeit für die Tätigung interaktiver Anrufe dar. In diesem Schnellstart erfahren Sie, wie Sie einen ausgehenden Anruf tätigen und verschiedene Ereignisse im Anruf erkennen können.

Voraussetzungen

Beispielcode

Downloaden oder klonen Sie den Schnellstart-Beispielcode aus GitHub.

Navigieren Sie zum Ordner CallAutomation_OutboundCalling, und öffnen Sie die Projektmappe in einem Code-Editor.

Einrichten und Hosten Ihres Azure DevTunnels

Azure DevTunnels ist ein Azure-Dienst, mit dem Sie im Internet gehostete lokale Webdienste freigeben können. Führen Sie die Befehle aus, um Ihre lokale Entwicklungsumgebung mit dem öffentlichen Internet zu verbinden. DevTunnels erstellt eine persistente Endpunkt-URL, die anonymen Zugriff zulässt. Dieser Endpunkt wird anschließend verwendet, um Ihre Anwendung über Anrufereignisse vom Azure Communication Services-Dienst für die Anrufautomatisierung zu benachrichtigen.

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

Folgen Sie alternativ den Anweisungen zum Einrichten Ihres Azure DevTunnel in Visual Studio.

Aktualisieren Ihrer Anwendungskonfiguration

Aktualisieren Sie als Nächstes Ihre Program.cs-Datei mit den folgenden Werten:

  • acsConnectionString: Geben Sie die Verbindungszeichenfolge für Ihre Azure Communications Service-Ressource ein. Ihre Azure Communication Services finden Sie in den Anweisungen hier.
  • callbackUriHost: Nachdem Sie Ihren DevTunnel-Host initialisiert haben, aktualisieren Sie dieses Feld mit diesem URI.
  • acsPhonenumber: Aktualisieren Sie dieses Feld mit der Azure Communication Services, die Sie erworben haben. Diese Telefonnummer sollte das E164-Telefonnummernformat verwenden (z. B. +18881234567).
  • targetPhonenumber: Aktualisieren Sie das Feld mit der Telefonnummer, die Ihre Anwendung anrufen soll. Diese Telefonnummer sollte das E164-Telefonnummernformat verwenden (z. B. +18881234567).
  • cognitiveServiceEndpoint: Aktualisieren Sie das Feld mit Ihrem Azure KI Services-Endpunkt.
  • targetTeamsUserId: (Optional) Aktualisieren Sie das Feld mit der Microsoft Teams-Benutzer-ID, die Sie dem Anruf hinzufügen möchten. Siehe Verwenden der Graph-API zum Abrufen der Teams-Benutzer-ID.
// 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>";

Ausführen eines ausgehenden Anrufs

Um den ausgehenden Anruf von Azure Communication Services auszuführen, verwendet dieses Beispiel die targetPhonenumber, die Sie zuvor in der Anwendung definiert haben, um den Anruf mithilfe der CreateCallAsync-API zu erstellen. Dieser Code führt einen ausgehenden Anruf mit der Zieltelefonnummer aus.

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);

Behandeln von Anrufautomatisierungsereignissen

Zuvor in Ihrer Anwendung haben Sie den callbackUriHost beim Anrufautomatisierungsdienst registriert. Der Host gibt den Endpunkt an, den der Dienst benötigt, um Sie über Anrufereignisse zu benachrichtigen. Anschließend können Sie die Ereignisse durchlaufen und bestimmte Ereignisse erkennen, die Ihre Anwendung verstehen möchte. Im folgenden Code antworten Sie auf das CallConnected-Ereignis.

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
    }
  }
});

(Optional) Hinzufügen eines Microsoft Teams-Benutzers zum Anruf

Sie können dem Anruf einen Microsoft Teams-Benutzer mithilfe der AddParticipantAsync-Methode mit MicrosoftTeamsUserIdentifier und der ID des Teams-Benutzers hinzufügen. Sie müssen zuerst den erforderlichen Schritt Autorisierung für Ihre Azure Communication Services-Ressource zum Aktivieren des Anrufs an Microsoft Teams-Benutzer ausführen. Optional können Sie auch ein SourceDisplayName übergeben, um den Text zu steuern, der in der Toast-Benachrichtigung für den Teams-Benutzer angezeigt wird.

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

Starten der Aufzeichnung eines Anrufs

Der Anrufautomatisierungsdienst ermöglicht auch das Starten der Aufzeichnung und Speichern der Aufzeichnungen von Sprach- und Videoanrufen. Weitere Informationen zu den verschiedenen Funktionen in den APIs für die Anrufaufzeichnung finden Sie hier.

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

Wiedergabe der Willkommensnachricht und Erkennen des Anrufs

Mit TextSource können Sie dem Dienst den Text bereitstellen, den Sie synthetisiert haben möchten und für Ihre Willkommensnachricht verwenden möchten. Der Azure Communication Services spielt diese Nachricht ab, wenn das CallConnected-Ereignis erkannt wird.

Als Nächstes übergeben Sie den Text an CallMediaRecognizeChoiceOptions und rufen dann StartRecognizingAsync auf. Auf diese Weise kann Ihre Anwendung die vom Anrufer ausgewählte Option erkennen.

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
    }
  };
}

Umgang mit Choice-Ereignissen

Azure Communication Services Call Automation löst das Ereignis api/callbacks an den von uns eingerichteten Webhook aus und benachrichtigt uns mit dem Ereignis RecognizeCompleted. Das Ereignis gibt Ihnen die Möglichkeit, auf empfangene Eingaben zu reagieren und eine Aktion auszulösen. Die Anwendung gibt dann basierend auf der empfangenen Eingabe eine Nachricht an den Anrufer weiter.

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);
}

Auflegen und Beenden der Aufzeichnung

Wenn Sie schließlich eine Bedingung erkennen, die für das Beenden des Anrufs spricht, können Sie die HangUpAsync-Methode verwenden, um aufzulegen.

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

Ausführen des Codes

Um die Anwendung mit VS Code auszuführen, öffnen Sie ein Terminalfenster, und führen Sie den folgenden Befehl aus.

dotnet run

Öffnen Sie http://localhost:8080/swagger/index.html oder Ihre Dev-Tunnel-URL im Browser. Die Tunnel-URL sieht wie folgt aus: <YOUR DEV TUNNEL ENDPOINT>/swagger/index.html

Voraussetzungen

Beispielcode

Downloaden oder klonen Sie den Schnellstart-Beispielcode aus GitHub.

Navigieren Sie zum Ordner CallAutomation_OutboundCalling, und öffnen Sie die Projektmappe in einem Code-Editor.

Einrichten und Hosten Ihres Azure DevTunnels

Azure DevTunnels ist ein Azure-Dienst, mit dem Sie im Internet gehostete lokale Webdienste freigeben können. Führen Sie die BDevTunnel-Befehle aus, um Ihre lokale Entwicklungsumgebung mit dem öffentlichen Internet zu verbinden. DevTunnels erstellt einen Tunnel mit einer persistenten Endpunkt-URL, die anonymen Zugriff zulässt. Azure Communication Services verwendet diesen Endpunkt, um Ihre Anwendung über Anrufereignisse vom Azure Communication Services-Dienst für die Anrufautomatisierung zu benachrichtigen.

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

Aktualisieren Ihrer Anwendungskonfiguration

Öffnen Sie dann die Datei application.yml im Ordner /resources, um die folgenden Werte zu konfigurieren:

  • connectionstring: Geben Sie die Verbindungszeichenfolge für Ihre Azure Communications Service-Ressource ein. Ihre Azure Communication Services finden Sie in den Anweisungen hier.
  • basecallbackuri: Nachdem Sie Ihren DevTunnel-Host initialisiert haben, aktualisieren Sie dieses Feld mit diesem URI.
  • callerphonenumber: Aktualisieren Sie dieses Feld mit der Azure Communication Services, die Sie erworben haben. Diese Telefonnummer sollte das E164-Telefonnummernformat verwenden (z. B. +18881234567).
  • targetphonenumber: Aktualisieren Sie das Feld mit der Telefonnummer, die Ihre Anwendung anrufen soll. Diese Telefonnummer sollte das E164-Telefonnummernformat verwenden (z. B. +18881234567).
  • cognitiveServiceEndpoint: Aktualisieren Sie das Feld mit Ihrem Azure KI Services-Endpunkt.
  • targetTeamsUserId: (Optional) Aktualisieren Sie das Feld mit der Microsoft Teams-Benutzer-ID, die Sie dem Anruf hinzufügen möchten. Siehe Verwenden der Graph-API zum Abrufen der Teams-Benutzer-ID.
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">

Tätigen eines ausgehenden Anrufs und Wiedergeben von Medien

Um den ausgehenden Anruf von Azure Communication Services auszuführen, verwendet dieses Beispiel die targetphonenumber, die Sie in der application.yml-Datei definiert haben, um den Anruf mithilfe der createCallWithResponse-API zu erstellen.

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);

(Optional) Hinzufügen eines Microsoft Teams-Benutzers zum Anruf

Sie können dem Anruf einen Microsoft Teams-Benutzer mithilfe der addParticipant-Methode mit MicrosoftTeamsUserIdentifier und der ID des Teams-Benutzers hinzufügen. Sie müssen zuerst den erforderlichen Schritt Autorisierung für Ihre Azure Communication Services-Ressource zum Aktivieren des Anrufs an Microsoft Teams-Benutzer ausführen. Optional können Sie auch ein SourceDisplayName übergeben, um den Text zu steuern, der in der Toast-Benachrichtigung für den Teams-Benutzer angezeigt wird.

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

Starten der Aufzeichnung eines Anrufs

Der Anrufautomatisierungsdienst ermöglicht auch das Starten der Aufzeichnung und Speichern der Aufzeichnungen von Sprach- und Videoanrufen. Weitere Informationen zu den verschiedenen Funktionen in den APIs für die Anrufaufzeichnung finden Sie hier.

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();

Beantworten von Anrufereignissen

Zuvor in Ihrer Anwendung haben Sie den basecallbackuri beim Anrufautomatisierungsdienst registriert. Der URI gibt den Endpunkt an, den der Dienst verwendet, um Sie über Anrufereignisse zu benachrichtigen. Anschließend können Sie die Ereignisse durchlaufen und bestimmte Ereignisse erkennen, die Ihre Anwendung verstehen möchte. Im folgenden Code antworten Sie auf das CallConnected-Ereignis.

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");
    }
}

Wiedergabe der Willkommensnachricht und Erkennen von Anrufereignissen

Mit TextSource können Sie dem Dienst den Text bereitstellen, den Sie synthetisiert haben möchten und für Ihre Willkommensnachricht verwenden möchten. Der Azure Communication Services spielt diese Nachricht ab, wenn das CallConnected-Ereignis erkannt wird.

Als Nächstes übergeben Sie den Text an CallMediaRecognizeChoiceOptions und rufen dann StartRecognizingAsync auf. Auf diese Weise kann Ihre Anwendung die vom Anrufer ausgewählte Option erkennen.

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;
}

Umgang mit Choice-Ereignissen

Azure Communication Services Call Automation löst das Ereignis api/callbacks an den von uns eingerichteten Webhook aus und benachrichtigt uns mit dem Ereignis RecognizeCompleted. Das Ereignis gibt Ihnen die Möglichkeit, auf empfangene Eingaben zu reagieren und eine Aktion auszulösen. Die Anwendung gibt dann basierend auf der empfangenen Eingabe eine Nachricht an den Anrufer weiter.

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);
}

Beenden des Aufrufs

Wenn Sie schließlich eine Bedingung erkennen, die für das Beenden des Anrufs spricht, können Sie die hangUp-Methode verwenden, um aufzulegen.

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

Ausführen des Codes

Navigieren Sie zum Verzeichnis, das die pom.xml-Datei enthält, und verwenden Sie die folgenden mvn-Befehle:

  • Kompilieren der Anwendung: mvn compile
  • Erstellen des Pakets: mvn package
  • Ausführen der Anwendung: mvn exec:java

Voraussetzungen

Beispielcode

Downloaden oder klonen Sie den Schnellstart-Beispielcode aus GitHub.

Navigieren Sie zum Ordner CallAutomation_OutboundCalling, und öffnen Sie die Projektmappe in einem Code-Editor.

Einrichten der Umgebung

Laden Sie den Beispielcode herunter, navigieren Sie zum Projektverzeichnis, und führen Sie den npm-Befehl aus, mit dem die erforderlichen Abhängigkeiten installiert werden, und richten Sie Ihre Entwicklerumgebung ein.

npm install

Einrichten und Hosten Ihres Azure DevTunnels

Azure DevTunnels ist ein Azure-Dienst, mit dem Sie im Internet gehostete lokale Webdienste freigeben können. Führen Sie die DevTunnel-CLI-Befehle aus, um Ihre lokale Entwicklungsumgebung mit dem öffentlichen Internet zu verbinden. Dieser Endpunkt wird anschließend verwendet, um Ihre Anwendung über Anrufereignisse vom Azure Communication Services-Dienst für die Anrufautomatisierung zu benachrichtigen.

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

Aktualisieren Ihrer Anwendungskonfiguration

Aktualisieren Sie als Nächstes Ihre .env-Datei mit den folgenden Werten:

  • CONNECTION_STRING: Geben Sie die Verbindungszeichenfolge für Ihre Azure Communications Service-Ressource ein. Ihre Azure Communication Services finden Sie in den Anweisungen hier.
  • CALLBACK_URI: Nachdem Sie Ihren DevTunnel-Host initialisiert haben, aktualisieren Sie dieses Feld mit diesem URI.
  • TARGET_PHONE_NUMBER: Aktualisieren Sie das Feld mit der Telefonnummer, die Ihre Anwendung anrufen soll. Diese Telefonnummer sollte das E164-Telefonnummernformat verwenden (z. B. +18881234567).
  • ACS_RESOURCE_PHONE_NUMBER: Aktualisieren Sie dieses Feld mit der Azure Communication Services, die Sie erworben haben. Diese Telefonnummer sollte das E164-Telefonnummernformat verwenden (z. B. +18881234567).
  • COGNITIVE_SERVICES_ENDPOINT: Aktualisieren Sie das Feld mit Ihrem Azure KI Services-Endpunkt.
  • TARGET_TEAMS_USER_ID: (Optional) Aktualisieren Sie das Feld mit der Microsoft Teams-Benutzer-ID, die Sie dem Anruf hinzufügen möchten. Siehe Verwenden der Graph-API zum Abrufen der Teams-Benutzer-ID.
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>"

Tätigen eines ausgehenden Anrufs und Wiedergeben von Medien

Zum Tätigen des ausgehenden Anrufs von Azure Communication Services verwenden Sie die Telefonnummer, die Sie der Umgebung angegeben haben. Stellen Sie sicher, dass die Telefonnummer im E164-Telefonnummernformat vorliegt (z. B. +18881234567).

Der Code führt einen ausgehenden Anruf mithilfe der target_phone_number aus, die Sie bereitgestellt haben, und tätigt einen ausgehenden Anruf an diese Nummer:

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);

(Optional) Hinzufügen eines Microsoft Teams-Benutzers zum Anruf

Sie können dem Anruf einen Microsoft Teams-Benutzer mithilfe der addParticipant-Methode mit der microsoftTeamsUserId-Eigenschaft hinzufügen. Sie müssen zuerst den erforderlichen Schritt Autorisierung für Ihre Azure Communication Services-Ressource zum Aktivieren des Anrufs an Microsoft Teams-Benutzer ausführen. Optional können Sie auch ein sourceDisplayName übergeben, um den Text zu steuern, der in der Toast-Benachrichtigung für den Teams-Benutzer angezeigt wird.

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

Starten der Aufzeichnung eines Anrufs

Der Anrufautomatisierungsdienst ermöglicht auch das Starten der Aufzeichnung und Speichern der Aufzeichnungen von Sprach- und Videoanrufen. Weitere Informationen zu den verschiedenen Funktionen in den APIs für die Anrufaufzeichnung finden Sie hier.

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

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

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

recordingId = response.recordingId;

Beantworten von Anrufereignissen

Zuvor in Ihrer Anwendung haben Sie den CALLBACK_URI beim Anrufautomatisierungsdienst registriert. Der URI gibt den Endpunkt an, den der Dienst verwendet, um Sie über Anrufereignisse zu benachrichtigen. Anschließend können Sie die Ereignisse durchlaufen und bestimmte Ereignisse erkennen, die Ihre Anwendung verstehen möchte. Sie reagieren auf das CallConnected-Ereignis, um benachrichtigt zu werden und Downstreamvorgänge zu initiieren. Mit TextSource können Sie dem Dienst den Text bereitstellen, den Sie synthetisiert haben möchten und für Ihre Willkommensnachricht verwenden möchten. Der Azure Communication Services spielt diese Nachricht ab, wenn das CallConnected-Ereignis erkannt wird.

Als Nächstes übergeben Sie den Text an CallMediaRecognizeChoiceOptions und rufen dann StartRecognizingAsync auf. Auf diese Weise kann Ihre Anwendung die vom Anrufer ausgewählte Option erkennen.

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)
 }

Umgang mit Choice-Ereignissen

Azure Communication Services Call Automation löst das Ereignis api/callbacks an den von uns eingerichteten Webhook aus und benachrichtigt uns mit dem Ereignis RecognizeCompleted. Das Ereignis gibt Ihnen die Möglichkeit, auf empfangene Eingaben zu reagieren und eine Aktion auszulösen. Die Anwendung gibt dann basierend auf der empfangenen Eingabe eine Nachricht an den Anrufer weiter.

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]); 
}

Beenden des Aufrufs

Wenn Sie schließlich eine Bedingung erkennen, die für das Beenden des Anrufs spricht, können Sie die hangUp()-Methode verwenden, um aufzulegen.

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

Ausführen des Codes

Um die Anwendung mit VS Code auszuführen, öffnen Sie ein Terminalfenster, und führen Sie den folgenden Befehl aus:

  npm run dev

Voraussetzungen

Beispielcode

Downloaden oder klonen Sie den Schnellstart-Beispielcode aus GitHub.

Navigieren Sie zum Ordner CallAutomation_OutboundCalling, und öffnen Sie die Projektmappe in einem Code-Editor.

Einrichten der Python-Umgebung

Erstellen und aktivieren Sie die Python-Umgebung, und installieren Sie die erforderlichen Pakete mithilfe des folgenden Befehls. Weitere Informationen zum Verwalten von Paketen finden Sie hier.

pip install -r requirements.txt

Einrichten und Hosten Ihres Azure DevTunnels

Azure DevTunnels ist ein Azure-Dienst, mit dem Sie im Internet gehostete lokale Webdienste freigeben können. Führen Sie die Befehle aus, um Ihre lokale Entwicklungsumgebung mit dem öffentlichen Internet zu verbinden. DevTunnels erstellt einen Tunnel mit einer persistenten Endpunkt-URL, die anonymen Zugriff zulässt. Dieser Endpunkt wird anschließend verwendet, um Ihre Anwendung über Anrufereignisse vom Azure Communication Services-Dienst für die Anrufautomatisierung zu benachrichtigen.

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

Aktualisieren Ihrer Anwendungskonfiguration

Aktualisieren Sie als Nächstes Ihre main.py-Datei mit den folgenden Werten:

  • ACS_CONNECTION_STRING: Geben Sie die Verbindungszeichenfolge für Ihre Azure Communications Service-Ressource ein. Ihre Azure Communication Services finden Sie in den Anweisungen hier.
  • CALLBACK_URI_HOST: Nachdem Sie Ihren DevTunnel-Host initialisiert haben, aktualisieren Sie dieses Feld mit diesem URI.
  • TARGET_PHONE_NUMBER: Aktualisieren Sie das Feld mit der Telefonnummer, die Ihre Anwendung anrufen soll. Diese Telefonnummer sollte das E164-Telefonnummernformat verwenden (z. B. +18881234567).
  • ACS_PHONE_NUMBER: Aktualisieren Sie dieses Feld mit der Azure Communication Services, die Sie erworben haben. Diese Telefonnummer sollte das E164-Telefonnummernformat verwenden (z. B. +18881234567).
  • COGNITIVE_SERVICES_ENDPOINT: Aktualisieren Sie das Feld mit Ihrem Azure KI Services-Endpunkt.
  • TARGET_TEAMS_USER_ID: (Optional) Aktualisieren Sie das Feld mit der Microsoft Teams-Benutzer-ID, die Sie dem Anruf hinzufügen möchten. Siehe Verwenden der Graph-API zum Abrufen der Teams-Benutzer-ID.
# 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>"

Ausführen eines ausgehenden Anrufs

Um den ausgehenden Anruf von Azure Communication Services zu tätigen, geben Sie zuerst die Telefonnummer an, unter der Sie den Anruf empfangen möchten. Um es einfach zu machen, können Sie die target_phone_number mit einer Telefonnummer im E164-Telefonnummernformat (z.B. +18881234567) aktualisieren.

Führen Sie einen ausgehenden Anruf aus, indem Sie die von Ihnen angegebene target_phone_number verwenden:

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("/")

(Optional) Hinzufügen eines Microsoft Teams-Benutzers zum Anruf

Sie können dem Anruf einen Microsoft Teams-Benutzer mithilfe der add_participant-Methode mit MicrosoftTeamsUserIdentifier und der ID des Teams-Benutzers hinzufügen. Sie müssen zuerst den erforderlichen Schritt Autorisierung für Ihre Azure Communication Services-Ressource zum Aktivieren des Anrufs an Microsoft Teams-Benutzer ausführen. Optional können Sie auch ein source_display_name übergeben, um den Text zu steuern, der in der Toast-Benachrichtigung für den Teams-Benutzer angezeigt wird.

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

Starten der Aufzeichnung eines Anrufs

Der Anrufautomatisierungsdienst ermöglicht auch das Starten der Aufzeichnung und Speichern der Aufzeichnungen von Sprach- und Videoanrufen. Weitere Informationen zu den verschiedenen Funktionen in den APIs für die Anrufaufzeichnung finden Sie hier.

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

Beantworten von Anrufereignissen

Zuvor in Ihrer Anwendung haben Sie den CALLBACK_URI_HOST beim Anrufautomatisierungsdienst registriert. Der URI gibt den Endpunkt an, den der Dienst verwendet, um Sie über Anrufereignisse zu benachrichtigen. Anschließend können Sie die Ereignisse durchlaufen und bestimmte Ereignisse erkennen, die Ihre Anwendung verstehen möchte. Im folgenden Code antworten Sie auf das CallConnected-Ereignis.

@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)

Wiedergabe der Willkommensnachricht und Erkennen von Anrufereignissen

Mit TextSource können Sie dem Dienst den Text bereitstellen, den Sie synthetisiert haben möchten und für Ihre Willkommensnachricht verwenden möchten. Der Azure Communication Services spielt diese Nachricht ab, wenn das CallConnected-Ereignis erkannt wird.

Als Nächstes übergeben Sie den Text an CallMediaRecognizeChoiceOptions und rufen dann StartRecognizingAsync auf. Auf diese Weise kann Ihre Anwendung die vom Anrufer ausgewählte Option erkennen.


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

Umgang mit Choice-Ereignissen

Azure Communication Services Call Automation löst das Ereignis api/callbacks an den von uns eingerichteten Webhook aus und benachrichtigt uns mit dem Ereignis RecognizeCompleted. Das Ereignis gibt Ihnen die Möglichkeit, auf empfangene Eingaben zu reagieren und eine Aktion auszulösen. Die Anwendung gibt dann basierend auf der empfangenen Eingabe eine Nachricht an den Anrufer weiter.

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)

Beenden des Aufrufs

Wenn Sie schließlich eine Bedingung erkennen, die für das Beenden des Anrufs spricht, können Sie die hang_up()-Methode verwenden, um aufzulegen. Abschließend können Sie auch den Anrufaufzeichnungsvorgang sicher beenden.

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

Ausführen des Codes

Um die Anwendung mit VS Code auszuführen, öffnen Sie ein Terminalfenster, und führen Sie den folgenden Befehl aus.

python main.py