Mulai Cepat: Melakukan panggilan keluar menggunakan Automasi Panggilan

Artikel
04/07/2024

API Automasi Panggilan Azure Communication Services adalah cara yang ampuh untuk menciptakan pengalaman panggilan interaktif. Dalam mulai cepat ini, kita membahas cara untuk melakukan panggilan keluar dan mengenali berbagai peristiwa dalam panggilan.

Prasyarat

Akun Azure dengan langganan aktif. Buat akun secara gratis.
Sumber daya Communication Services yang disebarkan. Buat sumber daya Azure Communication Services.
Nomor telepon di sumber daya Azure Communication Services Anda yang dapat melakukan panggilan keluar. Jika Anda memiliki langganan gratis, Anda bisa mendapatkan nomor telepon uji coba.
Membuat dan menghosting Azure Dev Tunnel. Instruksi di sini.
Membuat dan menyambungkan layanan Azure AI Multi-layanan ke sumber daya Azure Communication Services Anda.
Buat subdomain kustom untuk sumber daya layanan Azure AI Anda.
(Opsional) Pengguna Microsoft Teams dengan lisensi telepon yang voice diaktifkan. Lisensi telepon Teams diperlukan untuk menambahkan pengguna Teams ke panggilan. Pelajari selengkapnya tentang lisensi Teams di sini. Pelajari tentang mengaktifkan sistem telepon dengan voicedi sini.

Kode Sampel

Unduh atau klon kode sampel mulai cepat dari GitHub.

Navigasi ke CallAutomation_OutboundCalling folder dan buka solusi di editor kode.

Menyiapkan dan menghosting Azure DevTunnel Anda

Azure DevTunnels adalah layanan Azure yang memungkinkan Anda berbagi layanan web lokal yang dihosting di internet. Jalankan perintah untuk menghubungkan lingkungan pengembangan lokal Anda ke internet publik. DevTunnels membuat URL titik akhir persisten dan yang memungkinkan akses anonim. Kami menggunakan titik akhir ini untuk memberi tahu aplikasi Anda tentang peristiwa panggilan dari layanan Azure Communication Services Call Automation.

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

Memperbarui konfigurasi aplikasi Anda

Selanjutnya perbarui file Anda Program.cs dengan nilai berikut:

acsConnectionString: string koneksi untuk sumber daya Azure Communication Services Anda. Anda dapat menemukan String koneksi Azure Communication Services menggunakan instruksi di sini.
callbackUriHost: Setelah host DevTunnel Anda diinisialisasi, perbarui bidang ini dengan URI tersebut.
acsPhonenumber: perbarui bidang ini dengan nomor telepon Azure Communication Services yang telah Anda peroleh. Nomor telepon ini harus menggunakan format nomor telepon E164 (misalnya +18881234567)
targetPhonenumber: perbarui bidang dengan nomor telepon yang Anda inginkan untuk dihubungi aplikasi Anda. Nomor telepon ini harus menggunakan format nomor telepon E164 (misalnya +18881234567)
cognitiveServiceEndpoint: perbarui bidang dengan titik akhir layanan Azure AI Anda.
targetTeamsUserId: Bidang pembaruan (Opsional) dengan Id pengguna Microsoft Teams yang ingin Anda tambahkan ke panggilan. Lihat Menggunakan Graph API untuk mendapatkan ID pengguna 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>";

Melakukan panggilan keluar

Untuk melakukan panggilan keluar dari Azure Communication Services, sampel ini menggunakan yang targetPhonenumber Anda tentukan sebelumnya dalam aplikasi untuk membuat panggilan menggunakan CreateCallAsync API. Kode ini akan melakukan panggilan keluar menggunakan nomor telepon target.

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

Menangani peristiwa otomatisasi panggilan

Sebelumnya dalam aplikasi kami, kami mendaftarkan callbackUriHost ke Layanan Automasi Panggilan. Host menunjukkan titik akhir yang diperlukan layanan untuk memberi tahu kami tentang peristiwa panggilan yang terjadi. Kami kemudian dapat melakukan iterasi melalui peristiwa dan mendeteksi peristiwa tertentu yang ingin dipahami aplikasi kami. Dalam kode di bawah ini, kami merespons peristiwa tersebut 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
    }
  }
});

(Opsional) Menambahkan pengguna Microsoft Teams ke panggilan

