Rychlý start: Uskutečnění odchozího volání pomocí automatizace volání

Článek
04/07/2024

Rozhraní API služby Azure Communication Services pro automatizaci volání představují účinný způsob, jak vytvářet interaktivní prostředí volání. V tomto rychlém startu probereme způsob, jak provést odchozí hovor a rozpoznat různé události v hovoru.

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Nasazený prostředek komunikační služby. Vytvořte prostředek komunikační služby.
Telefonní číslo v prostředku služby Azure Communication Services, které může provádět odchozí hovory. Pokud máte bezplatné předplatné, můžete získat zkušební telefonní číslo.
Vytvoření a hostování azure Dev Tunnelu Tady jsou pokyny.
Vytvořte a připojte služby Azure AI s více službami k prostředku Azure Communication Services.
Vytvořte vlastní subdoménu pro prostředek služeb Azure AI.
(Volitelné) Uživatel Microsoft Teams s povolenou telefonní licencí voice . K přidání uživatelů Teams do hovoru se vyžaduje telefonní licence Teams. Další informace o licencích Teams najdete tady. Tady se dozvíte, jak povolit telefonní systémvoice.

Ukázkový kód

Stáhněte nebo naklonujte ukázkový kód pro rychlý start z GitHubu.

Přejděte do CallAutomation_OutboundCalling složky a otevřete řešení v editoru kódu.

Nastavení a hostování Azure DevTunnelu

Azure DevTunnels je služba Azure, která umožňuje sdílet místní webové služby hostované na internetu. Spuštěním příkazů připojte místní vývojové prostředí k veřejnému internetu. DevTunnels vytvoří trvalou adresu URL koncového bodu a umožňuje anonymní přístup. Tento koncový bod používáme k upozornění vaší aplikace na volání událostí ze služby Azure Communication Services Call Automation.

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

Aktualizace konfigurace aplikace

Dále aktualizujte Program.cs soubor následujícími hodnotami:

acsConnectionString: Připojovací řetězec pro váš prostředek Azure Communication Services. Služby Azure Communication Services najdete připojovací řetězec podle pokynů.
callbackUriHost: Po inicializaci hostitele DevTunnel aktualizujte toto pole tímto identifikátorem URI.
acsPhonenumber: Aktualizujte toto pole telefonním číslem služeb Azure Communication Services, které jste získali. Toto telefonní číslo by mělo používat formát telefonního čísla E164 (např. +18881234567).
targetPhonenumber: Aktualizujte pole s telefonním číslem, které chcete, aby vaše aplikace volala. Toto telefonní číslo by mělo používat formát telefonního čísla E164 (např. +18881234567).
cognitiveServiceEndpoint: Aktualizujte pole pomocí koncového bodu služeb Azure AI.
targetTeamsUserId: (Volitelné) aktualizační pole s ID uživatele Microsoft Teams, které chcete přidat do hovoru. Viz Použití rozhraní Graph API k získání ID uživatele Teams.

// 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>";

Uskutečnění odchozího hovoru

Pokud chcete provést odchozí volání ze služby Azure Communication Services, použije targetPhonenumber tato ukázka volání pomocí rozhraní API, kterou jste definovali dříve v aplikaci CreateCallAsync . Tento kód provede odchozí hovor pomocí cílového telefonního čísla.

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

Zpracování událostí automatizace volání

Dříve v naší aplikaci jsme zaregistrovali callbackUriHost službu Automatizace volání. Hostitel označuje koncový bod, který služba vyžaduje, aby nás informoval o volání událostí, ke kterým dochází. Pak můžeme iterovat událostmi a zjistit konkrétní události, kterým chce naše aplikace porozumět. V kódu níže odpovíme na CallConnected událost.

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

(Volitelné) Přidání uživatele Microsoft Teams do hovoru

Uživatele Microsoft Teams můžete do hovoru přidat pomocí AddParticipantAsync metody s MicrosoftTeamsUserIdentifier ID uživatele Teams. Nejprve je potřeba dokončit autorizaci požadovaného kroku pro prostředek služby Azure Communication Services, aby bylo možné volat uživatelům Microsoft Teams. Volitelně můžete také předat SourceDisplayName text zobrazený v informačním oznámení pro uživatele Teams.

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

Zahájení nahrávání hovoru

Služba Automatizace volání také umožňuje spustit nahrávání a ukládání nahrávek hlasových hovorů a videohovorů. Další informace o různých možnostech najdete v rozhraních API pro záznam hovorů.

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

