Rövid útmutató: Kimenő hívás kezdeményezése a Call Automation használatával
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
- Egy Azure-fiók, aktív előfizetéssel. Fiók ingyenes létrehozása.
- Üzembe helyezett Communication Services-erőforrás. Hozzon létre egy Communication Services-erőforrást.
- Az Azure Communication Services-erőforrás azon telefonszáma , amely kimenő hívásokat indíthat. Ha ingyenes előfizetéssel rendelkezik, beszerezheti a próbaverzió telefonszámát.
- Azure Dev Tunnel létrehozása és üzemeltetéséhez. Itt talál útmutatást.
- Többszolgáltatásos Azure AI-szolgáltatások létrehozása és csatlakoztatása az Azure Communication Services-erőforráshoz.
- Hozzon létre egy egyéni altartományt az Azure AI-szolgáltatások erőforrásához.
- (Nem kötelező) Engedélyezett telefonos licenccel
voice
rendelkező Microsoft Teams-felhasználó. A Teams telefonos licence szükséges a Teams-felhasználók híváshoz való hozzáadásához. További információ a Teams-licencekről itt. Itt megtudhatja, hogyan engedélyezheti a telefonrendszertvoice
.
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
Másik lehetőségként kövesse az utasításokat az Azure DevTunnel Visual Studióban való beállításához
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
TextSource
A 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
Nyissa meg vagy nyissa meg http://localhost:8080/swagger/index.html
a fejlesztői alagút URL-címét a böngészőben. Az alagút URL-címe a következőképpen néz ki: <YOUR DEV TUNNEL ENDPOINT>/swagger/index.html
Előfeltételek
- Egy Azure-fiók, aktív előfizetéssel. Fiók ingyenes létrehozása.
- Üzembe helyezett Communication Services-erőforrás. Hozzon létre egy Communication Services-erőforrást.
- Az Azure Communication Services-erőforrás azon telefonszáma , amely kimenő hívásokat indíthat. Ha ingyenes előfizetéssel rendelkezik, beszerezheti a próbaverzió telefonszámát.
- Azure Dev Tunnel létrehozása és üzemeltetéséhez. Itt talál útmutatást.
- Többszolgáltatásos Azure AI-szolgáltatások létrehozása és csatlakoztatása az Azure Communication Services-erőforráshoz.
- Hozzon létre egy egyéni altartományt az Azure AI-szolgáltatások erőforrásához.
- A Java Development Kit (JDK) 11-es vagy újabb verziója.
- Apache Maven.
- (Nem kötelező) Engedélyezett telefonos licenccel
voice
rendelkező Microsoft Teams-felhasználó. A Teams telefonos licence szükséges a Teams-felhasználók híváshoz való hozzáadásához. További információ a Teams-licencekről itt. A telefonrendszer engedélyezésérőlvoice
további információt a telefonrendszer beállításával kapcsolatban talál.
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
TextSource
A 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
- Egy Azure-fiók, aktív előfizetéssel. Fiók ingyenes létrehozása.
- Üzembe helyezett Communication Services-erőforrás. Hozzon létre egy Communication Services-erőforrást.
- Az Azure Communication Services-erőforrás azon telefonszáma , amely kimenő hívásokat indíthat. Ha ingyenes előfizetéssel rendelkezik, beszerezheti a próbaverzió telefonszámát.
- Azure Dev Tunnel létrehozása és üzemeltetéséhez. Itt talál útmutatást.
-
- Többszolgáltatásos Azure AI-szolgáltatások létrehozása és csatlakoztatása az Azure Communication Services-erőforráshoz.
- Hozzon létre egy egyéni altartományt az Azure AI-szolgáltatások erőforrásához.
- Node.js LTS-telepítés.
- A Visual Studio Code telepítve van.
- (Nem kötelező) Engedélyezett telefonos licenccel
voice
rendelkező Microsoft Teams-felhasználó. A Teams telefonos licence szükséges a Teams-felhasználók híváshoz való hozzáadásához. További információ a Teams-licencekről itt. A telefonrendszer engedélyezésérőlvoice
további információt a telefonrendszer beállításával kapcsolatban talál.
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 addParticipant
microsoftTeamsUserId
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. TextSource
A 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
- Egy Azure-fiók, aktív előfizetéssel. Fiók ingyenes létrehozása.
- Üzembe helyezett Communication Services-erőforrás. Hozzon létre egy Communication Services-erőforrást.
- Az Azure Communication Services-erőforrás azon telefonszáma , amely kimenő hívásokat indíthat. Ha ingyenes előfizetéssel rendelkezik, beszerezheti a próbaverzió telefonszámát.
- Azure Dev Tunnel létrehozása és üzemeltetéséhez. Itt talál útmutatást.
- Többszolgáltatásos Azure AI-szolgáltatások létrehozása és csatlakoztatása az Azure Communication Services-erőforráshoz.
- Hozzon létre egy egyéni altartományt az Azure AI-szolgáltatások erőforrásához.
- Python 3.7+.
- (Nem kötelező) Engedélyezett telefonos licenccel
voice
rendelkező Microsoft Teams-felhasználó. A Teams telefonos licence szükséges a Teams-felhasználók híváshoz való hozzáadásához. További információ a Teams-licencekről itt. A telefonrendszer engedélyezésérőlvoice
további információt a telefonrendszer beállításával kapcsolatban talál.
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
TextSource
A 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
Visszajelzés
https://aka.ms/ContentUserFeedback.
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ:Visszajelzés küldése és megtekintése a következőhöz: