Quickstart: Een uitgaande oproep maken met behulp van Gespreksautomatisering

  • Artikel

Azure Communication Services Call Automation-API's zijn een krachtige manier om interactieve belervaringen te maken. In deze quickstart behandelen we een manier om een uitgaande oproep te maken en verschillende gebeurtenissen in de oproep te herkennen.

Vereisten

  • Een Azure-account met een actief abonnement. Gratis een account maken
  • Een geïmplementeerde Communication Services-resource. Een Communication Services-resource maken.
  • Een telefoonnummer in uw Azure Communication Services-resource waarmee uitgaande oproepen kunnen worden uitgevoerd. Als u een gratis abonnement hebt, kunt u een proeftelefoonnummer krijgen.
  • Een Azure Dev Tunnel maken en hosten. Instructies hier.
  • Een Azure AI-services met meerdere services maken en verbinden met uw Azure Communication Services-resource.
  • Maak een aangepast subdomein voor uw Azure AI-servicesresource.
  • (Optioneel) Een Microsoft Teams-gebruiker met een telefoonlicentie die is voice ingeschakeld. Teams-telefoonlicentie is vereist om Teams-gebruikers toe te voegen aan het gesprek. Meer informatie over Teams-licenties vindt u hier. Hier vindt u meer informatie over het inschakelen van het telefoonsysteemvoice.

Voorbeeldcode

Download of kloon quickstart-voorbeeldcode van GitHub.

Navigeer naar CallAutomation_OutboundCalling de map en open de oplossing in een code-editor.

Uw Azure DevTunnel instellen en hosten

Azure DevTunnels is een Azure-service waarmee u lokale webservices kunt delen die worden gehost op internet. Voer de opdrachten uit om uw lokale ontwikkelomgeving te verbinden met het openbare internet. DevTunnels maakt een permanente eindpunt-URL en biedt anonieme toegang. We gebruiken dit eindpunt om uw toepassing op de hoogte te stellen van het aanroepen van gebeurtenissen van de Azure Communication Services Call Automation-service.

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

Uw toepassingsconfiguratie bijwerken

Werk het Program.cs bestand vervolgens bij met de volgende waarden:

  • acsConnectionString: de verbindingsreeks voor uw Azure Communication Services-resource. U vindt uw Azure Communication Services-verbindingsreeks met behulp van de instructies hier.
  • callbackUriHost: Nadat uw DevTunnel-host is geïnitialiseerd, werkt u dit veld bij met die URI.
  • acsPhonenumber: werk dit veld bij met het Azure Communication Services-telefoonnummer dat u hebt verkregen. Dit telefoonnummer moet de notatie E164-telefoonnummer gebruiken (bijvoorbeeld +18881234567)
  • targetPhonenumber: werk het veld bij met het telefoonnummer dat u wilt bellen door uw toepassing. Dit telefoonnummer moet de notatie E164-telefoonnummer gebruiken (bijvoorbeeld +18881234567)
  • cognitiveServiceEndpoint: veld bijwerken met uw Azure AI-services-eindpunt.
  • targetTeamsUserId: (Optioneel) bijwerken met de gebruikers-id van Microsoft Teams die u aan de oproep wilt toevoegen. Zie Graph API gebruiken om gebruikers-id van Teams op te halen.
// 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>";

Een uitgaande oproep maken

Als u de uitgaande aanroep vanuit Azure Communication Services wilt maken, gebruikt dit voorbeeld het targetPhonenumber voorbeeld dat u eerder in de toepassing hebt gedefinieerd om de aanroep te maken met behulp van de CreateCallAsync API. Met deze code wordt een uitgaande oproep uitgevoerd met behulp van het doeltelefoonnummer.

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

Oproepautomatiseringsevenementen verwerken

Eerder in onze toepassing hebben we de callbackUriHost aanroepautomatiseringsservice geregistreerd. De host geeft het eindpunt aan dat de service vereist om ons op de hoogte te stellen van aanroepende gebeurtenissen die plaatsvinden. Vervolgens kunnen we de gebeurtenissen herhalen en specifieke gebeurtenissen detecteren die onze toepassing wil begrijpen. In de code hieronder reageren we op de CallConnected gebeurtenis.

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

(Optioneel) Een Microsoft Teams-gebruiker toevoegen aan het gesprek

