快速入門：使用通話自動化進行向外撥打電話

發行項
07/17/2024

Azure 通訊服務通話自動化 API 是建立互動式通話體驗的強大方法。在本快速入門中，我們會討論如何向外撥打電話，並辨識通話中的各種事件。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
已部署通訊服務資源。建立通訊服務資源。
Azure 通訊服務資源中可向外撥打的電話號碼。如果您有免費的訂用帳戶，可以取得試用電話號碼。
建立及裝載 Azure Dev Tunnel。請參閱這裡的指示。
建立並將多服務 Azure AI 服務連線至您的 Azure 通訊服務資源。
為您的 Azure AI 服務資源建立自訂子網域。
(選擇性) 具有電話授權並已啟用 voice 的 Microsoft Teams 使用者。需要有 Teams 電話授權，才能將 Teams 使用者新增至通話。若想深入了解 Teams 授權，請參閱此處。若想了解如何透過 voice 啟用電話系統，請參閱此處。

範例指令碼

從 GitHub 下載或複製快速入門範例程式碼。

瀏覽至 CallAutomation_OutboundCalling 資料夾，並在程式碼編輯器中開啟解決方案。

設定及裝載您的 Azure DevTunnel

Azure DevTunnels 是一項 Azure 服務，可讓您共用裝載在網際網路上的本機 Web 服務。執行命令以將本機開發環境連線到公用網際網路。 DevTunnels 會建立持續性端點 URL，並允許匿名存取。我們會使用此端點向您的應用程式通知來自 Azure 通訊服務通話自動化服務的通話事件。

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

或者，請遵循指示在 Visual Studio 中設定 Azure DevTunnel

更新您的應用程式設定

接下來，使用下列值更新您的 Program.cs 檔案：

acsConnectionString：Azure 通訊服務資源的連接字串。您可以根據這裡的指示，找到您的 Azure 通訊服務連接字串。
callbackUriHost：在您的 DevTunnel 主機初始化之後，請使用該 URI 更新此欄位。
acsPhonenumber：將此欄位更新為您取得的 Azure 通訊服務電話號碼。此電話號碼應使用 E164 電話號碼格式 (例如 +18881234567)
targetPhonenumber：將此欄位更新為您希望應用程式撥打的電話號碼。此電話號碼應使用 E164 電話號碼格式 (例如 +18881234567)
cognitiveServiceEndpoint：將此欄位更新為您的 Azure AI 服務端點。
targetTeamsUserId：(選擇性) 更新欄位以包含您想要新增至通話的 Microsoft Teams 使用者識別碼。請參閱使用圖形 API 來取得 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>";

向外撥打電話

為了從 Azure 通訊服務向外撥打電話，此範例會使用您稍早在應用程式中定義的 targetPhonenumber 來透過 CreateCallAsync API 建立通話。此程式碼會使用目標電話號碼向外撥打電話。

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

處理呼叫自動化事件

稍早在應用程式中，我們已向通話自動化服務註冊 callbackUriHost。主機會指示服務向我們通知通話事件發生時所需的端點。接著，我們可以逐一查看事件，並偵測應用程式想要了解的特定事件。在下列程式碼中，我們會回應 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
    }
  }
});

(選擇性) 將 Microsoft Teams 使用者新增至通話

若要將 Microsoft Teams 使用者新增至通話，您可以使用 AddParticipantAsync 方法搭配 MicrosoftTeamsUserIdentifier 和 Teams 使用者識別碼。您必須完成先決條件步驟：授權 Azure 通訊服務資源以撥打給 Microsoft Teams 使用者。您也可以視需要傳入 SourceDisplayName，藉此控制 Teams 使用者快顯通知中顯示的文字。

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

開始錄製通話

通話自動化服務也可讓您開始錄製和儲存語音和視訊通話的記錄。您可以在此處深入了解通話錄製 API 的各種功能。

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

播放歡迎訊息並辨識

TextSource 可讓您在提供服務時顯示要合成及用於歡迎訊息的文字。 Azure 通訊服務通話自動化服務會在 CallConnected 事件時播放此訊息。

接下來，我們會將文字傳遞至 CallMediaRecognizeChoiceOptions，然後呼叫 StartRecognizingAsync。這可讓應用程式辨識來電者選擇的選項。

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

處理選擇事件