Přehrání uvítací zprávy a rozpoznání

Pomocí této služby TextSourcemůžete poskytnout text, který chcete syntetizovat a použít pro uvítací zprávu. Služba Automatizace volání služby Azure Communication Services přehraje tuto zprávu při CallConnected události.

Dále předáme text do CallMediaRecognizeChoiceOptions a potom zavoláme StartRecognizingAsync. To vaší aplikaci umožní rozpoznat možnost, která volající zvolí.

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

Zpracování událostí voleb

Automatizace volání služby Azure Communication Services aktivuje api/callbacks webhook, který jsme nastavili, a upozorní nás na RecognizeCompleted událost. Událost nám dává možnost reagovat na přijaté vstupy a aktivovat akci. Aplikace pak volajícímu přehraje zprávu na základě přijatého konkrétního vstupu.

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

Zavěsit a zastavit nahrávání

Nakonec, když zjistíme podmínku, která nám dává smysl ukončit volání, můžeme použít metodu HangUpAsync zavěsit hovor.

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

Pokud chcete spustit aplikaci pomocí nástroje VS Code, otevřete okno terminálu a spusťte následující příkaz.

dotnet run

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Nasazený prostředek komunikační služby. Vytvořte prostředek komunikační služby.
Telefonní číslo v prostředku služby Azure Communication Services, které může provádět odchozí hovory. Pokud máte bezplatné předplatné, můžete získat zkušební telefonní číslo.
Vytvoření a hostování azure Dev Tunnelu Tady jsou pokyny.
Vytvořte a připojte služby Azure AI s více službami k prostředku Azure Communication Services.
Vytvořte vlastní subdoménu pro prostředek služeb Azure AI.
Java Development Kit (JDK) verze 11 nebo novější.
Apache Maven
(Volitelné) Uživatel Microsoft Teams s povolenou telefonní licencí voice . K přidání uživatelů Teams do hovoru se vyžaduje telefonní licence Teams. Další informace o licencích Teams najdete tady. Další informace o povolení voice v telefonním systému najdete v tématu Nastavení telefonního systému.

Ukázkový kód

Stáhněte nebo naklonujte ukázkový kód pro rychlý start z GitHubu.

Přejděte do CallAutomation_OutboundCalling složky a otevřete řešení v editoru kódu.

Nastavení a hostování Azure DevTunnelu

Azure DevTunnels je služba Azure, která umožňuje sdílet místní webové služby hostované na internetu. Spuštěním příkazů DevTunnel připojte místní vývojové prostředí k veřejnému internetu. DevTunnels pak vytvoří tunel s trvalou adresou URL koncového bodu a umožní anonymní přístup. Služba Azure Communication Services používá tento koncový bod k upozornění vaší aplikace na volání událostí ze služby Automatizace volání služby Azure Communication Services.

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

Aktualizace konfigurace aplikace

Potom otevřete application.yml soubor ve /resources složce a nakonfigurujte následující hodnoty:

connectionstring: Připojovací řetězec pro váš prostředek Azure Communication Services. Služby Azure Communication Services najdete připojovací řetězec podle pokynů.
basecallbackuri: Po inicializaci hostitele DevTunnel aktualizujte toto pole tímto identifikátorem URI.
callerphonenumber: Aktualizujte toto pole telefonním číslem služeb Azure Communication Services, které jste získali. Toto telefonní číslo by mělo používat formát telefonního čísla E164 (např. +18881234567).
targetphonenumber: Aktualizujte pole s telefonním číslem, které chcete, aby vaše aplikace volala. Toto telefonní číslo by mělo používat formát telefonního čísla E164 (např. +18881234567).
cognitiveServiceEndpoint: Aktualizujte pole pomocí koncového bodu služeb Azure AI.
targetTeamsUserId: (Volitelné) aktualizační pole s ID uživatele Microsoft Teams, které chcete přidat do hovoru. Viz Použití rozhraní Graph API k získání ID uživatele Teams.

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">

Uskutečnění odchozího hovoru a přehrávání médií

Pokud chcete provést odchozí volání ze služby Azure Communication Services, použije targetphonenumber tato ukázka k vytvoření volání pomocí createCallWithResponse rozhraní API vámi definovanou v application.yml souboru.

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

(Volitelné) Přidání uživatele Microsoft Teams do hovoru

Uživatele Microsoft Teams můžete do hovoru přidat pomocí addParticipant metody s MicrosoftTeamsUserIdentifier ID uživatele Teams. Nejprve je potřeba dokončit autorizaci požadovaného kroku pro prostředek služby Azure Communication Services, aby bylo možné volat uživatelům Microsoft Teams. Volitelně můžete také předat SourceDisplayName text zobrazený v informačním oznámení pro uživatele Teams.

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

Zahájení nahrávání hovoru

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

Reakce na události volání

Dříve v naší aplikaci jsme zaregistrovali basecallbackuri službu Automatizace volání. Identifikátor URI označuje koncový bod, který služba použije k upozornění na volání událostí, ke kterým dochází. Pak můžeme iterovat událostmi a zjistit konkrétní události, kterým chce naše aplikace porozumět. V kódu níže odpovíme na CallConnected událost.

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

Přehrání uvítací zprávy a rozpoznání

Dále předáme text do CallMediaRecognizeChoiceOptions a potom zavoláme StartRecognizingAsync. To vaší aplikaci umožní rozpoznat možnost, která volající zvolí.

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

Zpracování událostí voleb

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

Zavěsit hovor

Nakonec, když zjistíme podmínku, která nám dává smysl ukončit volání, můžeme použít metodu hangUp zavěsit hovor.

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

Spuštění kódu

Přejděte do adresáře obsahujícího soubor pom.xml a použijte následující příkazy mvn:

Zkompilujte aplikaci: mvn compile
Sestavení balíčku: mvn package
Spusťte aplikaci: mvn exec:java

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Nasazený prostředek komunikační služby. Vytvořte prostředek komunikační služby.
Telefonní číslo v prostředku služby Azure Communication Services, které může provádět odchozí hovory. Pokud máte bezplatné předplatné, můžete získat zkušební telefonní číslo.
Vytvoření a hostování azure Dev Tunnelu Tady jsou pokyny.
- Vytvořte a připojte služby Azure AI s více službami k prostředku Azure Communication Services.
Vytvořte vlastní subdoménu pro prostředek služeb Azure AI.
Node.js instalaci LTS.
Nainstalovaný Editor Visual Studio Code
(Volitelné) Uživatel Microsoft Teams s povolenou telefonní licencí voice . K přidání uživatelů Teams do hovoru se vyžaduje telefonní licence Teams. Další informace o licencích Teams najdete tady. Další informace o povolení voice v telefonním systému najdete v tématu Nastavení telefonního systému.

Ukázkový kód

Stáhněte nebo naklonujte ukázkový kód pro rychlý start z GitHubu.

Přejděte do CallAutomation_OutboundCalling složky a otevřete řešení v editoru kódu.

Nastavení prostředí

Stáhněte si ukázkový kód a přejděte do adresáře projektu a spusťte npm příkaz, který nainstaluje potřebné závislosti a nastaví vývojové prostředí.

npm install

Nastavení a hostování Azure DevTunnelu

Azure DevTunnels je služba Azure, která umožňuje sdílet místní webové služby hostované na internetu. Pomocí příkazů rozhraní příkazového řádku DevTunnel připojte místní vývojové prostředí k veřejnému internetu. Tento koncový bod používáme k upozornění vaší aplikace na volání událostí ze služby Azure Communication Services Call Automation.

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

Aktualizace konfigurace aplikace

Potom soubor aktualizujte .env následujícími hodnotami:

CONNECTION_STRING: Připojovací řetězec pro váš prostředek Azure Communication Services. Služby Azure Communication Services najdete připojovací řetězec podle pokynů.
CALLBACK_URI: Po inicializaci hostitele DevTunnel aktualizujte toto pole tímto identifikátorem URI.
TARGET_PHONE_NUMBER: Aktualizujte pole s telefonním číslem, které chcete, aby vaše aplikace volala. Toto telefonní číslo by mělo používat formát telefonního čísla E164 (např. +18881234567).
ACS_RESOURCE_PHONE_NUMBER: Aktualizujte toto pole telefonním číslem služeb Azure Communication Services, které jste získali. Toto telefonní číslo by mělo používat formát telefonního čísla E164 (např. +18881234567).
COGNITIVE_SERVICES_ENDPOINT: Aktualizujte pole pomocí koncového bodu služeb Azure AI.
TARGET_TEAMS_USER_ID: (Volitelné) aktualizační pole s ID uživatele Microsoft Teams, které chcete přidat do hovoru. Viz Použití rozhraní Graph API k získání ID uživatele Teams.

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>"

Uskutečnění odchozího hovoru a přehrávání médií