Anda dapat menambahkan pengguna Microsoft Teams ke panggilan menggunakan AddParticipantAsync metode dengan MicrosoftTeamsUserIdentifier id pengguna Teams dan . Pertama-tama Anda perlu menyelesaikan Otorisasi langkah prasyarat untuk Sumber Daya Azure Communication Services Anda untuk mengaktifkan panggilan ke pengguna Microsoft Teams. Secara opsional, Anda juga dapat meneruskan untuk mengontrol teks yang SourceDisplayName ditampilkan dalam pemberitahuan toast untuk pengguna Teams.

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

Mulai merekam panggilan

Layanan Call Automation juga memungkinkan kemampuan untuk mulai merekam dan menyimpan rekaman panggilan suara dan video. Anda dapat mempelajari selengkapnya tentang berbagai kemampuan di API Perekaman Panggilan di sini.

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

Memutar pesan selamat datang dan mengenali

TextSourceDengan menggunakan , Anda dapat menyediakan layanan dengan teks yang ingin Anda sintesiskan dan digunakan untuk pesan selamat datang Anda. Layanan Automasi Panggilan Azure Communication Services memutar pesan ini saat CallConnected kejadian.

Selanjutnya, kita meneruskan teks ke CallMediaRecognizeChoiceOptions dan kemudian memanggil StartRecognizingAsync. Ini memungkinkan aplikasi Anda mengenali opsi yang dipilih pemanggil.

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

Menangani Peristiwa Pilihan

Azure Communication Services Call Automation memicu api/callbacks ke webhook yang telah kami siapkan dan akan memberi tahu kami tentang peristiwa tersebut RecognizeCompleted . Peristiwa ini memberi kita kemampuan untuk menanggapi input yang diterima dan memicu tindakan. Aplikasi kemudian memutar pesan kepada pemanggil berdasarkan input tertentu yang diterima.

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

Tutup dan hentikan perekaman

Akhirnya, ketika kita mendeteksi kondisi yang masuk akal bagi kita untuk mengakhiri panggilan, kita dapat menggunakan HangUpAsync metode untuk menutup panggilan.

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

Untuk menjalankan aplikasi dengan Visual Studio Code, buka jendela Terminal dan jalankan perintah berikut

dotnet run

Prasyarat

Akun Azure dengan langganan aktif. Buat akun secara gratis.
Sumber daya Communication Services yang disebarkan. Buat sumber daya Azure Communication Services.
Nomor telepon di sumber daya Azure Communication Services Anda yang dapat melakukan panggilan keluar. Jika Anda memiliki langganan gratis, Anda bisa mendapatkan nomor telepon uji coba.
Membuat dan menghosting Azure Dev Tunnel. Instruksi di sini.
Membuat dan menyambungkan layanan Azure AI Multi-layanan ke sumber daya Azure Communication Services Anda.
Buat subdomain kustom untuk sumber daya layanan Azure AI Anda.
Java Development Kit (JDK) versi 11 atau lebih tinggi.
Apache Maven.
(Opsional) Pengguna Microsoft Teams dengan lisensi telepon yang voice diaktifkan. Lisensi telepon Teams diperlukan untuk menambahkan pengguna Teams ke panggilan. Pelajari selengkapnya tentang lisensi Teams di sini. Untuk informasi selengkapnya tentang mengaktifkan voice sistem telepon Anda, lihat menyiapkan sistem telepon Anda.

Kode Sampel

Unduh atau klon kode sampel mulai cepat dari GitHub.

Navigasi ke CallAutomation_OutboundCalling folder dan buka solusi di editor kode.

Menyiapkan dan menghosting Azure DevTunnel Anda

Azure DevTunnels adalah layanan Azure yang memungkinkan Anda berbagi layanan web lokal yang dihosting di internet. Jalankan perintah DevTunnel untuk menghubungkan lingkungan pengembangan lokal Anda ke internet publik. DevTunnels kemudian membuat terowongan dengan URL titik akhir persisten dan yang memungkinkan akses anonim. Azure Communication Services menggunakan titik akhir ini untuk memberi tahu aplikasi Anda tentang peristiwa panggilan dari layanan Azure Communication Services Call Automation.

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

Memperbarui konfigurasi aplikasi Anda

Kemudian buka application.yml file di /resources folder untuk mengonfigurasi nilai berikut:

connectionstring: string koneksi untuk sumber daya Azure Communication Services Anda. Anda dapat menemukan String koneksi Azure Communication Services menggunakan instruksi di sini.
basecallbackuri: Setelah host DevTunnel Anda diinisialisasi, perbarui bidang ini dengan URI tersebut.
callerphonenumber: perbarui bidang ini dengan nomor telepon Azure Communication Services yang telah Anda peroleh. Nomor telepon ini harus menggunakan format nomor telepon E164 (misalnya +18881234567)
targetphonenumber: perbarui bidang dengan nomor telepon yang Anda inginkan untuk dihubungi aplikasi Anda. Nomor telepon ini harus menggunakan format nomor telepon E164 (misalnya +18881234567)
cognitiveServiceEndpoint: perbarui bidang dengan titik akhir layanan Azure AI Anda.
targetTeamsUserId: Bidang pembaruan (Opsional) dengan Id pengguna Microsoft Teams yang ingin Anda tambahkan ke panggilan. Lihat Menggunakan Graph API untuk mendapatkan ID pengguna 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">

Melakukan panggilan keluar dan memutar media

Untuk melakukan panggilan keluar dari Azure Communication Services, sampel ini menggunakan yang targetphonenumber Anda tentukan dalam application.yml file untuk membuat panggilan menggunakan createCallWithResponse API.

PhoneNumberIdentifier caller = new PhoneNumberIdentifier(appConfig.getCallerphonenumber());
PhoneNumberIdentifier target = new PhoneNumberIdentifier(appConfig.getTargetphonenumber());
CallInvite callInvite = new CallInvite(target, caller);
CreateCallOptions createCallOptions = new CreateCallOptions(callInvite, appConfig.getCallBackUri());
CallIntelligenceOptions callIntelligenceOptions = new CallIntelligenceOptions().setCognitiveServicesEndpoint(appConfig.getCognitiveServiceEndpoint());
createCallOptions = createCallOptions.setCallIntelligenceOptions(callIntelligenceOptions);
Response<CreateCallResult> result = client.createCallWithResponse(createCallOptions, Context.NONE);

(Opsional) Menambahkan pengguna Microsoft Teams ke panggilan

Anda dapat menambahkan pengguna Microsoft Teams ke panggilan menggunakan addParticipant metode dengan MicrosoftTeamsUserIdentifier id pengguna Teams dan . Pertama-tama Anda perlu menyelesaikan Otorisasi langkah prasyarat untuk Sumber Daya Azure Communication Services Anda untuk mengaktifkan panggilan ke pengguna Microsoft Teams. Secara opsional, Anda juga dapat meneruskan untuk mengontrol teks yang SourceDisplayName ditampilkan dalam pemberitahuan toast untuk pengguna Teams.

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

Mulai merekam panggilan

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

Menanggapi peristiwa panggilan

Sebelumnya dalam aplikasi kami, kami mendaftarkan basecallbackuri ke Layanan Automasi Panggilan. URI menunjukkan titik akhir yang akan digunakan layanan untuk memberi tahu kami tentang peristiwa panggilan yang terjadi. Kami kemudian dapat melakukan iterasi melalui peristiwa dan mendeteksi peristiwa tertentu yang ingin dipahami aplikasi kami. Dalam kode di bawah ini, kami merespons peristiwa tersebut 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");
    }
}

Memutar pesan selamat datang dan mengenali

Selanjutnya, kita meneruskan teks ke CallMediaRecognizeChoiceOptions dan kemudian memanggil StartRecognizingAsync. Ini memungkinkan aplikasi Anda mengenali opsi yang dipilih pemanggil.

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

Menangani Peristiwa Pilihan

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

Menutup panggilan

Akhirnya, ketika kita mendeteksi kondisi yang masuk akal bagi kita untuk mengakhiri panggilan, kita dapat menggunakan hangUp metode untuk menutup panggilan.

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

Menjalankan kode

Navigasi ke direktori yang berisi file pom.xml dan gunakan perintah mvn berikut:

Kompilasi aplikasi: mvn compile
Bangun paket: mvn package
Jalankan aplikasi: mvn exec:java

Prasyarat

