Rychlý start: Uskutečnění odchozího volání pomocí automatizace volání
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
Případně podle pokynů nastavte Azure DevTunnel v sadě Visual Studio.
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 TextSource
můž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);
}
Spuštění kódu
Pokud chcete spustit aplikaci pomocí nástroje VS Code, otevřete okno terminálu a spusťte následující příkaz.
dotnet run
Otevřete http://localhost:8080/swagger/index.html
adresu URL vývojového tunelu v prohlížeči. Adresa URL tunelu vypadá takto: <YOUR DEV TUNNEL ENDPOINT>/swagger/index.html
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. "00aa00aa-bb11-cc22-dd33-44ee44ee44ee">
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
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ů.
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í
Pomocí této služby TextSource
můž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í.
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
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.
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
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ů.
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 TextSource
můž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
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.
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. "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
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
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ů.
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í
Pomocí této služby TextSource
můž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í.
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
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.
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
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