Hızlı Başlangıç: Çağrı Otomasyonu kullanarak giden arama yapma

  • Makale

Azure İletişim Hizmetleri Çağrı Otomasyonu API'leri etkileşimli arama deneyimleri oluşturmanın güçlü bir yoludur. Bu hızlı başlangıçta, giden arama yapma ve aramadaki çeşitli olayları tanımanın bir yolunu ele alacağız.

Önkoşullar

Örnek kod

GitHub'dan hızlı başlangıç örnek kodunu indirin veya kopyalayın.

Klasöre CallAutomation_OutboundCalling gidin ve çözümü bir kod düzenleyicisinde açın.

Azure DevTunnel'inizi ayarlama ve barındırma

Azure DevTunnels , İnternet'te barındırılan yerel web hizmetlerini paylaşmanızı sağlayan bir Azure hizmetidir. Yerel geliştirme ortamınızı genel İnternet'e bağlamak için komutları çalıştırın. DevTunnels, anonim erişime izin veren kalıcı bir uç nokta URL'si oluşturur. Bu uç noktayı, Azure İletişim Hizmetleri Çağrı Otomasyonu hizmetinden olayları çağıran uygulamanızı bilgilendirmek için kullanırız.

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

Alternatif olarak, Visual Studio'da Azure DevTunnel'inizi ayarlamak için yönergeleri izleyin

Uygulama yapılandırmanızı güncelleştirme

Ardından dosyanızı Program.cs aşağıdaki değerlerle güncelleştirin:

  • acsConnectionString: Azure İletişim Hizmetleri kaynağınızın bağlantı dizesi. buradaki yönergeleri kullanarak Azure İletişim Hizmetleri bağlantı dizesi bulabilirsiniz.
  • callbackUriHost: DevTunnel ana bilgisayarınız başlatıldıktan sonra bu alanı bu URI ile güncelleştirin.
  • acsPhonenumber: bu alanı, edindiğiniz Azure İletişim Hizmetleri telefon numarasıyla güncelleştirin. Bu telefon numarası E164 telefon numarası biçimini kullanmalıdır (ör. +18881234567)
  • targetPhonenumber: uygulamanızın aramasını istediğiniz telefon numarasıyla alanı güncelleştirin. Bu telefon numarası E164 telefon numarası biçimini kullanmalıdır (ör. +18881234567)
  • cognitiveServiceEndpoint: Alanını Azure AI hizmetleri uç noktanızla güncelleştirin.
  • targetTeamsUserId: (İsteğe bağlı) aramasına eklemek istediğiniz Microsoft Teams kullanıcı kimliğine sahip güncelleştirme alanı. Bkz . Teams kullanıcı kimliğini almak için Graph API'sini kullanma.
// 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>";

Giden arama yapma

Azure İletişim Hizmetleri'dan giden çağrı yapmak için bu örnek, api kullanarak çağrıyı oluşturmak için uygulamada daha önce tanımladığınız çağrıyı CreateCallAsync kullanırtargetPhonenumber. Bu kod, hedef telefon numarasını kullanarak bir giden arama yapar.

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

Çağrı otomasyonu olaylarını işleme

Uygulamamızın önceki bölümlerinde Çağrı Otomasyonu Hizmeti'ne kaydettik callbackUriHost . Konak, hizmetin gerçekleşen olayları çağırmak için bize bildirmesi gereken uç noktayı belirtir. Ardından olaylar arasında yineleme yapabilir ve uygulamamızın anlamak istediği belirli olayları algılayabiliriz. Aşağıdaki kodda olayı yanıtlıyoruz 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
    }
  }
});

(İsteğe bağlı) Aramaya Microsoft Teams kullanıcısı ekleme

Ve Teams kullanıcı kimliği ile yöntemini kullanarak AddParticipantAsync aramaya bir MicrosoftTeamsUserIdentifier Microsoft Teams kullanıcısı ekleyebilirsiniz. Microsoft Teams kullanıcılarına çağrıyı etkinleştirmek için önce Azure İletişim Hizmetleri Kaynağınız için Yetkilendirme önkoşul adımını tamamlamanız gerekir. İsteğe bağlı olarak, Teams kullanıcısı için bildirim bildiriminde görüntülenen metni denetlemek için bir SourceDisplayName de geçirebilirsiniz.

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

Aramayı kaydetmeye başlama

Çağrı Otomasyonu hizmeti ayrıca sesli ve görüntülü arama kayıtlarını kaydetmeye ve depolamaya başlama olanağı sağlar. Arama Kaydı API'leri hakkında daha fazla bilgiyi burada bulabilirsiniz.

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

Karşılama iletisini yürütme ve tanıma

TextSourcekullanarak, karşılama iletiniz için sentezlenmesini ve kullanılmasını istediğiniz metni hizmete sağlayabilirsiniz. Azure İletişim Hizmetleri Çağrı Otomasyonu hizmeti bu iletiyi olay üzerinde oynatmaktadırCallConnected.

Ardından metni içine CallMediaRecognizeChoiceOptions geçirip çağrısı StartRecognizingAsyncyapacağız. Bu, uygulamanızın çağıranın seçtiği seçeneği tanımasını sağlar.

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

Seçim Olaylarını İşle

Azure İletişim Hizmetleri Çağrı Otomasyonu, kurulumu yaptığımız web kancasını tetikler api/callbacks ve olayı bize RecognizeCompleted bildirir. Olay, bize alınan girişlere yanıt verme ve bir eylem tetikleme olanağı sağlar. Uygulama daha sonra, alınan belirli girişe göre çağırana bir ileti çalar.

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

Kapatma ve kaydı durdurma

Son olarak, çağrıyı sonlandırmamız için mantıklı bir koşul algıladığımızda, çağrıyı HangUpAsync kapatmak için yöntemini kullanabiliriz.

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

Kodu çalıştırma

Uygulamayı VS Code ile çalıştırmak için bir Terminal penceresi açın ve aşağıdaki komutu çalıştırın

dotnet run

Tarayıcıda geliştirme tüneli URL'nizi veya geliştirme tüneli URL'nizi açın http://localhost:8080/swagger/index.html . Tünel URL'si şöyle görünür: <YOUR DEV TUNNEL ENDPOINT>/swagger/index.html

Önkoşullar

Örnek kod

GitHub'dan hızlı başlangıç örnek kodunu indirin veya kopyalayın.

Klasöre CallAutomation_OutboundCalling gidin ve çözümü bir kod düzenleyicisinde açın.

Azure DevTunnel'inizi ayarlama ve barındırma

Azure DevTunnels , İnternet'te barındırılan yerel web hizmetlerini paylaşmanızı sağlayan bir Azure hizmetidir. Yerel geliştirme ortamınızı genel İnternet'e bağlamak için DevTunnel komutlarını çalıştırın. DevTunnels daha sonra kalıcı uç nokta URL'sine sahip ve anonim erişime izin veren bir tünel oluşturur. Azure İletişim Hizmetleri, Azure İletişim Hizmetleri Çağrı Otomasyonu hizmetinden olayları çağırmayı uygulamanıza bildirmek için bu uç noktayı kullanır.

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

Uygulama yapılandırmanızı güncelleştirme

