Megosztás a következőn keresztül:

Rövid útmutató: Kimenő hívás kezdeményezése a Call Automation használatával

  • Cikk

Az Azure Communication Services Call Automation API-kkal interaktív hívási élményeket hozhat létre. Ebben a rövid útmutatóban bemutatjuk a kimenő hívások indításának és a hívás különböző eseményeinek felismerésének módját.

Előfeltételek

Mintakód

Rövid útmutató mintakód letöltése vagy klónozása a GitHubról.

Lépjen a mappára CallAutomation_OutboundCalling , és nyissa meg a megoldást egy kódszerkesztőben.

Az Azure DevTunnel beállítása és üzemeltetéséhez

Az Azure DevTunnels egy Azure-szolgáltatás, amely lehetővé teszi az interneten üzemeltetett helyi webszolgáltatások megosztását. Futtassa a parancsokat a helyi fejlesztési környezet nyilvános internethez való csatlakoztatásához. A DevTunnels létrehoz egy állandó végpont URL-címét, amely lehetővé teszi a névtelen hozzáférést. Ezzel a végponttal értesítjük az alkalmazást az Azure Communication Services Hívásautomatizálási szolgáltatásából érkező hívási eseményekről.

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

Az alkalmazáskonfiguráció frissítése

Frissítse a fájlt a Program.cs következő értékekkel:

  • acsConnectionString: Az Azure Communication Services-erőforrás kapcsolati sztring. Az Azure Communication Services-kapcsolati sztring az itt található utasítások segítségével találhatja meg.
  • callbackUriHost: Miután inicializálta a DevTunnel-gazdagépet, frissítse ezt a mezőt ezzel az URI-val.
  • acsPhonenumber: frissítse ezt a mezőt a beszerzett Azure Communication Services-telefonszámmal. Ennek a telefonszámnak az E164-es telefonszámformátumot kell használnia (pl. +18881234567)
  • targetPhonenumber: frissítse a mezőt azzal a telefonszámmal, amellyel az alkalmazást hívni szeretné. Ennek a telefonszámnak az E164-es telefonszámformátumot kell használnia (pl. +18881234567)
  • cognitiveServiceEndpoint: a mező frissítése az Azure AI-szolgáltatások végpontjával.
  • targetTeamsUserId: (Nem kötelező) frissítési mező a híváshoz hozzáadni kívánt Microsoft Teams-felhasználóazonosítóval. Lásd: A Graph API használata a Teams felhasználói azonosítóinak lekéréséhez.
// 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>";

Kimenő hívás kezdeményezése

Az Azure Communication Servicesből kimenő hívás indításához ez a minta az targetPhonenumber alkalmazásban korábban definiált módon hozza létre a hívást az CreateCallAsync API használatával. Ez a kód kimenő hívást indít a cél telefonszám használatával.

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

Hívásautomatizálási események kezelése

Az alkalmazás korábbi részében regisztráltuk a callbackUriHost Hívásautomatizálási szolgáltatásban. A gazdagép azt a végpontot jelzi, amelyhez a szolgáltatásnak értesítenie kell minket a bekövetkező események hívásáról. Ezután iterálhatunk az eseményeken, és észlelhetjük az alkalmazás által megérteni kívánt konkrét eseményeket. Az alábbi kódban válaszolunk az eseményre CallConnected .

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

(Nem kötelező) Microsoft Teams-felhasználó hozzáadása a híváshoz

A híváshoz Microsoft Teams-felhasználót adhat hozzá egy AddParticipantAsync metódussal MicrosoftTeamsUserIdentifier és a Teams-felhasználó azonosítójával. Először el kell végeznie az Azure Communication Services-erőforrás engedélyezési előfeltételeinek lépéseit a Microsoft Teams-felhasználók meghívásának engedélyezéséhez. A Teams-felhasználó bejelentési értesítésében megjelenő szöveg szabályozásához is megadhat egy SourceDisplayName elemet.

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

Hívás felvételének megkezdése

A Hívásautomatizálás szolgáltatás lehetővé teszi a hang- és videohívások felvételének rögzítését és tárolását is. A hívásrögzítési API-k különböző képességeiről itt olvashat bővebben.

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

Üdvözlő üzenet lejátszása és felismerése

TextSourceA használatával a szolgáltatásnak megadhatja a szintetizálni kívánt szöveget, és használhatja az üdvözlő üzenethez. Az Azure Communication Services Call Automation szolgáltatás ezt az üzenetet az eseményen CallConnected játssza le.