Akun Azure dengan langganan aktif. Buat akun secara gratis.
Sumber daya Communication Services yang disebarkan. Buat sumber daya Azure Communication Services.
Nomor telepon di sumber daya Azure Communication Services Anda yang dapat melakukan panggilan keluar. Jika Anda memiliki langganan gratis, Anda bisa mendapatkan nomor telepon uji coba.
Membuat dan menghosting Azure Dev Tunnel. Instruksi di sini.
- Membuat dan menyambungkan layanan Azure AI Multi-layanan ke sumber daya Azure Communication Services Anda.
Buat subdomain kustom untuk sumber daya layanan Azure AI Anda.
Node.js penginstalan LTS.
Kode Studio Visual terinstal.
(Opsional) Pengguna Microsoft Teams dengan lisensi telepon yang voice diaktifkan. Lisensi telepon Teams diperlukan untuk menambahkan pengguna Teams ke panggilan. Pelajari selengkapnya tentang lisensi Teams di sini. Untuk informasi selengkapnya tentang mengaktifkan voice sistem telepon Anda, lihat menyiapkan sistem telepon Anda.

Kode Sampel

Unduh atau klon kode sampel mulai cepat dari GitHub.

Navigasi ke CallAutomation_OutboundCalling folder dan buka solusi di editor kode.

Menyiapkan lingkungan

Unduh kode sampel dan navigasikan ke direktori proyek dan jalankan npm perintah yang menginstal dependensi yang diperlukan dan menyiapkan lingkungan pengembang Anda.

npm install

Menyiapkan dan menghosting Azure DevTunnel Anda

Azure DevTunnels adalah layanan Azure yang memungkinkan Anda berbagi layanan web lokal yang dihosting di internet. Gunakan perintah DevTunnel CLI untuk menghubungkan lingkungan pengembangan lokal Anda ke internet publik. Kami menggunakan titik akhir ini untuk memberi tahu aplikasi Anda tentang peristiwa panggilan dari layanan Azure Communication Services Call Automation.

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

Memperbarui konfigurasi aplikasi Anda

Kemudian perbarui file Anda .env dengan nilai berikut:

CONNECTION_STRING: string koneksi untuk sumber daya Azure Communication Services Anda. Anda dapat menemukan String koneksi Azure Communication Services menggunakan instruksi di sini.
CALLBACK_URI: Setelah host DevTunnel Anda diinisialisasi, perbarui bidang ini dengan URI tersebut.
TARGET_PHONE_NUMBER: perbarui bidang dengan nomor telepon yang Anda inginkan untuk dihubungi aplikasi Anda. Nomor telepon ini harus menggunakan format nomor telepon E164 (misalnya +18881234567)
ACS_RESOURCE_PHONE_NUMBER: perbarui bidang ini dengan nomor telepon Azure Communication Services yang telah Anda peroleh. Nomor telepon ini harus menggunakan format nomor telepon E164 (misalnya +18881234567)
COGNITIVE_SERVICES_ENDPOINT: perbarui bidang dengan titik akhir layanan Azure AI Anda.
TARGET_TEAMS_USER_ID: Bidang pembaruan (Opsional) dengan Id pengguna Microsoft Teams yang ingin Anda tambahkan ke panggilan. Lihat Menggunakan Graph API untuk mendapatkan ID pengguna 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>"

Melakukan panggilan keluar dan memutar media

Untuk melakukan panggilan keluar dari Azure Communication Services, Anda menggunakan nomor telepon yang Anda berikan ke lingkungan. Pastikan bahwa nomor telepon dalam format nomor telepon E164 (misalnya +18881234567)

Kode melakukan panggilan keluar menggunakan target_phone_number yang telah Anda berikan dan melakukan panggilan keluar ke nomor tersebut:

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

(Opsional) Menambahkan pengguna Microsoft Teams ke panggilan

Anda dapat menambahkan pengguna Microsoft Teams ke panggilan menggunakan addParticipant metode dengan microsoftTeamsUserId properti . Pertama-tama Anda perlu menyelesaikan Otorisasi langkah prasyarat untuk Sumber Daya Azure Communication Services Anda untuk mengaktifkan panggilan ke pengguna Microsoft Teams. Secara opsional, Anda juga dapat meneruskan untuk mengontrol teks yang sourceDisplayName ditampilkan dalam pemberitahuan toast untuk pengguna Teams.

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

Mulai merekam panggilan

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

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

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

recordingId = response.recordingId;

Menanggapi peristiwa panggilan

Sebelumnya dalam aplikasi kami, kami mendaftarkan CALLBACK_URI ke Layanan Automasi Panggilan. URI menunjukkan titik akhir yang digunakan layanan untuk memberi tahu kami tentang peristiwa panggilan yang terjadi. Kami kemudian dapat melakukan iterasi melalui peristiwa dan mendeteksi peristiwa tertentu yang ingin dipahami aplikasi kami. Kami menanggapi peristiwa tersebut CallConnected untuk mendapatkan pemberitahuan dan memulai operasi hilir. TextSourceDengan menggunakan , Anda dapat menyediakan layanan dengan teks yang ingin Anda sintesiskan dan digunakan untuk pesan selamat datang Anda. Layanan Automasi Panggilan Azure Communication Services memutar pesan ini saat CallConnected kejadian.