Ardından aşağıdaki değerleri yapılandırmak için klasöründeki dosyayı /resources açınapplication.yml:

  • connectionstring: Azure İletişim Hizmetleri kaynağınızın bağlantı dizesi. buradaki yönergeleri kullanarak Azure İletişim Hizmetleri bağlantı dizesi bulabilirsiniz.
  • basecallbackuri: DevTunnel ana bilgisayarınız başlatıldıktan sonra bu alanı bu URI ile güncelleştirin.
  • callerphonenumber: bu alanı, edindiğiniz Azure İletişim Hizmetleri telefon numarasıyla güncelleştirin. Bu telefon numarası E164 telefon numarası biçimini kullanmalıdır (ör. +18881234567)
  • targetphonenumber: uygulamanızın aramasını istediğiniz telefon numarasıyla alanı güncelleştirin. Bu telefon numarası E164 telefon numarası biçimini kullanmalıdır (ör. +18881234567)
  • cognitiveServiceEndpoint: Alanını Azure AI hizmetleri uç noktanızla güncelleştirin.
  • targetTeamsUserId: (İsteğe bağlı) aramasına eklemek istediğiniz Microsoft Teams kullanıcı kimliğine sahip güncelleştirme alanı. Bkz . Teams kullanıcı kimliğini almak için Graph API'sini kullanma.
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">

Giden arama yapma ve medya yürütme

Azure İletişim Hizmetleri'dan giden çağrı yapmak için bu örnek, API'yi kullanarak çağrıyı oluşturmak için dosyada application.yml tanımladığınız çağrıyı createCallWithResponse kullanırtargetphonenumber.

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

(İsteğe bağlı) Aramaya Microsoft Teams kullanıcısı ekleme

Ve Teams kullanıcı kimliği ile yöntemini kullanarak addParticipant aramaya bir MicrosoftTeamsUserIdentifier Microsoft Teams kullanıcısı ekleyebilirsiniz. Microsoft Teams kullanıcılarına çağrıyı etkinleştirmek için önce Azure İletişim Hizmetleri Kaynağınız için Yetkilendirme önkoşul adımını tamamlamanız gerekir. İsteğe bağlı olarak, Teams kullanıcısı için bildirim bildiriminde görüntülenen metni denetlemek için bir SourceDisplayName de geçirebilirsiniz.

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

Aramayı kaydetmeye başlama

Çağrı Otomasyonu hizmeti ayrıca sesli ve görüntülü arama kayıtlarını kaydetmeye ve depolamaya başlama olanağı sağlar. Arama Kaydı API'leri hakkında daha fazla bilgiyi burada bulabilirsiniz.

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

Çağrı olaylarını yanıtlama

Uygulamamızın önceki bölümlerinde Çağrı Otomasyonu Hizmeti'ne kaydettik basecallbackuri . URI, hizmetin gerçekleşen olayları çağırmak için bizi bilgilendirmek için kullanacağı uç noktayı gösterir. Ardından olaylar arasında yineleme yapabilir ve uygulamamızın anlamak istediği belirli olayları algılayabiliriz. Aşağıdaki kodda olayı yanıtlıyoruz 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");
    }
}

Karşılama iletisini yürütme ve tanıma

TextSourcekullanarak, karşılama iletiniz için sentezlenmesini ve kullanılmasını istediğiniz metni hizmete sağlayabilirsiniz. Azure İletişim Hizmetleri Çağrı Otomasyonu hizmeti bu iletiyi olay üzerinde oynatmaktadırCallConnected.

Ardından metni içine CallMediaRecognizeChoiceOptions geçirip çağrısı StartRecognizingAsyncyapacağız. Bu, uygulamanızın çağıranın seçtiği seçeneği tanımasını sağlar.

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

Seçim Olaylarını İşle

Azure İletişim Hizmetleri Çağrı Otomasyonu, kurulumu yaptığımız web kancasını tetikler api/callbacks ve olayı bize RecognizeCompleted bildirir. Olay, bize alınan girişlere yanıt verme ve bir eylem tetikleme olanağı sağlar. Uygulama daha sonra, alınan belirli girişe göre çağırana bir ileti çalar.

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

Aramayı kapatma

Son olarak, çağrıyı sonlandırmamız için mantıklı bir koşul algıladığımızda, çağrıyı hangUp kapatmak için yöntemini kullanabiliriz.

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

Kodu çalıştırma

pom.xml dosyasını içeren dizine gidin ve aşağıdaki mvn komutlarını kullanın:

  • Uygulamayı derleyin: mvn compile
  • Paketi derleyin: mvn package
  • Uygulamayı yürüt: mvn exec:java