K odchozímu volání ze služeb Azure Communication Services použijete telefonní číslo, které jste zadali do prostředí. Ujistěte se, že je telefonní číslo ve formátu E164 (např. +18881234567).

Kód provede odchozí volání pomocí target_phone_number, které jste zadali, a umístí odchozí volání na toto číslo:

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

(Volitelné) Přidání uživatele Microsoft Teams do hovoru

Uživatele Microsoft Teams můžete do hovoru přidat pomocí addParticipant metody s microsoftTeamsUserId vlastností. Nejprve je potřeba dokončit autorizaci požadovaného kroku pro prostředek služby Azure Communication Services, aby bylo možné volat uživatelům Microsoft Teams. Volitelně můžete také předat sourceDisplayName text zobrazený v informačním oznámení pro uživatele Teams.

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

Zahájení nahrávání hovoru

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

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

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

recordingId = response.recordingId;

Reakce na události volání

Dříve v naší aplikaci jsme zaregistrovali CALLBACK_URI službu Automatizace volání. Identifikátor URI označuje koncový bod, který služba používá k upozornění na volání událostí, ke kterým dochází. Pak můžeme iterovat událostmi a zjistit konkrétní události, kterým chce naše aplikace porozumět. Na událost reagujeme CallConnected , abychom dostávali oznámení a iniciovali podřízené operace. Pomocí této služby TextSourcemůžete poskytnout text, který chcete syntetizovat a použít pro uvítací zprávu. Služba Automatizace volání služby Azure Communication Services přehraje tuto zprávu při CallConnected události.

Dále předáme text do CallMediaRecognizeChoiceOptions a potom zavoláme StartRecognizingAsync. To vaší aplikaci umožní rozpoznat možnost, která volající zvolí.

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

Zpracování událostí voleb

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

Zavěsit hovor

Nakonec, když zjistíme podmínku, která nám dává smysl ukončit volání, můžeme použít metodu hangUp() zavěsit hovor.

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

Spuštění kódu

Aplikaci spustíte tak, že otevřete okno terminálu a spustíte následující příkaz:

  npm run dev

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Nasazený prostředek komunikační služby. Vytvořte prostředek komunikační služby.
Telefonní číslo v prostředku služby Azure Communication Services, které může provádět odchozí hovory. Pokud máte bezplatné předplatné, můžete získat zkušební telefonní číslo.
Vytvoření a hostování azure Dev Tunnelu Tady jsou pokyny.
Vytvořte a připojte služby Azure AI s více službami k prostředku Azure Communication Services.
Vytvořte vlastní subdoménu pro prostředek služeb Azure AI.
Python 3.7+.
(Volitelné) Uživatel Microsoft Teams s povolenou telefonní licencí voice . K přidání uživatelů Teams do hovoru se vyžaduje telefonní licence Teams. Další informace o licencích Teams najdete tady. Další informace o povolení voice v telefonním systému najdete v tématu Nastavení telefonního systému.

Ukázkový kód

Stáhněte nebo naklonujte ukázkový kód pro rychlý start z GitHubu.

Přejděte do CallAutomation_OutboundCalling složky a otevřete řešení v editoru kódu.

Nastavení prostředí Pythonu

Pomocí následujícího příkazu vytvořte a aktivujte prostředí Pythonu a nainstalujte požadované balíčky. Další informace o správě balíčků najdete tady.

pip install -r requirements.txt

Nastavení a hostování Azure DevTunnelu

Azure DevTunnels je služba Azure, která umožňuje sdílet místní webové služby hostované na internetu. Pomocí příkazů připojte místní vývojové prostředí k veřejnému internetu. DevTunnels vytvoří tunel s trvalou adresou URL koncového bodu a umožňuje anonymní přístup. Tento koncový bod používáme k upozornění vaší aplikace na volání událostí ze služby Azure Communication Services Call Automation.

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

Aktualizace konfigurace aplikace

Potom aktualizujte main.py soubor následujícími hodnotami:

ACS_CONNECTION_STRING: Připojovací řetězec pro váš prostředek Azure Communication Services. Služby Azure Communication Services najdete připojovací řetězec podle pokynů.
CALLBACK_URI_HOST: Po inicializaci hostitele DevTunnel aktualizujte toto pole tímto identifikátorem URI.
TARGET_PHONE_NUMBER: Aktualizujte pole s telefonním číslem, které chcete, aby vaše aplikace volala. Toto telefonní číslo by mělo používat formát telefonního čísla E164 (např. +18881234567).
ACS_PHONE_NUMBER: Aktualizujte toto pole telefonním číslem služeb Azure Communication Services, které jste získali. Toto telefonní číslo by mělo používat formát telefonního čísla E164 (např. +18881234567).
COGNITIVE_SERVICES_ENDPOINT: Aktualizujte pole pomocí koncového bodu služeb Azure AI.
TARGET_TEAMS_USER_ID: (Volitelné) aktualizační pole s ID uživatele Microsoft Teams, které chcete přidat do hovoru. Viz Použití rozhraní Graph API k získání ID uživatele Teams.