Azure 通訊服務呼叫自動化會觸發 api/callbacks 至我們設定的 Webhook，並向我們通知 RecognizeCompleted 事件。事件可讓我們回應收到的輸入並觸發動作。接著，應用程式會根據收到的特定輸入對來電者播放訊息。

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

掛斷並停止錄製

最後，當我們偵測到終止通話的合理條件時，我們可以使用 HangUpAsync 方法來掛斷通話。

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

若要使用 VS Code 執行應用程式，請開啟終端機視窗並執行下列命令

dotnet run

在瀏覽器中開啟 http://localhost:8080/swagger/index.html 或您的開發人員通道 URL。通道 URL 格式類似於：<YOUR DEV TUNNEL ENDPOINT>/swagger/index.html

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
已部署通訊服務資源。建立通訊服務資源。
Azure 通訊服務資源中可向外撥打的電話號碼。如果您有免費的訂用帳戶，可以取得試用電話號碼。
建立及裝載 Azure Dev Tunnel。請參閱這裡的指示。
建立並將多服務 Azure AI 服務連線至您的 Azure 通訊服務資源。
為您的 Azure AI 服務資源建立自訂子網域。
Java Development Kit (JDK) 第 11 版或更新版本。
Apache Maven。
(選擇性) 具有電話授權並已啟用 voice 的 Microsoft Teams 使用者。需要有 Teams 電話授權，才能將 Teams 使用者新增至通話。若想深入了解 Teams 授權，請參閱此處。如需在電話系統上啟用 voice 的詳細資訊，請參閱設定電話系統。

範例指令碼

從 GitHub 下載或複製快速入門範例程式碼。

瀏覽至 CallAutomation_OutboundCalling 資料夾，並在程式碼編輯器中開啟解決方案。

設定及裝載您的 Azure DevTunnel

Azure DevTunnels 是一項 Azure 服務，可讓您共用裝載在網際網路上的本機 Web 服務。執行 DevTunnel 命令，將本機開發環境連線到公用網際網路。 DevTunnels 接著會建立具有持續性端點 URL 的通道，並允許匿名存取。 Azure 通訊服務會使用此端點向您的應用程式通知來自 Azure 通訊服務通話自動化服務的通話事件。

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

更新您的應用程式設定

接著開啟 /resources 資料夾中的 application.yml 檔案以設定下列值：

connectionstring：Azure 通訊服務資源的連接字串。您可以根據這裡的指示，找到您的 Azure 通訊服務連接字串。
basecallbackuri：在您的 DevTunnel 主機初始化之後，請使用該 URI 更新此欄位。
callerphonenumber：將此欄位更新為您取得的 Azure 通訊服務電話號碼。此電話號碼應使用 E164 電話號碼格式 (例如 +18881234567)
targetphonenumber：將此欄位更新為您希望應用程式撥打的電話號碼。此電話號碼應使用 E164 電話號碼格式 (例如 +18881234567)
cognitiveServiceEndpoint：將此欄位更新為您的 Azure AI 服務端點。
targetTeamsUserId：(選擇性) 更新欄位以包含您想要新增至通話的 Microsoft Teams 使用者識別碼。請參閱使用圖形 API 來取得 Teams 使用者識別碼 (部分機器翻譯)。

acs:
  connectionstring: <YOUR ACS CONNECTION STRING> 
  basecallbackuri: <YOUR DEV TUNNEL ENDPOINT> 
  callerphonenumber: <YOUR ACS PHONE NUMBER ex. "+1425XXXAAAA"> 
  targetphonenumber: <YOUR TARGET PHONE NUMBER ex. "+1425XXXAAAA"> 
  cognitiveServiceEndpoint: <YOUR COGNITIVE SERVICE ENDPOINT>
  targetTeamsUserId: <(OPTIONAL) YOUR TARGET TEAMS USER ID ex. "00aa00aa-bb11-cc22-dd33-44ee44ee44ee">

向外撥打電話並播放媒體

為了從 Azure 通訊服務向外撥打電話，此範例會使用您在 application.yml 檔案中定義的 targetphonenumber 來透過 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);

(選擇性) 將 Microsoft Teams 使用者新增至通話

若要將 Microsoft Teams 使用者新增至通話，您可以使用 addParticipant 方法搭配 MicrosoftTeamsUserIdentifier 和 Teams 使用者識別碼。您必須完成先決條件步驟：授權 Azure 通訊服務資源以撥打給 Microsoft Teams 使用者。您也可以視需要傳入 SourceDisplayName，藉此控制 Teams 使用者快顯通知中顯示的文字。

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