Önkoşullar

Örnek kod

GitHub'dan hızlı başlangıç örnek kodunu indirin veya kopyalayın.

Klasöre CallAutomation_OutboundCalling gidin ve çözümü bir kod düzenleyicisinde açın.

Ortamı ayarlama

Örnek kodu indirin, proje dizinine gidin ve gerekli bağımlılıkları yükleyip geliştirici ortamınızı ayarlayan komutu çalıştırın npm .

npm install

Azure DevTunnel'inizi ayarlama ve barındırma

Azure DevTunnels , İnternet'te barındırılan yerel web hizmetlerini paylaşmanızı sağlayan bir Azure hizmetidir. Yerel geliştirme ortamınızı genel İnternet'e bağlamak için DevTunnel CLI komutlarını kullanın. Bu uç noktayı, Azure İletişim Hizmetleri Çağrı Otomasyonu hizmetinden olayları çağıran uygulamanızı bilgilendirmek için kullanırız.

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

Uygulama yapılandırmanızı güncelleştirme

Ardından dosyanızı aşağıdaki değerlerle güncelleştirin .env :

  • CONNECTION_STRING: Azure İletişim Hizmetleri kaynağınızın bağlantı dizesi. buradaki yönergeleri kullanarak Azure İletişim Hizmetleri bağlantı dizesi bulabilirsiniz.
  • CALLBACK_URI: DevTunnel ana bilgisayarınız başlatıldıktan sonra bu alanı bu URI ile güncelleştirin.
  • TARGET_PHONE_NUMBER: uygulamanızın aramasını istediğiniz telefon numarasıyla alanı güncelleştirin. Bu telefon numarası E164 telefon numarası biçimini kullanmalıdır (ör. +18881234567)
  • ACS_RESOURCE_PHONE_NUMBER: bu alanı, edindiğiniz Azure İletişim Hizmetleri telefon numarasıyla güncelleştirin. Bu telefon numarası E164 telefon numarası biçimini kullanmalıdır (ör. +18881234567)
  • COGNITIVE_SERVICES_ENDPOINT: Alanını Azure AI hizmetleri uç noktanızla güncelleştirin.
  • TARGET_TEAMS_USER_ID: (İsteğe bağlı) aramasına eklemek istediğiniz Microsoft Teams kullanıcı kimliğine sahip güncelleştirme alanı. Bkz . Teams kullanıcı kimliğini almak için Graph API'sini kullanma.
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>"

Giden arama yapma ve medya yürütme

Azure İletişim Hizmetleri'dan giden arama yapmak için ortama sağladığınız telefon numarasını kullanırsınız. Telefon numarasının E164 telefon numarası biçiminde olduğundan emin olun (ör. +18881234567)

Kod, sağladığınız target_phone_number kullanarak bir giden çağrı yapar ve bu numaraya giden bir çağrı yapar:

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

(İsteğe bağlı) Aramaya Microsoft Teams kullanıcısı ekleme

özelliğiyle microsoftTeamsUserId yöntemini kullanarak addParticipant aramaya bir Microsoft Teams kullanıcısı ekleyebilirsiniz. Microsoft Teams kullanıcılarına çağrıyı etkinleştirmek için önce Azure İletişim Hizmetleri Kaynağınız için Yetkilendirme önkoşul adımını tamamlamanız gerekir. İsteğe bağlı olarak, Teams kullanıcısı için bildirim bildiriminde görüntülenen metni denetlemek için bir sourceDisplayName de geçirebilirsiniz.

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

Aramayı kaydetmeye başlama

Çağrı Otomasyonu hizmeti ayrıca sesli ve görüntülü arama kayıtlarını kaydetmeye ve depolamaya başlama olanağı sağlar. Arama Kaydı API'leri hakkında daha fazla bilgiyi burada bulabilirsiniz.

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

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

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

recordingId = response.recordingId;