Ezután átadjuk a szöveget a CallMediaRecognizeChoiceOptions következőnek, majd meghívjuk StartRecognizingAsync. Ez lehetővé teszi, hogy az alkalmazás felismerje a hívó által választott lehetőséget.

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

Választási események kezelése

Az Azure Communication Services Hívásautomatizálása aktiválja a api/callbacks webhookot, amely a beállítással rendelkezik, és értesítést küld az RecognizeCompleted eseményről. Az esemény lehetővé teszi számunkra, hogy válaszoljunk a fogadott bemenetekre, és aktiváljunk egy műveletet. Az alkalmazás ezután egy üzenetet játszik le a hívónak a kapott konkrét bemenet alapján.

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

Lefagyás és rögzítés leállítása

Végül, ha egy olyan feltételt észlelünk, amely logikus a hívás leállításához, a HangUpAsync metódus használatával leállíthatjuk a hívást.

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

A kód futtatása

Az alkalmazás VS Code-tal való futtatásához nyisson meg egy terminálablakot, és futtassa a következő parancsot

dotnet run

Előfeltételek

Mintakód

Rövid útmutató mintakód letöltése vagy klónozása a GitHubról.

Lépjen a mappára CallAutomation_OutboundCalling , és nyissa meg a megoldást egy kódszerkesztőben.

Az Azure DevTunnel beállítása és üzemeltetéséhez

Az Azure DevTunnels egy Azure-szolgáltatás, amely lehetővé teszi az interneten üzemeltetett helyi webszolgáltatások megosztását. Futtassa a DevTunnel parancsokat a helyi fejlesztési környezet nyilvános internethez való csatlakoztatásához. A DevTunnels ezután létrehoz egy alagutat egy állandó végpont URL-címével, amely lehetővé teszi a névtelen hozzáférést. Az Azure Communication Services ezzel a végponttal értesíti az alkalmazást az Azure Communication Services Hívásautomatizálási szolgáltatásából érkező hívási eseményekről.

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

Az alkalmazáskonfiguráció frissítése

Ezután nyissa meg a application.yml fájlt a /resources mappában a következő értékek konfigurálásához:

  • connectionstring: Az Azure Communication Services-erőforrás kapcsolati sztring. Az Azure Communication Services-kapcsolati sztring az itt található utasítások segítségével találhatja meg.
  • basecallbackuri: Miután inicializálta a DevTunnel-gazdagépet, frissítse ezt a mezőt ezzel az URI-val.
  • callerphonenumber: frissítse ezt a mezőt a beszerzett Azure Communication Services-telefonszámmal. Ennek a telefonszámnak az E164-es telefonszámformátumot kell használnia (pl. +18881234567)
  • targetphonenumber: frissítse a mezőt azzal a telefonszámmal, amellyel az alkalmazást hívni szeretné. Ennek a telefonszámnak az E164-es telefonszámformátumot kell használnia (pl. +18881234567)
  • cognitiveServiceEndpoint: a mező frissítése az Azure AI-szolgáltatások végpontjával.
  • targetTeamsUserId: (Nem kötelező) frissítési mező a híváshoz hozzáadni kívánt Microsoft Teams-felhasználóazonosítóval. Lásd: A Graph API használata a Teams felhasználói azonosítóinak lekéréséhez.
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">

Kimenő hívás indítása és média lejátszása

Az Azure Communication Servicesből érkező kimenő hívás indításához ez a minta a targetphonenumber fájlban application.yml meghatározott módon hozza létre a hívást az createCallWithResponse API használatával.

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

(Nem kötelező) Microsoft Teams-felhasználó hozzáadása a híváshoz

A híváshoz Microsoft Teams-felhasználót adhat hozzá egy addParticipant metódussal MicrosoftTeamsUserIdentifier és a Teams-felhasználó azonosítójával. Először el kell végeznie az Azure Communication Services-erőforrás engedélyezési előfeltételeinek lépéseit a Microsoft Teams-felhasználók meghívásának engedélyezéséhez. A Teams-felhasználó bejelentési értesítésében megjelenő szöveg szabályozásához is megadhat egy SourceDisplayName elemet.

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

Hívás felvételének megkezdése

A Hívásautomatizálás szolgáltatás lehetővé teszi a hang- és videohívások felvételének rögzítését és tárolását is. A hívásrögzítési API-k különböző képességeiről itt olvashat bővebben.

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