開始錄製通話

通話自動化服務也可讓您開始錄製和儲存語音和視訊通話的記錄。您可以在此處深入了解通話錄製 API 的各種功能。

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

回應來電事件

稍早在應用程式中，我們已向通話自動化服務註冊 basecallbackuri。 URI 會指示服務向我們通知通話事件發生時要使用的端點。接著，我們可以逐一查看事件，並偵測應用程式想要了解的特定事件。在下列程式碼中，我們會回應 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");
    }
}

播放歡迎訊息並辨識

TextSource 可讓您在提供服務時顯示要合成及用於歡迎訊息的文字。 Azure 通訊服務通話自動化服務會在 CallConnected 事件時播放此訊息。

接下來，我們會將文字傳遞至 CallMediaRecognizeChoiceOptions，然後呼叫 StartRecognizingAsync。這可讓應用程式辨識來電者選擇的選項。

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

處理選擇事件

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

掛斷通話

最後，當我們偵測到終止通話的合理條件時，我們可以使用 hangUp 方法來掛斷通話。

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

執行程式碼

瀏覽至包含 pom.xml 檔案的目錄，並使用下列 mvn 命令：

編譯應用程式：mvn compile
建置套件：mvn package
執行應用程式：mvn exec:java

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
已部署通訊服務資源。建立通訊服務資源。
Azure 通訊服務資源中可向外撥打的電話號碼。如果您有免費的訂用帳戶，可以取得試用電話號碼。
建立及裝載 Azure Dev Tunnel。請參閱這裡的指示。
- 建立並將多服務 Azure AI 服務連線至您的 Azure 通訊服務資源。
為您的 Azure AI 服務資源建立自訂子網域。
Node.js LTS 安裝。
Visual Studio Code 已安裝。
(選擇性) 具有電話授權並已啟用 voice 的 Microsoft Teams 使用者。需要有 Teams 電話授權，才能將 Teams 使用者新增至通話。若想深入了解 Teams 授權，請參閱此處。如需在電話系統上啟用 voice 的詳細資訊，請參閱設定電話系統。

範例指令碼

從 GitHub 下載或複製快速入門範例程式碼。

瀏覽至 CallAutomation_OutboundCalling 資料夾，並在程式碼編輯器中開啟解決方案。

設定環境

下載範例程式碼並瀏覽至專案目錄，並執行 npm 命令以安裝必要的相依項目並設定您的開發人員環境。

npm install

設定及裝載您的 Azure DevTunnel

Azure DevTunnels 是一項 Azure 服務，可讓您共用裝載在網際網路上的本機 Web 服務。使用 DevTunnel CLI 命令，將本機開發環境連線到公用網際網路。我們會使用此端點向您的應用程式通知來自 Azure 通訊服務通話自動化服務的通話事件。

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

更新您的應用程式設定

接著使用下列值更新您的 .env 檔案：

CONNECTION_STRING：Azure 通訊服務資源的連接字串。您可以根據這裡的指示，找到您的 Azure 通訊服務連接字串。
CALLBACK_URI：在您的 DevTunnel 主機初始化之後，請使用該 URI 更新此欄位。
TARGET_PHONE_NUMBER：將此欄位更新為您希望應用程式撥打的電話號碼。此電話號碼應使用 E164 電話號碼格式 (例如 +18881234567)
ACS_RESOURCE_PHONE_NUMBER：將此欄位更新為您取得的 Azure 通訊服務電話號碼。此電話號碼應使用 E164 電話號碼格式 (例如 +18881234567)
COGNITIVE_SERVICES_ENDPOINT：將此欄位更新為您的 Azure AI 服務端點。
TARGET_TEAMS_USER_ID：(選擇性) 更新欄位以包含您想要新增至通話的 Microsoft Teams 使用者識別碼。請參閱使用圖形 API 來取得 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>"

向外撥打電話並播放媒體

若要從 Azure 通訊服務進行向外撥打電話，請使用您向環境提供的電話號碼。確定電話號碼為 E164 電話號碼格式 (例如 +18881234567)

程式碼會使用您提供的 target_phone_number，並向外撥打給該號碼：

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

(選擇性) 將 Microsoft Teams 使用者新增至通話