U kunt een Microsoft Teams-gebruiker toevoegen aan de aanroep met behulp van de AddParticipantAsync methode met een MicrosoftTeamsUserIdentifier en de gebruikers-id van Teams. U moet eerst de vereiste stap Autorisatie voor uw Azure Communication Services-resource voltooien om aanroepen naar Microsoft Teams-gebruikers mogelijk te maken. U kunt desgewenst ook een SourceDisplayName bericht doorgeven om de tekst te bepalen die wordt weergegeven in de pop-upmelding voor de Teams-gebruiker.

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

Beginnen met het opnemen van een gesprek

De Call Automation-service maakt het ook mogelijk om opnamen van spraak- en videogesprekken te starten en op te slaan. Hier vindt u meer informatie over de verschillende mogelijkheden in de CALL Recording-API's.

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

Welkomstbericht afspelen en herkennen

Met behulp van de TextSourceservice kunt u de service voorzien van de tekst die u wilt synthetiseren en gebruiken voor uw welkomstbericht. De Azure Communication Services Call Automation-service speelt dit bericht af op de CallConnected gebeurtenis.

Vervolgens geven we de tekst door aan de CallMediaRecognizeChoiceOptions en vervolgens bellen StartRecognizingAsync. Hierdoor kan uw toepassing de optie herkennen die de beller kiest.

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

Keuze-gebeurtenissen verwerken

Azure Communication Services Call Automation activeert de api/callbacks webhook die we hebben ingesteld en informeert ons over de RecognizeCompleted gebeurtenis. De gebeurtenis biedt ons de mogelijkheid om te reageren op invoer die is ontvangen en een actie te activeren. De toepassing speelt vervolgens een bericht af bij de beller op basis van de specifieke invoer die is ontvangen.

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

Opname ophangen en stoppen

Ten slotte, wanneer we een voorwaarde detecteren die zinvol is om de aanroep te beëindigen, kunnen we de HangUpAsync methode gebruiken om de aanroep op te hangen.

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

De code uitvoeren

Als u de toepassing wilt uitvoeren met VS Code, opent u een Terminal-venster en voert u de volgende opdracht uit

dotnet run

Vereisten

Voorbeeldcode

Download of kloon quickstart-voorbeeldcode van GitHub.

Navigeer naar CallAutomation_OutboundCalling de map en open de oplossing in een code-editor.

Uw Azure DevTunnel instellen en hosten

Azure DevTunnels is een Azure-service waarmee u lokale webservices kunt delen die worden gehost op internet. Voer de DevTunnel-opdrachten uit om uw lokale ontwikkelomgeving te verbinden met het openbare internet. DevTunnels maakt vervolgens een tunnel met een permanente eindpunt-URL en biedt anonieme toegang. Azure Communication Services gebruikt dit eindpunt om uw toepassing op de hoogte te stellen van het aanroepen van gebeurtenissen van de Azure Communication Services Call Automation-service.

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

Uw toepassingsconfiguratie bijwerken

Open vervolgens het application.yml bestand in de /resources map om de volgende waarden te configureren:

  • connectionstring: de verbindingsreeks voor uw Azure Communication Services-resource. U vindt uw Azure Communication Services-verbindingsreeks met behulp van de instructies hier.
  • basecallbackuri: Nadat uw DevTunnel-host is geïnitialiseerd, werkt u dit veld bij met die URI.
  • callerphonenumber: werk dit veld bij met het Azure Communication Services-telefoonnummer dat u hebt verkregen. Dit telefoonnummer moet de notatie E164-telefoonnummer gebruiken (bijvoorbeeld +18881234567)
  • targetphonenumber: werk het veld bij met het telefoonnummer dat u wilt bellen door uw toepassing. Dit telefoonnummer moet de notatie E164-telefoonnummer gebruiken (bijvoorbeeld +18881234567)
  • cognitiveServiceEndpoint: veld bijwerken met uw Azure AI-services-eindpunt.
  • targetTeamsUserId: (Optioneel) bijwerken met de gebruikers-id van Microsoft Teams die u aan de oproep wilt toevoegen. Zie Graph API gebruiken om gebruikers-id van Teams op te halen.
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. "ab01bc12-d457-4995-a27b-c405ecfe4870">

Een uitgaand gesprek voeren en media afspelen

Als u de uitgaande aanroep vanuit Azure Communication Services wilt maken, gebruikt dit voorbeeld de targetphonenumber door u gedefinieerde in het application.yml bestand om de aanroep te maken met behulp van de 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);

(Optioneel) Een Microsoft Teams-gebruiker toevoegen aan het gesprek

U kunt een Microsoft Teams-gebruiker toevoegen aan de aanroep met behulp van de addParticipant methode met een MicrosoftTeamsUserIdentifier en de gebruikers-id van Teams. U moet eerst de vereiste stap Autorisatie voor uw Azure Communication Services-resource voltooien om aanroepen naar Microsoft Teams-gebruikers mogelijk te maken. U kunt desgewenst ook een SourceDisplayName bericht doorgeven om de tekst te bepalen die wordt weergegeven in de pop-upmelding voor de Teams-gebruiker.

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

Beginnen met het opnemen van een gesprek

De Call Automation-service maakt het ook mogelijk om opnamen van spraak- en videogesprekken te starten en op te slaan. Hier vindt u meer informatie over de verschillende mogelijkheden in de CALL Recording-API's.

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

Reageren op oproepevenementen

Eerder in onze toepassing hebben we de basecallbackuri aanroepautomatiseringsservice geregistreerd. De URI geeft het eindpunt aan dat de service zal gebruiken om ons op de hoogte te stellen van aanroepende gebeurtenissen die plaatsvinden. Vervolgens kunnen we de gebeurtenissen herhalen en specifieke gebeurtenissen detecteren die onze toepassing wil begrijpen. In de code hieronder reageren we op de CallConnected gebeurtenis.

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

Welkomstbericht afspelen en herkennen

Met behulp van de TextSourceservice kunt u de service voorzien van de tekst die u wilt synthetiseren en gebruiken voor uw welkomstbericht. De Azure Communication Services Call Automation-service speelt dit bericht af op de CallConnected gebeurtenis.

Vervolgens geven we de tekst door aan de CallMediaRecognizeChoiceOptions en vervolgens bellen StartRecognizingAsync. Hierdoor kan uw toepassing de optie herkennen die de beller kiest.

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

Keuze-gebeurtenissen verwerken

Azure Communication Services Call Automation activeert de api/callbacks webhook die we hebben ingesteld en informeert ons over de RecognizeCompleted gebeurtenis. De gebeurtenis biedt ons de mogelijkheid om te reageren op invoer die is ontvangen en een actie te activeren. De toepassing speelt vervolgens een bericht af bij de beller op basis van de specifieke invoer die is ontvangen.

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

Het gesprek ophangen

Ten slotte, wanneer we een voorwaarde detecteren die zinvol is om de aanroep te beëindigen, kunnen we de hangUp methode gebruiken om de aanroep op te hangen.

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

De code uitvoeren

Navigeer naar de map met het bestand pom.xml en gebruik de volgende mvn-opdrachten:

  • Compileer de toepassing: mvn compile
  • Bouw het pakket: mvn package
  • Voer de app uit: mvn exec:java

Vereisten

Voorbeeldcode

Download of kloon quickstart-voorbeeldcode van GitHub.

Navigeer naar CallAutomation_OutboundCalling de map en open de oplossing in een code-editor.

De omgeving instellen

Download de voorbeeldcode en navigeer naar de projectmap en voer de npm opdracht uit waarmee de benodigde afhankelijkheden worden geïnstalleerd en uw ontwikkelomgeving wordt ingesteld.

npm install

Uw Azure DevTunnel instellen en hosten

Azure DevTunnels is een Azure-service waarmee u lokale webservices kunt delen die worden gehost op internet. Gebruik de DevTunnel CLI-opdrachten om uw lokale ontwikkelomgeving te verbinden met het openbare internet. We gebruiken dit eindpunt om uw toepassing op de hoogte te stellen van het aanroepen van gebeurtenissen van de Azure Communication Services Call Automation-service.

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

Uw toepassingsconfiguratie bijwerken

Werk het .env bestand vervolgens bij met de volgende waarden:

  • CONNECTION_STRING: de verbindingsreeks voor uw Azure Communication Services-resource. U vindt uw Azure Communication Services-verbindingsreeks met behulp van de instructies hier.
  • CALLBACK_URI: Nadat uw DevTunnel-host is geïnitialiseerd, werkt u dit veld bij met die URI.
  • TARGET_PHONE_NUMBER: werk het veld bij met het telefoonnummer dat u wilt bellen door uw toepassing. Dit telefoonnummer moet de notatie E164-telefoonnummer gebruiken (bijvoorbeeld +18881234567)
  • ACS_RESOURCE_PHONE_NUMBER: werk dit veld bij met het Azure Communication Services-telefoonnummer dat u hebt verkregen. Dit telefoonnummer moet de notatie E164-telefoonnummer gebruiken (bijvoorbeeld +18881234567)
  • COGNITIVE_SERVICES_ENDPOINT: veld bijwerken met uw Azure AI-services-eindpunt.
  • TARGET_TEAMS_USER_ID: (Optioneel) bijwerken met de gebruikers-id van Microsoft Teams die u aan de oproep wilt toevoegen. Zie Graph API gebruiken om gebruikers-id van Teams op te halen.
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>"

Een uitgaand gesprek voeren en media afspelen

Als u de uitgaande oproep vanuit Azure Communication Services wilt maken, gebruikt u het telefoonnummer dat u hebt opgegeven voor de omgeving. Zorg ervoor dat het telefoonnummer de notatie E164-telefoonnummer heeft (bijvoorbeeld +18881234567)

De code maakt een uitgaande aanroep met behulp van de target_phone_number die u hebt opgegeven en plaats een uitgaande oproep naar dat 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);

(Optioneel) Een Microsoft Teams-gebruiker toevoegen aan het gesprek

U kunt een Microsoft Teams-gebruiker toevoegen aan de aanroep met behulp van de addParticipant methode met de microsoftTeamsUserId eigenschap. U moet eerst de vereiste stap Autorisatie voor uw Azure Communication Services-resource voltooien om aanroepen naar Microsoft Teams-gebruikers mogelijk te maken. U kunt desgewenst ook een sourceDisplayName bericht doorgeven om de tekst te bepalen die wordt weergegeven in de pop-upmelding voor de Teams-gebruiker.

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

Beginnen met het opnemen van een gesprek

De Call Automation-service maakt het ook mogelijk om opnamen van spraak- en videogesprekken te starten en op te slaan. Hier vindt u meer informatie over de verschillende mogelijkheden in de CALL Recording-API's.

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

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

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

recordingId = response.recordingId;

Reageren op oproepevenementen

Eerder in onze toepassing hebben we de CALLBACK_URI aanroepautomatiseringsservice geregistreerd. De URI geeft het eindpunt aan dat de service gebruikt om ons op de hoogte te stellen van aanroepende gebeurtenissen die plaatsvinden. Vervolgens kunnen we de gebeurtenissen herhalen en specifieke gebeurtenissen detecteren die onze toepassing wil begrijpen. We reageren op de CallConnected gebeurtenis om een melding te ontvangen en downstreambewerkingen te starten. Met behulp van de TextSourceservice kunt u de service voorzien van de tekst die u wilt synthetiseren en gebruiken voor uw welkomstbericht. De Azure Communication Services Call Automation-service speelt dit bericht af op de CallConnected gebeurtenis.

Vervolgens geven we de tekst door aan de CallMediaRecognizeChoiceOptions en vervolgens bellen StartRecognizingAsync. Hierdoor kan uw toepassing de optie herkennen die de beller kiest.

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

Keuze-gebeurtenissen verwerken

Azure Communication Services Call Automation activeert de api/callbacks webhook die we hebben ingesteld en informeert ons over de RecognizeCompleted gebeurtenis. De gebeurtenis biedt ons de mogelijkheid om te reageren op invoer die is ontvangen en een actie te activeren. De toepassing speelt vervolgens een bericht af bij de beller op basis van de specifieke invoer die is ontvangen.

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

Het gesprek ophangen

Ten slotte, wanneer we een voorwaarde detecteren die zinvol is om de aanroep te beëindigen, kunnen we de hangUp() methode gebruiken om de aanroep op te hangen.

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

De code uitvoeren

Als u de toepassing wilt uitvoeren, opent u een Terminal-venster en voert u de volgende opdracht uit:

  npm run dev

Vereisten

Voorbeeldcode

Download of kloon quickstart-voorbeeldcode van GitHub.

Navigeer naar CallAutomation_OutboundCalling de map en open de oplossing in een code-editor.

De Python-omgeving instellen

Maak en activeer python-omgeving en installeer de vereiste pakketten met behulp van de volgende opdracht. Meer informatie over het beheren van pakketten vindt u hier

pip install -r requirements.txt

Uw Azure DevTunnel instellen en hosten

Azure DevTunnels is een Azure-service waarmee u lokale webservices kunt delen die worden gehost op internet. Gebruik de opdrachten om uw lokale ontwikkelomgeving te verbinden met het openbare internet. DevTunnels maakt een tunnel met een permanente eindpunt-URL en biedt anonieme toegang. We gebruiken dit eindpunt om uw toepassing op de hoogte te stellen van het aanroepen van gebeurtenissen van de Azure Communication Services Call Automation-service.

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

Uw toepassingsconfiguratie bijwerken