Válaszadás hívási eseményekre

Az alkalmazás korábbi részében regisztráltuk a basecallbackuri Hívásautomatizálási szolgáltatásban. Az URI azt jelzi, hogy a szolgáltatás a szolgáltatás által használt végpontot fogja használni, hogy értesítsen minket a bekövetkező események hívásáról. Ezután iterálhatunk az eseményeken, és észlelhetjük az alkalmazás által megérteni kívánt konkrét eseményeket. Az alábbi kódban válaszolunk az eseményre CallConnected .

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

Üdvözlő üzenet lejátszása és felismerése

TextSourceA használatával a szolgáltatásnak megadhatja a szintetizálni kívánt szöveget, és használhatja az üdvözlő üzenethez. Az Azure Communication Services Call Automation szolgáltatás ezt az üzenetet az eseményen CallConnected játssza le.

Ezután átadjuk a szöveget a CallMediaRecognizeChoiceOptions következőnek, majd meghívjuk StartRecognizingAsync. Ez lehetővé teszi, hogy az alkalmazás felismerje a hívó által választott lehetőséget.

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

Választási események kezelése

Az Azure Communication Services Hívásautomatizálása aktiválja a api/callbacks webhookot, amely a beállítással rendelkezik, és értesítést küld az RecognizeCompleted eseményről. Az esemény lehetővé teszi számunkra, hogy válaszoljunk a fogadott bemenetekre, és aktiváljunk egy műveletet. Az alkalmazás ezután egy üzenetet játszik le a hívónak a kapott konkrét bemenet alapján.

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

A hívás lefagyása

Végül, ha egy olyan feltételt észlelünk, amely logikus a hívás leállításához, a hangUp metódus használatával leállíthatjuk a hívást.

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

A kód futtatása

Keresse meg a pom.xml fájlt tartalmazó könyvtárat, és használja az alábbi mvn-parancsokat:

  • Az alkalmazás fordítása: mvn compile
  • A csomag összeállítása: mvn package
  • Hajtsa végre az alkalmazást: mvn exec:java

Előfeltételek

Mintakód

Rövid útmutató mintakód letöltése vagy klónozása a GitHubról.

Lépjen a mappára CallAutomation_OutboundCalling , és nyissa meg a megoldást egy kódszerkesztőben.

A környezet beállítása

Töltse le a mintakódot, keresse meg a projektkönyvtárat, és futtassa a npm szükséges függőségeket telepítő parancsot, és állítsa be a fejlesztői környezetet.

npm install

Az Azure DevTunnel beállítása és üzemeltetéséhez

Az Azure DevTunnels egy Azure-szolgáltatás, amely lehetővé teszi az interneten üzemeltetett helyi webszolgáltatások megosztását. A DevTunnel CLI-parancsokkal csatlakoztassa a helyi fejlesztési környezetet a nyilvános internethez. Ezzel a végponttal értesítjük az alkalmazást az Azure Communication Services Hívásautomatizálási szolgáltatásából érkező hívási eseményekről.

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

Az alkalmazáskonfiguráció frissítése

Ezután frissítse a fájlt a .env következő értékekkel:

  • CONNECTION_STRING: Az Azure Communication Services-erőforrás kapcsolati sztring. Az Azure Communication Services-kapcsolati sztring az itt található utasítások segítségével találhatja meg.
  • CALLBACK_URI: Miután inicializálta a DevTunnel-gazdagépet, frissítse ezt a mezőt ezzel az URI-val.
  • TARGET_PHONE_NUMBER: frissítse a mezőt azzal a telefonszámmal, amellyel az alkalmazást hívni szeretné. Ennek a telefonszámnak az E164-es telefonszámformátumot kell használnia (pl. +18881234567)
  • ACS_RESOURCE_PHONE_NUMBER: frissítse ezt a mezőt a beszerzett Azure Communication Services-telefonszámmal. Ennek a telefonszámnak az E164-es telefonszámformátumot kell használnia (pl. +18881234567)
  • COGNITIVE_SERVICES_ENDPOINT: a mező frissítése az Azure AI-szolgáltatások végpontjával.
  • TARGET_TEAMS_USER_ID: (Nem kötelező) frissítési mező a híváshoz hozzáadni kívánt Microsoft Teams-felhasználóazonosítóval. Lásd: A Graph API használata a Teams felhasználói azonosítóinak lekéréséhez.
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>"

Kimenő hívás indítása és média lejátszása

Az Azure Communication Servicesből kimenő hívás indításához a környezetnek megadott telefonszámot kell használnia. Győződjön meg arról, hogy a telefonszám E164-es telefonszámformátumban van (pl. +18881234567)

A kód kimenő hívást kezdeményez a megadott target_phone_number, és kimenő hívást indít erre a számra:

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

(Nem kötelező) Microsoft Teams-felhasználó hozzáadása a híváshoz

A tulajdonsággal rendelkező metódussal hozzáadhat egy Microsoft Teams-felhasználót a addParticipantmicrosoftTeamsUserId híváshoz. Először el kell végeznie az Azure Communication Services-erőforrás engedélyezési előfeltételeinek lépéseit a Microsoft Teams-felhasználók meghívásának engedélyezéséhez. A Teams-felhasználó bejelentési értesítésében megjelenő szöveg szabályozásához is megadhat egy sourceDisplayName elemet.

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

Hívás felvételének megkezdése

A Hívásautomatizálás szolgáltatás lehetővé teszi a hang- és videohívások felvételének rögzítését és tárolását is. A hívásrögzítési API-k különböző képességeiről itt olvashat bővebben.

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

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

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

recordingId = response.recordingId;

Válaszadás hívási eseményekre

Az alkalmazás korábbi részében regisztráltuk a CALLBACK_URI Hívásautomatizálási szolgáltatásban. Az URI azt a végpontot jelzi, amellyel a szolgáltatás értesítést küld a bekövetkező események hívásáról. Ezután iterálhatunk az eseményeken, és észlelhetjük az alkalmazás által megérteni kívánt konkrét eseményeket. Válaszolunk az eseményre, CallConnected hogy értesítést kapjunk, és elindítsuk az alsóbb rétegbeli műveleteket. TextSourceA használatával a szolgáltatásnak megadhatja a szintetizálni kívánt szöveget, és használhatja az üdvözlő üzenethez. Az Azure Communication Services Call Automation szolgáltatás ezt az üzenetet az eseményen CallConnected játssza le.

Ezután átadjuk a szöveget a CallMediaRecognizeChoiceOptions következőnek, majd meghívjuk StartRecognizingAsync. Ez lehetővé teszi, hogy az alkalmazás felismerje a hívó által választott lehetőséget.

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

Választási események kezelése

Az Azure Communication Services Hívásautomatizálása aktiválja a api/callbacks webhookot, amely a beállítással rendelkezik, és értesítést küld az RecognizeCompleted eseményről. Az esemény lehetővé teszi számunkra, hogy válaszoljunk a fogadott bemenetekre, és aktiváljunk egy műveletet. Az alkalmazás ezután egy üzenetet játszik le a hívónak a kapott konkrét bemenet alapján.

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

A hívás lefagyása

Végül, ha egy olyan feltételt észlelünk, amely logikus a hívás leállításához, a hangUp() metódus használatával leállíthatjuk a hívást.

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

A kód futtatása

Az alkalmazás futtatásához nyisson meg egy terminálablakot, és futtassa a következő parancsot:

  npm run dev

Előfeltételek

Mintakód

Rövid útmutató mintakód letöltése vagy klónozása a GitHubról.

Lépjen a mappára CallAutomation_OutboundCalling , és nyissa meg a megoldást egy kódszerkesztőben.

A Python-környezet beállítása

Hozzon létre és aktiválja a Python-környezetet, és telepítse a szükséges csomagokat a következő paranccsal. A csomagok kezeléséről itt tudhat meg többet

pip install -r requirements.txt

Az Azure DevTunnel beállítása és üzemeltetéséhez

Az Azure DevTunnels egy Azure-szolgáltatás, amely lehetővé teszi az interneten üzemeltetett helyi webszolgáltatások megosztását. A parancsokkal csatlakoztathatja a helyi fejlesztési környezetet a nyilvános internethez. A DevTunnels létrehoz egy állandó végpont URL-címmel rendelkező alagutat, amely lehetővé teszi a névtelen hozzáférést. Ezzel a végponttal értesítjük az alkalmazást az Azure Communication Services Hívásautomatizálási szolgáltatásából érkező hívási eseményekről.

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

Az alkalmazáskonfiguráció frissítése