Çağrı olaylarını yanıtlama

Uygulamamızın önceki bölümlerinde Çağrı Otomasyonu Hizmeti'ne kaydettik CALLBACK_URI . URI, hizmetin gerçekleşen olayları çağırmak için bizi bilgilendirmek için kullandığı uç noktayı gösterir. Ardından olaylar arasında yineleme yapabilir ve uygulamamızın anlamak istediği belirli olayları algılayabiliriz. Bildirim almak ve aşağı akış işlemlerini başlatmak için olaya yanıt CallConnected veririz. TextSourcekullanarak, karşılama iletiniz için sentezlenmesini ve kullanılmasını istediğiniz metni hizmete sağlayabilirsiniz. Azure İletişim Hizmetleri Çağrı Otomasyonu hizmeti bu iletiyi olay üzerinde oynatmaktadırCallConnected.

Ardından metni içine CallMediaRecognizeChoiceOptions geçirip çağrısı StartRecognizingAsyncyapacağız. Bu, uygulamanızın çağıranın seçtiği seçeneği tanımasını sağlar.

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

Seçim Olaylarını İşle

Azure İletişim Hizmetleri Çağrı Otomasyonu, kurulumu yaptığımız web kancasını tetikler api/callbacks ve olayı bize RecognizeCompleted bildirir. Olay, bize alınan girişlere yanıt verme ve bir eylem tetikleme olanağı sağlar. Uygulama daha sonra, alınan belirli girişe göre çağırana bir ileti çalar.

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

Aramayı kapatma

Son olarak, çağrıyı sonlandırmamız için mantıklı bir koşul algıladığımızda, çağrıyı hangUp() kapatmak için yöntemini kullanabiliriz.

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

Kodu çalıştırma

Uygulamayı çalıştırmak için bir Terminal penceresi açın ve aşağıdaki komutu çalıştırın:

  npm run dev

Önkoşullar

Örnek kod

GitHub'dan hızlı başlangıç örnek kodunu indirin veya kopyalayın.

Klasöre CallAutomation_OutboundCalling gidin ve çözümü bir kod düzenleyicisinde açın.

Python ortamını ayarlama

Python ortamını oluşturup etkinleştirin ve aşağıdaki komutu kullanarak gerekli paketleri yükleyin. Paketleri yönetme hakkında daha fazla bilgiyi burada bulabilirsiniz

pip install -r requirements.txt

Azure DevTunnel'inizi ayarlama ve barındırma

Azure DevTunnels , İnternet'te barındırılan yerel web hizmetlerini paylaşmanızı sağlayan bir Azure hizmetidir. Yerel geliştirme ortamınızı genel İnternet'e bağlamak için komutlarını kullanın. DevTunnels, kalıcı uç nokta URL'sine sahip ve anonim erişime izin veren bir tünel oluşturur. Bu uç noktayı, Azure İletişim Hizmetleri Çağrı Otomasyonu hizmetinden olayları çağıran uygulamanızı bilgilendirmek için kullanırız.

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

Uygulama yapılandırmanızı güncelleştirme

Ardından dosyanızı main.py aşağıdaki değerlerle güncelleştirin:

  • ACS_CONNECTION_STRING: Azure İletişim Hizmetleri kaynağınızın bağlantı dizesi. buradaki yönergeleri kullanarak Azure İletişim Hizmetleri bağlantı dizesi bulabilirsiniz.
  • CALLBACK_URI_HOST: DevTunnel ana bilgisayarınız başlatıldıktan sonra bu alanı bu URI ile güncelleştirin.
  • TARGET_PHONE_NUMBER: uygulamanızın aramasını istediğiniz telefon numarasıyla alanı güncelleştirin. Bu telefon numarası E164 telefon numarası biçimini kullanmalıdır (ör. +18881234567)
  • ACS_PHONE_NUMBER: bu alanı, edindiğiniz Azure İletişim Hizmetleri telefon numarasıyla güncelleştirin. Bu telefon numarası E164 telefon numarası biçimini kullanmalıdır (ör. +18881234567)
  • COGNITIVE_SERVICES_ENDPOINT: Alanını Azure AI hizmetleri uç noktanızla güncelleştirin.
  • TARGET_TEAMS_USER_ID: (İsteğe bağlı) aramasına eklemek istediğiniz Microsoft Teams kullanıcı kimliğine sahip güncelleştirme alanı. Bkz . Teams kullanıcı kimliğini almak için Graph API'sini kullanma.