Werk het main.py bestand vervolgens bij met de volgende waarden:

  • ACS_CONNECTION_STRING: de verbindingsreeks voor uw Azure Communication Services-resource. U vindt uw Azure Communication Services-verbindingsreeks met behulp van de instructies hier.
  • CALLBACK_URI_HOST: Nadat uw DevTunnel-host is geïnitialiseerd, werkt u dit veld bij met die URI.
  • TARGET_PHONE_NUMBER: werk het veld bij met het telefoonnummer dat u wilt bellen door uw toepassing. Dit telefoonnummer moet de notatie E164-telefoonnummer gebruiken (bijvoorbeeld +18881234567)
  • ACS_PHONE_NUMBER: werk dit veld bij met het Azure Communication Services-telefoonnummer dat u hebt verkregen. Dit telefoonnummer moet de notatie E164-telefoonnummer gebruiken (bijvoorbeeld +18881234567)
  • COGNITIVE_SERVICES_ENDPOINT: veld bijwerken met uw Azure AI-services-eindpunt.
  • TARGET_TEAMS_USER_ID: (Optioneel) bijwerken met de gebruikers-id van Microsoft Teams die u aan de oproep wilt toevoegen. Zie Graph API gebruiken om gebruikers-id van Teams op te halen.
# 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. "ab01bc12-d457-4995-a27b-c405ecfe4870"
TARGET_TEAMS_USER_ID = "<TARGET_TEAMS_USER_ID>"

Een uitgaande oproep maken

Als u de uitgaande oproep vanuit Azure Communication Services wilt maken, geeft u eerst het telefoonnummer op dat u wilt ontvangen. Om het eenvoudig te maken, kunt u het target_phone_number bijwerken met een telefoonnummer in de E164-telefoonnummernotatie (bijvoorbeeld +18881234567)

Maak een uitgaande oproep met behulp van de target_phone_number die u hebt opgegeven:

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

(Optioneel) Een Microsoft Teams-gebruiker toevoegen aan het gesprek

U kunt een Microsoft Teams-gebruiker toevoegen aan de aanroep met behulp van de add_participant methode met een MicrosoftTeamsUserIdentifier en de gebruikers-id van Teams. U moet eerst de vereiste stap Autorisatie voor uw Azure Communication Services-resource voltooien om aanroepen naar Microsoft Teams-gebruikers mogelijk te maken. U kunt desgewenst ook een source_display_name bericht doorgeven om de tekst te bepalen die wordt weergegeven in de pop-upmelding voor de Teams-gebruiker.

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

Beginnen met het opnemen van een gesprek

De Call Automation-service maakt het ook mogelijk om opnamen van spraak- en videogesprekken te starten en op te slaan. Hier vindt u meer informatie over de verschillende mogelijkheden in de CALL Recording-API's.

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

Reageren op oproepevenementen

Eerder in onze toepassing hebben we de CALLBACK_URI_HOST aanroepautomatiseringsservice geregistreerd. De URI geeft het eindpunt aan dat de service gebruikt om ons op de hoogte te stellen van aanroepende gebeurtenissen die plaatsvinden. Vervolgens kunnen we de gebeurtenissen herhalen en specifieke gebeurtenissen detecteren die onze toepassing wil begrijpen. In de code hieronder reageren we op de CallConnected gebeurtenis.

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

Welkomstbericht afspelen en herkennen

Met behulp van de TextSourceservice kunt u de service voorzien van de tekst die u wilt synthetiseren en gebruiken voor uw welkomstbericht. De Azure Communication Services Call Automation-service speelt dit bericht af op de CallConnected gebeurtenis.

Vervolgens geven we de tekst door aan de CallMediaRecognizeChoiceOptions en vervolgens bellen StartRecognizingAsync. Hierdoor kan uw toepassing de optie herkennen die de beller kiest.


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

Keuze-gebeurtenissen verwerken

Azure Communication Services Call Automation activeert de api/callbacks webhook die we hebben ingesteld en informeert ons over de RecognizeCompleted gebeurtenis. De gebeurtenis biedt ons de mogelijkheid om te reageren op invoer die is ontvangen en een actie te activeren. De toepassing speelt vervolgens een bericht af bij de beller op basis van de specifieke invoer die is ontvangen.

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)

Het gesprek ophangen

Ten slotte, wanneer we een voorwaarde detecteren die zinvol is om de aanroep te beëindigen, kunnen we de hang_up() methode gebruiken om de aanroep op te hangen. Ten slotte kunnen we de oproepopnamebewerking ook veilig stoppen.

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

De code uitvoeren

Als u de toepassing wilt uitvoeren met VS Code, opent u een Terminal-venster en voert u de volgende opdracht uit

python main.py