Ezután frissítse a main.py fájlt a következő értékekkel:

  • ACS_CONNECTION_STRING: Az Azure Communication Services-erőforrás kapcsolati sztring. Az Azure Communication Services-kapcsolati sztring az itt található utasítások segítségével találhatja meg.
  • CALLBACK_URI_HOST: Miután inicializálta a DevTunnel-gazdagépet, frissítse ezt a mezőt ezzel az URI-val.
  • TARGET_PHONE_NUMBER: frissítse a mezőt azzal a telefonszámmal, amellyel az alkalmazást hívni szeretné. Ennek a telefonszámnak az E164-es telefonszámformátumot kell használnia (pl. +18881234567)
  • ACS_PHONE_NUMBER: frissítse ezt a mezőt a beszerzett Azure Communication Services-telefonszámmal. Ennek a telefonszámnak az E164-es telefonszámformátumot kell használnia (pl. +18881234567)
  • COGNITIVE_SERVICES_ENDPOINT: a mező frissítése az Azure AI-szolgáltatások végpontjával.
  • TARGET_TEAMS_USER_ID: (Nem kötelező) frissítési mező a híváshoz hozzáadni kívánt Microsoft Teams-felhasználóazonosítóval. Lásd: A Graph API használata a Teams felhasználói azonosítóinak lekéréséhez.
# 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>"

Kimenő hívás kezdeményezése

Az Azure Communication Servicesből érkező hívás indításához először adja meg a hívást fogadni kívánt telefonszámot. Az egyszerűség érdekében frissítheti a target_phone_number telefonszámot E164-es telefonszámformátumban (pl. +18881234567)

Kimenő hívás indítása a megadott target_phone_number használatával:

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

(Nem kötelező) Microsoft Teams-felhasználó hozzáadása a híváshoz

A híváshoz Microsoft Teams-felhasználót adhat hozzá egy add_participant metódussal MicrosoftTeamsUserIdentifier és a Teams-felhasználó azonosítójával. Először el kell végeznie az Azure Communication Services-erőforrás engedélyezési előfeltételeinek lépéseit a Microsoft Teams-felhasználók meghívásának engedélyezéséhez. A Teams-felhasználó bejelentési értesítésében megjelenő szöveg szabályozásához is megadhat egy source_display_name elemet.

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

Hívás felvételének megkezdése

A Hívásautomatizálás szolgáltatás lehetővé teszi a hang- és videohívások felvételének rögzítését és tárolását is. A hívásrögzítési API-k különböző képességeiről itt olvashat bővebben.

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

Válaszadás hívási eseményekre

Az alkalmazás korábbi részében regisztráltuk a CALLBACK_URI_HOST Hívásautomatizálási szolgáltatásban. Az URI azt a végpontot jelzi, amellyel a szolgáltatás értesítést küld a bekövetkező események hívásáról. Ezután iterálhatunk az eseményeken, és észlelhetjük az alkalmazás által megérteni kívánt konkrét eseményeket. Az alábbi kódban válaszolunk az eseményre CallConnected .

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

Üdvözlő üzenet lejátszása és felismerése

TextSourceA használatával a szolgáltatásnak megadhatja a szintetizálni kívánt szöveget, és használhatja az üdvözlő üzenethez. Az Azure Communication Services Call Automation szolgáltatás ezt az üzenetet az eseményen CallConnected játssza le.

Ezután átadjuk a szöveget a CallMediaRecognizeChoiceOptions következőnek, majd meghívjuk StartRecognizingAsync. Ez lehetővé teszi, hogy az alkalmazás felismerje a hívó által választott lehetőséget.


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

Választási események kezelése

Az Azure Communication Services Hívásautomatizálása aktiválja a api/callbacks webhookot, amely a beállítással rendelkezik, és értesítést küld az RecognizeCompleted eseményről. Az esemény lehetővé teszi számunkra, hogy válaszoljunk a fogadott bemenetekre, és aktiváljunk egy műveletet. Az alkalmazás ezután egy üzenetet játszik le a hívónak a kapott konkrét bemenet alapján.

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)

A hívás lefagyása

Végül, ha egy olyan feltételt észlelünk, amely logikus a hívás leállításához, a hang_up() metódus használatával leállíthatjuk a hívást. Végül biztonságosan leállíthatjuk a hívásrögzítési műveletet is.

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

A kód futtatása

Az alkalmazás VS Code-tal való futtatásához nyisson meg egy terminálablakot, és futtassa a következő parancsot

python main.py