# 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>"

Uskutečnění odchozího hovoru

Pokud chcete provést odchozí volání ze služeb Azure Communication Services, nejprve zadáte telefonní číslo, které chcete hovor přijmout. Aby bylo snadné, můžete aktualizovat target_phone_number telefonní číslo ve formátu E164 (např. +18881234567).

Proveďte odchozí volání pomocí target_phone_number, které jste zadali:

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

(Volitelné) Přidání uživatele Microsoft Teams do hovoru

Uživatele Microsoft Teams můžete do hovoru přidat pomocí add_participant metody s MicrosoftTeamsUserIdentifier ID uživatele Teams. Nejprve je potřeba dokončit autorizaci požadovaného kroku pro prostředek služby Azure Communication Services, aby bylo možné volat uživatelům Microsoft Teams. Volitelně můžete také předat source_display_name text zobrazený v informačním oznámení pro uživatele Teams.

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

Zahájení nahrávání hovoru

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

Reakce na události volání

Dříve v naší aplikaci jsme zaregistrovali CALLBACK_URI_HOST službu Automatizace volání. Identifikátor URI označuje koncový bod, který služba používá k upozornění na volání událostí, ke kterým dochází. Pak můžeme iterovat událostmi a zjistit konkrétní události, kterým chce naše aplikace porozumět. V kódu níže odpovíme na CallConnected událost.

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

Přehrání uvítací zprávy a rozpoznání

Dále předáme text do CallMediaRecognizeChoiceOptions a potom zavoláme StartRecognizingAsync. To vaší aplikaci umožní rozpoznat možnost, která volající zvolí.


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

Zpracování událostí voleb

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)

Zavěsit hovor

Nakonec, když zjistíme podmínku, která nám dává smysl ukončit volání, můžeme použít metodu hang_up() zavěsit hovor. Nakonec můžeme také bezpečně zastavit operaci záznamu volání.

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

Spuštění kódu

Visual Studio Code
Visual Studio

Pokud chcete spustit aplikaci pomocí nástroje VS Code, otevřete okno terminálu a spusťte následující příkaz.

python main.py

Rychlý start: Uskutečnění odchozího volání pomocí automatizace volání

Požadavky

Ukázkový kód

Nastavení a hostování Azure DevTunnelu

Aktualizace konfigurace aplikace

Uskutečnění odchozího hovoru

Zpracování událostí automatizace volání

(Volitelné) Přidání uživatele Microsoft Teams do hovoru

Zahájení nahrávání hovoru

Přehrání uvítací zprávy a rozpoznání

Zpracování událostí voleb

Zavěsit a zastavit nahrávání

Spuštění kódu

Požadavky

Ukázkový kód

Nastavení a hostování Azure DevTunnelu

Aktualizace konfigurace aplikace

Uskutečnění odchozího hovoru a přehrávání médií

(Volitelné) Přidání uživatele Microsoft Teams do hovoru

Zahájení nahrávání hovoru

Reakce na události volání

Přehrání uvítací zprávy a rozpoznání

Zpracování událostí voleb

Zavěsit hovor

Spuštění kódu

Požadavky

Ukázkový kód

Nastavení prostředí

Nastavení a hostování Azure DevTunnelu

Aktualizace konfigurace aplikace

Uskutečnění odchozího hovoru a přehrávání médií

(Volitelné) Přidání uživatele Microsoft Teams do hovoru

Zahájení nahrávání hovoru

Reakce na události volání

Zpracování událostí voleb

Zavěsit hovor

Spuštění kódu

Požadavky

Ukázkový kód

Nastavení prostředí Pythonu

Nastavení a hostování Azure DevTunnelu

Aktualizace konfigurace aplikace

Uskutečnění odchozího hovoru

(Volitelné) Přidání uživatele Microsoft Teams do hovoru

Zahájení nahrávání hovoru

Reakce na události volání

Přehrání uvítací zprávy a rozpoznání

Zpracování událostí voleb

Zavěsit hovor

Spuštění kódu

Další materiály