您可以使用 addParticipant 方法搭配 microsoftTeamsUserId 屬性，將 Microsoft Teams 使用者新增至通話。您必須完成先決條件步驟：授權 Azure 通訊服務資源以撥打給 Microsoft Teams 使用者。您也可以視需要傳入 sourceDisplayName，藉此控制 Teams 使用者快顯通知中顯示的文字。

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

開始錄製通話

通話自動化服務也可讓您開始錄製和儲存語音和視訊通話的記錄。您可以在此處深入了解通話錄製 API 的各種功能。

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

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

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

recordingId = response.recordingId;

回應來電事件

稍早在應用程式中，我們已向通話自動化服務註冊 CALLBACK_URI。 URI 會指示服務向我們通知通話事件發生時要使用的端點。接著，我們可以逐一查看事件，並偵測應用程式想要了解的特定事件。我們會回應 CallConnected 事件以取得通知，並開始下游作業。 TextSource 可讓您在提供服務時顯示要合成及用於歡迎訊息的文字。 Azure 通訊服務通話自動化服務會在 CallConnected 事件時播放此訊息。

接下來，我們會將文字傳遞至 CallMediaRecognizeChoiceOptions，然後呼叫 StartRecognizingAsync。這可讓應用程式辨識來電者選擇的選項。

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

處理選擇事件

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

掛斷通話

最後，當我們偵測到終止通話的合理條件時，我們可以使用 hangUp() 方法來掛斷通話。

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

執行程式碼

若要執行應用程式，請開啟終端機視窗並執行下列命令：

  npm run dev

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
已部署通訊服務資源。建立通訊服務資源。
Azure 通訊服務資源中可向外撥打的電話號碼。如果您有免費的訂用帳戶，可以取得試用電話號碼。
建立及裝載 Azure Dev Tunnel。請參閱這裡的指示。
建立並將多服務 Azure AI 服務連線至您的 Azure 通訊服務資源。
為您的 Azure AI 服務資源建立自訂子網域。
Python 3.7 以上版本。
(選擇性) 具有電話授權並已啟用 voice 的 Microsoft Teams 使用者。需要有 Teams 電話授權，才能將 Teams 使用者新增至通話。若想深入了解 Teams 授權，請參閱此處。如需在電話系統上啟用 voice 的詳細資訊，請參閱設定電話系統。

範例指令碼

從 GitHub 下載或複製快速入門範例程式碼。

瀏覽至 CallAutomation_OutboundCalling 資料夾，並在程式碼編輯器中開啟解決方案。

設定 Python 環境

使用下列命令建立並啟動 Python 環境，並安裝必要的套件。您可以從此處深入了解如何管理套件

pip install -r requirements.txt

設定及裝載您的 Azure DevTunnel

Azure DevTunnels 是一項 Azure 服務，可讓您共用裝載在網際網路上的本機 Web 服務。使用命令以將本機開發環境連線到公用網際網路。 DevTunnels 會建立具有持續性端點 URL 的通道，並允許匿名存取。我們會使用此端點向您的應用程式通知來自 Azure 通訊服務通話自動化服務的通話事件。

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

更新您的應用程式設定

接著使用下列值更新您的 main.py 檔案：

ACS_CONNECTION_STRING：Azure 通訊服務資源的連接字串。您可以根據這裡的指示，找到您的 Azure 通訊服務連接字串。
CALLBACK_URI_HOST：在您的 DevTunnel 主機初始化之後，請使用該 URI 更新此欄位。
TARGET_PHONE_NUMBER：將此欄位更新為您希望應用程式撥打的電話號碼。此電話號碼應使用 E164 電話號碼格式 (例如 +18881234567)
ACS_PHONE_NUMBER：將此欄位更新為您取得的 Azure 通訊服務電話號碼。此電話號碼應使用 E164 電話號碼格式 (例如 +18881234567)
COGNITIVE_SERVICES_ENDPOINT：將此欄位更新為您的 Azure AI 服務端點。
TARGET_TEAMS_USER_ID：(選擇性) 更新欄位以包含您想要新增至通話的 Microsoft Teams 使用者識別碼。請參閱使用圖形 API 來取得 Teams 使用者識別碼 (部分機器翻譯)。

# Your ACS resource connection string 
ACS_CONNECTION_STRING = "<ACS_CONNECTION_STRING>" 

# Your ACS resource phone number will act as source number to start outbound call 
ACS_PHONE_NUMBER = "<ACS_PHONE_NUMBER>" 

# Target phone number you want to receive the call. 
TARGET_PHONE_NUMBER = "<TARGET_PHONE_NUMBER>" 

# Callback events URI to handle callback events. 
CALLBACK_URI_HOST = "<CALLBACK_URI_HOST_WITH_PROTOCOL>" 
CALLBACK_EVENTS_URI = CALLBACK_URI_HOST + "/api/callbacks" 

#Your Cognitive service endpoint 
COGNITIVE_SERVICES_ENDPOINT = "<COGNITIVE_SERVICES_ENDPOINT>" 

#(OPTIONAL) Your target Microsoft Teams user Id ex. "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
TARGET_TEAMS_USER_ID = "<TARGET_TEAMS_USER_ID>"

向外撥打電話

若要從 Azure 通訊服務向外撥打電話，請先提供要用於接聽電話的電話號碼。為求簡單，您可以將 target_phone_number 更新為 E164 電話號碼格式的電話號碼 (例如 +18881234567)

使用您提供的 target_phone_number 向外撥打電話：

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

(選擇性) 將 Microsoft Teams 使用者新增至通話

若要將 Microsoft Teams 使用者新增至通話，您可以使用 add_participant 方法搭配 MicrosoftTeamsUserIdentifier 和 Teams 使用者識別碼。您必須完成先決條件步驟：授權 Azure 通訊服務資源以撥打給 Microsoft Teams 使用者。您也可以視需要傳入 source_display_name，藉此控制 Teams 使用者快顯通知中顯示的文字。

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

開始錄製通話

通話自動化服務也可讓您開始錄製和儲存語音和視訊通話的記錄。您可以在此處深入了解通話錄製 API 的各種功能。

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

回應來電事件

稍早在應用程式中，我們已向通話自動化服務註冊 CALLBACK_URI_HOST。 URI 會指示服務向我們通知通話事件發生時要使用的端點。接著，我們可以逐一查看事件，並偵測應用程式想要了解的特定事件。在下列程式碼中，我們會回應 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)

播放歡迎訊息並辨識

TextSource 可讓您在提供服務時顯示要合成及用於歡迎訊息的文字。 Azure 通訊服務通話自動化服務會在 CallConnected 事件時播放此訊息。

接下來，我們會將文字傳遞至 CallMediaRecognizeChoiceOptions，然後呼叫 StartRecognizingAsync。這可讓應用程式辨識來電者選擇的選項。


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

處理選擇事件

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)

掛斷通話

最後，當我們偵測到終止通話的合理條件時，我們可以使用 hang_up() 方法來掛斷通話。最後，我們也可以安全地停止通話錄製作業。

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

執行程式碼

Visual Studio Code
Visual Studio

若要使用 VS Code 執行應用程式，請開啟終端機視窗並執行下列命令

python main.py

共用方式為

快速入門：使用通話自動化進行向外撥打電話

必要條件

範例指令碼

設定及裝載您的 Azure DevTunnel

更新您的應用程式設定

向外撥打電話

處理呼叫自動化事件

(選擇性) 將 Microsoft Teams 使用者新增至通話

開始錄製通話

播放歡迎訊息並辨識

處理選擇事件

掛斷並停止錄製

執行程式碼

必要條件

範例指令碼

設定及裝載您的 Azure DevTunnel

更新您的應用程式設定

向外撥打電話並播放媒體

(選擇性) 將 Microsoft Teams 使用者新增至通話

開始錄製通話

回應來電事件

播放歡迎訊息並辨識

處理選擇事件

掛斷通話

執行程式碼

必要條件

範例指令碼

設定環境

設定及裝載您的 Azure DevTunnel

更新您的應用程式設定

向外撥打電話並播放媒體

(選擇性) 將 Microsoft Teams 使用者新增至通話

開始錄製通話

回應來電事件

處理選擇事件

掛斷通話

執行程式碼

必要條件

範例指令碼

設定 Python 環境

設定及裝載您的 Azure DevTunnel

更新您的應用程式設定

向外撥打電話

(選擇性) 將 Microsoft Teams 使用者新增至通話

開始錄製通話

回應來電事件

播放歡迎訊息並辨識

處理選擇事件

掛斷通話

執行程式碼

意見反應

其他資源