Selanjutnya, kita meneruskan teks ke CallMediaRecognizeChoiceOptions dan kemudian memanggil StartRecognizingAsync. Ini memungkinkan aplikasi Anda mengenali opsi yang dipilih pemanggil.

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

Menangani Peristiwa Pilihan

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

Menutup panggilan

Akhirnya, ketika kita mendeteksi kondisi yang masuk akal bagi kita untuk mengakhiri panggilan, kita dapat menggunakan hangUp() metode untuk menutup panggilan.

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

Menjalankan kode

Untuk menjalankan aplikasi, buka jendela Terminal dan jalankan perintah berikut:

  npm run dev

Prasyarat

Akun Azure dengan langganan aktif. Buat akun secara gratis.
Sumber daya Communication Services yang disebarkan. Buat sumber daya Azure Communication Services.
Nomor telepon di sumber daya Azure Communication Services Anda yang dapat melakukan panggilan keluar. Jika Anda memiliki langganan gratis, Anda bisa mendapatkan nomor telepon uji coba.
Membuat dan menghosting Azure Dev Tunnel. Instruksi di sini.
Membuat dan menyambungkan layanan Azure AI Multi-layanan ke sumber daya Azure Communication Services Anda.
Buat subdomain kustom untuk sumber daya layanan Azure AI Anda.
Python 3.7+.
(Opsional) Pengguna Microsoft Teams dengan lisensi telepon yang voice diaktifkan. Lisensi telepon Teams diperlukan untuk menambahkan pengguna Teams ke panggilan. Pelajari selengkapnya tentang lisensi Teams di sini. Untuk informasi selengkapnya tentang mengaktifkan voice sistem telepon Anda, lihat menyiapkan sistem telepon Anda.

Kode Sampel

Unduh atau klon kode sampel mulai cepat dari GitHub.

Navigasi ke CallAutomation_OutboundCalling folder dan buka solusi di editor kode.

Menyiapkan lingkungan Python

Buat dan aktifkan lingkungan python dan instal paket yang diperlukan menggunakan perintah berikut. Anda dapat mempelajari selengkapnya tentang mengelola paket di sini

pip install -r requirements.txt

Menyiapkan dan menghosting Azure DevTunnel Anda

Azure DevTunnels adalah layanan Azure yang memungkinkan Anda berbagi layanan web lokal yang dihosting di internet. Gunakan perintah untuk menghubungkan lingkungan pengembangan lokal Anda ke internet publik. DevTunnels membuat terowongan dengan URL titik akhir persisten dan yang memungkinkan akses anonim. Kami menggunakan titik akhir ini untuk memberi tahu aplikasi Anda tentang peristiwa panggilan dari layanan Azure Communication Services Call Automation.

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

Memperbarui konfigurasi aplikasi Anda

Kemudian perbarui file Anda main.py dengan nilai berikut:

ACS_CONNECTION_STRING: string koneksi untuk sumber daya Azure Communication Services Anda. Anda dapat menemukan String koneksi Azure Communication Services menggunakan instruksi di sini.
CALLBACK_URI_HOST: Setelah host DevTunnel Anda diinisialisasi, perbarui bidang ini dengan URI tersebut.
TARGET_PHONE_NUMBER: perbarui bidang dengan nomor telepon yang Anda inginkan untuk dihubungi aplikasi Anda. Nomor telepon ini harus menggunakan format nomor telepon E164 (misalnya +18881234567)
ACS_PHONE_NUMBER: perbarui bidang ini dengan nomor telepon Azure Communication Services yang telah Anda peroleh. Nomor telepon ini harus menggunakan format nomor telepon E164 (misalnya +18881234567)
COGNITIVE_SERVICES_ENDPOINT: perbarui bidang dengan titik akhir layanan Azure AI Anda.
TARGET_TEAMS_USER_ID: Bidang pembaruan (Opsional) dengan Id pengguna Microsoft Teams yang ingin Anda tambahkan ke panggilan. Lihat Menggunakan Graph API untuk mendapatkan ID pengguna 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>"

Melakukan panggilan keluar