# 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>"

Giden arama yapma

Azure İletişim Hizmetleri'dan giden arama yapmak için, önce aramayı almak istediğiniz telefon numarasını belirtin. Bunu basit hale getirmek için, E164 telefon numarası biçiminde bir telefon numarasıyla güncelleştirebilirsiniz target_phone_number (ör. +18881234567)

Sağladığınız target_phone_number kullanarak giden arama yapın:

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

(İsteğe bağlı) Aramaya Microsoft Teams kullanıcısı ekleme

Ve Teams kullanıcı kimliği ile yöntemini kullanarak add_participant aramaya bir MicrosoftTeamsUserIdentifier Microsoft Teams kullanıcısı ekleyebilirsiniz. Microsoft Teams kullanıcılarına çağrıyı etkinleştirmek için önce Azure İletişim Hizmetleri Kaynağınız için Yetkilendirme önkoşul adımını tamamlamanız gerekir. İsteğe bağlı olarak, Teams kullanıcısı için bildirim bildiriminde görüntülenen metni denetlemek için bir source_display_name de geçirebilirsiniz.

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

Aramayı kaydetmeye başlama

Çağrı Otomasyonu hizmeti ayrıca sesli ve görüntülü arama kayıtlarını kaydetmeye ve depolamaya başlama olanağı sağlar. Arama Kaydı API'leri hakkında daha fazla bilgiyi burada bulabilirsiniz.

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

Çağrı olaylarını yanıtlama

Uygulamamızın önceki bölümlerinde Çağrı Otomasyonu Hizmeti'ne kaydettik CALLBACK_URI_HOST . URI, hizmetin gerçekleşen olayları çağırmak için bizi bilgilendirmek için kullandığı uç noktayı gösterir. Ardından olaylar arasında yineleme yapabilir ve uygulamamızın anlamak istediği belirli olayları algılayabiliriz. Aşağıdaki kodda olayı yanıtlıyoruz 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)

Karşılama iletisini yürütme ve tanıma

TextSourcekullanarak, karşılama iletiniz için sentezlenmesini ve kullanılmasını istediğiniz metni hizmete sağlayabilirsiniz. Azure İletişim Hizmetleri Çağrı Otomasyonu hizmeti bu iletiyi olay üzerinde oynatmaktadırCallConnected.

Ardından metni içine CallMediaRecognizeChoiceOptions geçirip çağrısı StartRecognizingAsyncyapacağız. Bu, uygulamanızın çağıranın seçtiği seçeneği tanımasını sağlar.


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

Seçim Olaylarını İşle

Azure İletişim Hizmetleri Çağrı Otomasyonu, kurulumu yaptığımız web kancasını tetikler api/callbacks ve olayı bize RecognizeCompleted bildirir. Olay, bize alınan girişlere yanıt verme ve bir eylem tetikleme olanağı sağlar. Uygulama daha sonra, alınan belirli girişe göre çağırana bir ileti çalar.

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)

Aramayı kapatma

Son olarak, çağrıyı sonlandırmamız için mantıklı bir koşul algıladığımızda, çağrıyı hang_up() kapatmak için yöntemini kullanabiliriz. Son olarak, arama kayıt işlemini de güvenli bir şekilde durdurabiliriz.

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

Kodu çalıştırma

Uygulamayı VS Code ile çalıştırmak için bir Terminal penceresi açın ve aşağıdaki komutu çalıştırın

python main.py