Untuk melakukan panggilan keluar dari Azure Communication Services, pertama-tama Anda memberikan nomor telepon yang ingin Anda terima panggilannya. Agar sederhana, Anda dapat memperbarui target_phone_number dengan nomor telepon dalam format nomor telepon E164 (misalnya +18881234567)

Lakukan panggilan keluar menggunakan target_phone_number yang Telah Anda berikan:

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

(Opsional) Menambahkan pengguna Microsoft Teams ke panggilan

Anda dapat menambahkan pengguna Microsoft Teams ke panggilan menggunakan add_participant metode dengan MicrosoftTeamsUserIdentifier id pengguna Teams dan . Pertama-tama Anda perlu menyelesaikan Otorisasi langkah prasyarat untuk Sumber Daya Azure Communication Services Anda untuk mengaktifkan panggilan ke pengguna Microsoft Teams. Secara opsional, Anda juga dapat meneruskan untuk mengontrol teks yang source_display_name ditampilkan dalam pemberitahuan toast untuk pengguna Teams.

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

Mulai merekam panggilan

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

Menanggapi peristiwa panggilan

Sebelumnya dalam aplikasi kami, kami mendaftarkan CALLBACK_URI_HOST ke Layanan Automasi Panggilan. URI menunjukkan titik akhir yang digunakan layanan untuk memberi tahu kami tentang peristiwa panggilan yang terjadi. Kami kemudian dapat melakukan iterasi melalui peristiwa dan mendeteksi peristiwa tertentu yang ingin dipahami aplikasi kami. Dalam kode di bawah ini, kami merespons peristiwa tersebut 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)

Memutar pesan selamat datang dan mengenali

Selanjutnya, kita meneruskan teks ke CallMediaRecognizeChoiceOptions dan kemudian memanggil StartRecognizingAsync. Ini memungkinkan aplikasi Anda mengenali opsi yang dipilih pemanggil.


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

Menangani Peristiwa Pilihan

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)

Menutup panggilan

Akhirnya, ketika kita mendeteksi kondisi yang masuk akal bagi kita untuk mengakhiri panggilan, kita dapat menggunakan hang_up() metode untuk menutup panggilan. Akhirnya, kita juga dapat menghentikan operasi perekaman panggilan dengan aman.

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

Menjalankan kode

Visual Studio Code
Visual Studio

Untuk menjalankan aplikasi dengan Visual Studio Code, buka jendela Terminal dan jalankan perintah berikut

python main.py

Mulai Cepat: Melakukan panggilan keluar menggunakan Automasi Panggilan

Prasyarat

Kode Sampel

Menyiapkan dan menghosting Azure DevTunnel Anda

Memperbarui konfigurasi aplikasi Anda

Melakukan panggilan keluar

Menangani peristiwa otomatisasi panggilan

(Opsional) Menambahkan pengguna Microsoft Teams ke panggilan

Mulai merekam panggilan

Memutar pesan selamat datang dan mengenali

Menangani Peristiwa Pilihan

Tutup dan hentikan perekaman

Menjalankan kode

Prasyarat

Kode Sampel

Menyiapkan dan menghosting Azure DevTunnel Anda

Memperbarui konfigurasi aplikasi Anda

Melakukan panggilan keluar dan memutar media

(Opsional) Menambahkan pengguna Microsoft Teams ke panggilan

Mulai merekam panggilan

Menanggapi peristiwa panggilan

Memutar pesan selamat datang dan mengenali

Menangani Peristiwa Pilihan

Menutup panggilan

Menjalankan kode

Prasyarat

Kode Sampel

Menyiapkan lingkungan

Menyiapkan dan menghosting Azure DevTunnel Anda

Memperbarui konfigurasi aplikasi Anda

Melakukan panggilan keluar dan memutar media

(Opsional) Menambahkan pengguna Microsoft Teams ke panggilan

Mulai merekam panggilan

Menanggapi peristiwa panggilan

Menangani Peristiwa Pilihan

Menutup panggilan

Menjalankan kode

Prasyarat

Kode Sampel

Menyiapkan lingkungan Python

Menyiapkan dan menghosting Azure DevTunnel Anda

Memperbarui konfigurasi aplikasi Anda

Melakukan panggilan keluar

(Opsional) Menambahkan pengguna Microsoft Teams ke panggilan

Mulai merekam panggilan

Menanggapi peristiwa panggilan

Memutar pesan selamat datang dan mengenali

Menangani Peristiwa Pilihan

Menutup panggilan

Menjalankan kode

Sumber Daya Tambahan: