本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon Chime SDK PSTN 音訊服務
**注意**
本節說明 Chime SDK PSTN 音訊服務，先前在舊版文件和一些部落格文章中稱為「SIP 媒體應用程式 (SMA)」。接下來，當我們參考「SIP 媒體應用程式」時，我們指的是 Amazon Chime SDK 主控台中的組態項目，以及與 PSTN 音訊服務相關聯的 AWS SDK。
本節說明如何使用 Amazon Chime SDK 公有切換電話網路 (PSTN) 音訊服務。透過 PSTN 音訊服務，開發人員可以使用無伺服器 AWS Lambda 函數的敏捷性和操作簡單性來建置自訂電話應用程式。
您的 AWS Lambda 函數會控制通話的行為，例如播放語音提示、收集數字、記錄通話、使用 Amazon Chime SDK Voice Connector 將通話轉接至 PSTN 和工作階段起始通訊協定 (SIP) 裝置。下列主題提供 PSTN 音訊服務的概觀和架構資訊，包括如何建置 AWS Lambda 函數來控制呼叫。
**注意**
本節中的主題假設您了解 AWS Lambda 服務。如需 的詳細資訊 AWS Lambda，請參閱 [入門 AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html)。此外，若要成功使用 Amazon Chime SDK 的本節，Amazon Chime SDK 管理員必須至少建立一個 SIP 規則和一個 SIP 媒體應用程式。如需完成這些任務的詳細資訊，請參閱《*Amazon Chime SDK 管理員指南*》中的[管理 SIP 媒體應用程式](https://docs.aws.amazon.com/chime-sdk/latest/ag/manage-sip-applications.html)。
**Topics**
+ [遷移至 Amazon Chime SDK 語音命名空間](voice-namespace-migration.md)
+ [了解 Amazon Chime SDK PSTN 音訊的電話號碼、SIP 規則、SIP 媒體應用程式和 AWS Lambda 函數](using-lambda.md)
+ [了解 Amazon Chime SDK PSTN 音訊服務程式設計模型](pstn-model.md)
+ [將呼叫和事件路由到 Amazon Chime SDK PSTN 音訊的 AWS Lambda 函數](route-calls-events.md)
+ [將呼叫路由到 Amazon Chime SDK PSTN 音訊的 AWS Lambda 函數 (AWS CLI)](route-calls-events-cli.md)
+ [了解如何使用 Amazon Chime SDK PSTN 音訊服務通話端](call-architecture.md)
+ [了解 Amazon Chime SDK PSTN 音訊的通話流程](call-flow.md)
+ [為 Amazon Chime SDK PSTN 音訊服務建置 AWS Lambda 函數](writing-lambdas.md)
# 遷移至 Amazon Chime SDK 語音命名空間
[Amazon Chime SDK Voice](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 命名空間是 API 的專用空間 APIs ，可建立和管理 Amazon Chime SDK 語音資源。您可以使用 命名空間來處理任何 AWS 區域中的 Amazon Chime SDK 語音 API 端點，這些端點可供他們使用。如果您剛開始使用 Amazon Chime SDK，請使用此命名空間。如需區域的詳細資訊，請參閱本指南[Amazon Chime SDK 的可用 AWS 區域](sdk-available-regions.md)中的 。
使用 [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間的現有應用程式應計劃遷移到專用命名空間，以便使用更新的 APIs和新功能。
**Topics**
+ [遷移的原因](#first-concept-chapter)
+ [遷移之前](#voice-before-migrate)
+ [命名空間之間的差異](#voice-namespace-diffs)
## 遷移的原因
基於下列原因，我們建議您遷移至 [Amazon Chime SDK Voice](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 命名空間：
**API 端點的選擇**
Amazon Chime SDK Voice 命名空間可讓您在任何[區域中使用 API 端點，使其可供使用](https://docs.aws.amazon.com/chime-sdk/latest/dg/sdk-available-regions.html)。如果您想要使用 以外的 API 端點`us-east-1`，則必須使用 Amazon Chime SDK Voice 命名空間。如需目前端點的詳細資訊，請參閱本指南[API 映射](migrate-from-chm-namespace.md#name-end-map)中的 。
**已更新和新的語音 APIs**
我們只在 Amazon Chime SDK Voice APIs。
## 遷移之前
遷移之前，請注意命名空間之間的差異。下表列出並說明它們。
| | Amazon Chime SDK 語音命名空間 | Amazon Chime 命名空間 |
| --- | --- | --- |
| **AWS 命名空間** | `ChimeSDKVoice` | `Chime` |
| **區域** | 多個 | 僅限 `us-east-1` |
| **端點** | `https://voice-chime.region.amazonaws.com` | `service.chime.aws.amazon.com` |
| **服務主體** | `chime.amazonaws.com` | `chime.amazonaws.com` |
| **API** | 只有 PSTN 音訊服務的 APIs | PSTN 音訊和 Amazon Chime 其他部分的 APIs |
| Voice Connector 管理 | 多個區域 | us-east-1 |
| Voice Connector 群組管理 | 多個區域 | us-east-1 |
| SIP 媒體應用程式和 SIP 規則管理 | 多個區域 | us-east-1 |
| 電話號碼管理 | 多個區域 | us-east-1 |
| 呼叫分析 | 可用性 | 無 |
| 語音設定檔網域 | 可用性 | 無 |
| 緊急呼叫管理 | 多個區域 | us-east-1 |
| Proxy 電話工作階段管理 | 多個區域 | us-east-1 |
| 串流管理 | 多個區域 | us-east-1 |
| 記錄和指標管理 | 多個區域 | us-east-1 |
如需可用區域的詳細資訊，請參閱[語音區域](sdk-available-regions.md#voice-regions)。
## 命名空間之間的差異
下列各節說明 `Amazon Chime SDK Voice`和 `Amazon Chime`命名空間之間的差異。
**AWS 命名空間**
Amazon Chime SDK 命名空間使用`Chime`正式名稱。Amazon Chime SDK Voice 命名空間使用`ChimeSDKVoice`正式名稱。名稱的精確格式因平台而異。
例如，如果您使用 Node.js 中的 AWS SDK 來建立會議，您可以使用下列程式碼行來解決命名空間。
```
const chimeVoice = AWS.Chime();
```
若要遷移至 Amazon Chime SDK Voice 命名空間，請使用新的命名空間和端點區域更新這行程式碼。
```
const chimeVoice = AWS.ChimeSDKVoice({ region: "eu-central-1" });
```
**區域**
[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間只能處理`us-east-1`區域中的 API 端點。[Amazon Chime SDK Voice](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) 命名空間可以解決任何可用區域中的 Amazon Chime SDK 語音 API 端點。如需語音區域的最新清單，請參閱本指南[Amazon Chime SDK 的可用 AWS 區域](sdk-available-regions.md)中的 。
**端點**
[Amazon Chime SDK Voice](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 命名空間使用與 [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間不同的 API 端點。
只有用來建立語音動作的端點才能用來修改它。這表示透過 中的端點建立的語音動作`eu-central-1`只能透過 修改`eu-central-1`。這也表示您無法處理透過 `Chime` 命名空間建立的語音動作，其`ChimeSDKVoice`命名空間位於 中`us-east-1`。如需目前端點的詳細資訊，請參閱本指南[API 映射](migrate-from-chm-namespace.md#name-end-map)中的 。
**服務主體**
這兩個命名空間都使用 `chime.amazonaws.com`服務主體。如果您有授予服務存取權的存取政策，則不需要更新這些政策。
**API**
[Amazon Chime SDK Voice](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 命名空間僅包含 APIs以建立和管理語音動作。[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間包含語音 APIs 和 Amazon Chime 服務的其他部分，例如會議。
**標記**
只有 [Amazon Chime SDK Voice](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 命名空間支援標籤。如需標籤的詳細資訊，請參閱 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_TagResource.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_TagResource.html)和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UntagResource.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UntagResource.html)。
**媒體區域**
如果您使用 `Chime` 命名空間來建立語音連接器和 SIP 媒體應用程式等資源，您只能在 `us-east-1`和 中執行此操作`us-west-2`，而且您必須使用`us-east-1`端點。
相反地，`ChimeSDKVoice`命名空間允許在所有支援的區域中建立資源，而不只是 `us-east-1`和 `us-west-2`。如需區域涵蓋範圍的詳細資訊，請參閱[Amazon Chime SDK 的可用 AWS 區域](sdk-available-regions.md)。
# 了解 Amazon Chime SDK PSTN 音訊的電話號碼、SIP 規則、SIP 媒體應用程式和 AWS Lambda 函數
Amazon Chime SDK 管理員必須先佈建電話號碼，並建立稱為 SIP 規則和 SIP 媒體應用程式的受管物件，才能使用 PSTN 音訊服務。您可以使用 Amazon Chime SDK 主控台或 AWS SDK 佈建電話號碼，以及佈建 SIP 規則和 SIP 媒體應用程式受管物件。
此影像顯示組成 PSTN 音訊服務的受管物件之間的關係。影像中的數字對應至影像下方文字中的數字。
![\[Amazon Chime SDK PSTN 音訊服務中的受管物件。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/pstn-diagram2.png)
您只能將電話號碼和 Amazon Chime SDK Voice Connectors (1) 指派給 SIP 規則 (2)。此外，您必須在 PSTN 音訊服務中佈建電話號碼或語音連接器。收到電話號碼的撥入通話或從語音連接器發出的撥出通話請求時，SIP 規則會叫用 SIP 媒體應用程式和相關聯的 AWS Lambda 函數 (4)。 AWS Lambda 函數會執行一組預先定義的動作，例如播放保留音樂或參加會議。為了提供多區域彈性，SIP 規則可以根據容錯移轉的優先順序，在不同 AWS 區域 (3) 中指定替代目標 SIP 媒體應用程式。如果一個目標失敗，PSTN 音訊服務會嘗試下一個目標，依此類推。請注意，每個替代目標必須位於不同的 AWS 區域。
此外，多個 SIP 媒體應用程式可以叫用指定的 AWS Lambda 函數。另一種方式是，當您建立 AWS Lambda 函數時，任何 SIP 媒體應用程式都可以使用該函數。
如需佈建 SIP 媒體應用程式和規則的詳細資訊，請參閱《*Amazon Chime SDK 管理員指南*》中的[管理 SIP 媒體應用程式和規則](https://docs.aws.amazon.com/chime-sdk/latest/ag/manage-sip-applications.html)。
# 了解 Amazon Chime SDK PSTN 音訊服務程式設計模型
PSTN 音訊服務使用請求/回應程式設計模型，進而使用 AWS Lambda 函數。系統會自動調用您的 AWS Lambda 函數以進行傳入和傳出呼叫。例如，當新的來電送達時，PSTN 音訊服務會使用`NEW_INCOMING_CALL`事件叫用您的 AWS Lambda 函數，並等待稱為*動作*的命令。例如，您的應用程式可以選擇播放音訊提示、收集數字、錄製音訊或轉接通話等動作。這些 JSON 格式動作會使用函數的回呼傳回 PSTN 音訊服務 AWS Lambda 。
此範例顯示`PlayAudio`動作。
```
{
"Type": "PlayAudio",
"Parameters": {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"PlaybackTerminators": ["1", "8", "#"],
"Repeat": "5",
"AudioSource": {
"Type": "S3",
"BucketName": "valid-S3-bucket-name",
"Key": "wave-file.wav"
}
}
}
```
此範例顯示`RecordAudio`動作。
```
{
"Type": "RecordAudio",
"Parameters": {
"CallId": "call-id-1",
"DurationInSeconds": "10",
"SilenceDurationInSeconds": 3,
"SilenceThreshold": 100,
"RecordingTerminators": [
"#"
],
"RecordingDestination": {
"Type": "S3",
"BucketName": "valid-bucket-name",
"Prefix": "valid-prefix-name"
}
}
}
```
一旦 PSTN 音訊服務執行動作，它會再次調用您的 AWS Lambda 函數，並顯示成功或失敗。
您的應用程式也可以撥打外撥電話，並使用您的 AWS Lambda 函數來控制通話流程、來電者體驗和通話內容。在這種情況下，您可以呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html) API，並使用`NEW_OUTBOUND_CALL`事件 AWS Lambda 叫用您的 。接聽通話後，您可以傳回動作，例如播放語音提示和收集使用者輸入的數字。您也可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 來觸發 AWS Lambda 函數，以實作計時器、參與者靜音和等候室。
# 將呼叫和事件路由到 Amazon Chime SDK PSTN 音訊的 AWS Lambda 函數
PSTN 音訊服務提供下列方式，將來電路由到您的 AWS Lambda 函數以進行處理。
+ 您可以根據呼叫的號碼路由呼叫。若要這樣做，Amazon Chime SDK 管理員會建立 SIP 規則，並將**觸發類型**設定為**收件人電話號碼**。此電話號碼必須存在於與 SIP 規則相同的 AWS 帳戶中的 Amazon Chime SDK 電話號碼庫存中。
+ 您可以根據傳入語音連接器 SIP 呼叫的請求 URI，將呼叫路由到 AWS Lambda 函數。若要這樣做，Amazon Chime SDK 管理員會建立**觸發類型**設定為**請求 URI 主機名稱**的 SIP 規則。此欄位必須包含 Voice Connector 的「傳出主機名稱」欄位中指定的完整網域名稱，該語音連接器是在與 SIP 規則相同的 AWS 帳戶中佈建。
**注意**
使用**請求 URI 主機名稱**觸發類型時，PSTN 音訊服務會驗證傳入`user`的部分 `Request-URI`(`@`簽署前的部分）。您必須使用[增強的 Backus-Naur 格式](https://datatracker.ietf.org/doc/html/rfc2234)。必要長度：介於 1 到 36 之間，包含 。使用下列值： `a-z, A-Z, 0-9, &, =, +, $, /, %, -, _, !, ~, *, `(`,`)、 (`.`)。如果您的 SIP 供應商需要傳遞較長的值，請改用自訂 SIP 標頭。如需詳細資訊，請參閱[在 Amazon Chime SDK PTSN 音訊服務中使用 SIP 標頭](sip-headers.md)。
接下來，管理員會佈建至少一個目標 SIP 媒體應用程式。或者，您可以依優先順序佈建多個 SIP 媒體應用程式，以支援備援和容錯移轉。例如，您可以在兩個不同的 AWS 區域中佈建兩個 SIP 媒體應用程式，並指定其優先順序。如果 SIP 規則具有多個目標 SIP 媒體應用程式，則 SIP 媒體應用程式的 Lambda 函數會依優先順序叫用。SIP 媒體應用程式中優先順序最高的 AWS Lambda 函數 （最小數字，例如 1) 會先執行。如果 PSTN 音訊服務無法叫用該 AWS Lambda 函數，則會叫用 SIP 媒體應用程式中具有下一個最高優先順序 （下一個最小數字，例如 2) 的 AWS Lambda 函數。如果所有嘗試執行 SIP 規則中指定的 SIP 媒體應用程式都失敗，PSTN 音訊服務會掛斷。
佈建必要的 SIP 規則和 SIP 媒體應用程式後，PSTN 音訊服務會將來電路由到您的 AWS Lambda 函數。下圖顯示使用**收件人電話號碼**觸發類型的典型序列。
![\[使用收件人電話號碼觸發類型的 SIP 規則和 SIP 媒體應用程式工作流程規則圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/SMA Images-CS-2021-05-05-SIP Rules-PSTN-W-Lambda.png)
在圖表中：
1. PSTN 音訊服務會收到對相同 AWS 帳戶中 SIP 規則佈建之電話號碼的來電。
1. 然後，PSTN 音訊服務會評估 SIP 規則，並擷取優先順序最高的 SIP 媒體應用程式 （在此情況下為優先順序 1)。
1. 然後，服務會叫用與 SIP 媒體應用程式相關聯的 AWS Lambda 函數。
1. 選用。如果服務無法叫用 AWS Lambda 與最高優先順序相關聯的 ，則會嘗試以下一個最高優先順序 （在此情況下為優先順序 2) 執行 SIP 媒體應用程式，如果有的話。
1. 選用。如果所有目標 SIP 媒體應用程式都失敗，PSTN 音訊服務會掛斷通話。
下圖顯示使用**請求 URI 主機名稱**觸發類型的典型規則。
![\[使用請求 URI 主機名稱觸發類型的規則圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/SMA Images-CS-2021-05-05-SIP Rules-VC-W-Lambda.png)
在圖表中：
1. PSTN 音訊服務會在 Amazon Chime SDK Voice Connector 上接收來電，其**請求 URI 主機名稱**符合相同 AWS 帳戶中佈建的 SIP 規則。
1. 服務接著會評估 SIP 規則，並擷取優先順序最低的 SIP 媒體應用程式 （在此情況下，是唯一優先順序為 1 的目標 SIP 媒體應用程式）。
1. 然後，服務會叫用與 SIP 媒體應用程式相關聯的 AWS Lambda 函數。
1. 選用。如果服務無法叫用 AWS Lambda 與最低優先順序相關聯的 ，則會嘗試以下一個最低優先順序執行 SIP 媒體應用程式，如果有的話。在此情況下，只有一個目標 SIP 媒體應用程式。
1. 選用。如果所有目標 SIP 媒體應用程式都失敗，PSTN 音訊服務會掛斷通話。
此外，您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html) API 建立外撥呼叫，然後調用您的 AWS Lambda 函數以進行其他處理。若要使用此 API，您可以將佈建的 **SIP 媒體應用程式 ID** 指定為參數。
最後，當呼叫處於作用中狀態時，您可以隨時使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 觸發 AWS Lambda 函數。若要使用 API，您可以將佈建的 **SIP 媒體應用程式 ID** 指定為參數。
# 將呼叫路由到 Amazon Chime SDK PSTN 音訊的 AWS Lambda 函數 (AWS CLI)
本教學課程會引導您使用 Amazon Chime SDK PSTN 音訊服務設定 Lambda 函數的呼叫路由。您將了解如何建立 Lambda 函數、設定 SIP 媒體應用程式，以及設定 SIP 規則來處理來電。
## 先決條件
開始本教學課程之前，請務必執行下列動作：
+ 安裝 AWS CLI。如需詳細資訊，請參閱 *AWS CLI User Guide* 中的 [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
+ AWS CLI 使用適當的登入資料設定您的 。若尚未設定憑證，請執行 `aws configure`。
+ 基本熟悉 AWS Lambda 和 Amazon Chime SDK 概念。
+ 設定足夠的許可，以在您的 AWS 帳戶中建立和管理 Amazon Chime SDK 和 Lambda 資源。
+ 對於以電話號碼為基礎的轉接，您需要在 Amazon Chime SDK 電話號碼庫存中擁有電話號碼。
+ 對於語音連接器型路由，您需要在帳戶中設定語音連接器。
## 成本考量
本教學課程包含清除說明，以確保您在完成後不會持續產生費用。如需詳細資訊，請參閱 [Amazon Chime SDK 定價](https://aws.amazon.com/chime/chime-sdk/pricing/)。
讓我們開始設定 Amazon Chime SDK PSTN 音訊的通話路由。
## 搜尋和佈建電話號碼
使用電話號碼觸發條件建立 SIP 規則之前，您需要在 Amazon Chime SDK 庫存中擁有電話號碼。以下是如何搜尋可用的電話號碼並進行佈建的方法。
**Example ：搜尋可用的電話號碼**
```
# Search for available toll-free phone numbers
aws chime-sdk-voice search-available-phone-numbers \
--phone-number-type TollFree \
--country US \
--toll-free-prefix 844 \
--max-results 5 \
--region us-east-1
```
此命令會搜尋美國字首為 844 的可用免付費電話號碼。您可以修改參數來搜尋不同類型的數字。
**Example ：佈建電話號碼**
找到可用的電話號碼後，您可以使用下列命令進行佈建：
```
# Order a phone number
aws chime-sdk-voice create-phone-number-order \
--product-type SipMediaApplicationDialIn \
--e164-phone-numbers "+18445550100" \
--region us-east-1
```
`+18445550100` 將 取代為搜尋結果中實際可用的電話號碼。此命令會將電話號碼佈建至您的帳戶。
**Example ：檢查電話號碼狀態**
訂購電話號碼之後，您可以檢查其狀態：
```
# Get the phone number order status
aws chime-sdk-voice get-phone-number-order \
--phone-number-order-id abcd1234-5678-90ab-cdef-EXAMPLE55555 \
--region us-east-1
```
將訂單 ID 取代為從`create-phone-number-order`命令傳回的訂單 ID。
**Example ：列出庫存中的電話號碼**
若要查看庫存中的所有電話號碼：
```
# List all phone numbers
aws chime-sdk-voice list-phone-numbers \
--region us-east-1
```
若要尋找可用於 SIP 規則的未指派電話號碼：
```
# List unassigned phone numbers
aws chime-sdk-voice list-phone-numbers \
--region us-east-1 \
--query "PhoneNumbers[?Status=='Unassigned'].E164PhoneNumber"
```
## 建立用於呼叫處理的 Lambda 函數
現在，讓我們建立一個 Lambda 函數來處理來電。函數會從 PSTN 音訊服務接收事件，並回應如何處理呼叫的指示。
**Example ：建立 Lambda 的 IAM 角色**
在建立 Lambda 函數之前，您需要建立授予必要許可的 IAM 角色。
```
cat > lambda-trust-policy.json << EOF
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
EOF
```
```
aws iam create-role --role-name ChimeSDKLambdaRole \
--assume-role-policy-document file://lambda-trust-policy.json
```
```
aws iam attach-role-policy --role-name ChimeSDKLambdaRole \
--policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
```
這些命令會建立 IAM 角色，允許 Lambda 擔任該角色並連接基本執行政策，以提供 Lambda 將日誌寫入 CloudWatch 的許可。
**Example 建立 Lambda 函數。**
現在，建立一個簡單的 Lambda 函數來處理來電。
```
mkdir -p lambda
cat > lambda/index.js << EOF
exports.handler = async (event) => {
console.log('Received event:', JSON.stringify(event, null, 2));
// Simple call handling logic
const response = {
SchemaVersion: '1.0',
Actions: [
{
Type: 'Speak',
Parameters: {
Engine: 'neural',
Text: 'Hello! This is a test call from Amazon Chime SDK PSTN Audio.',
VoiceId: 'Joanna'
}
},
{
Type: 'Hangup',
Parameters: {
SipResponseCode: '200'
}
}
]
};
return response;
};
EOF
```
```
cd lambda
zip -r function.zip index.js
cd ..
```
```
# Get your AWS account ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
aws lambda create-function \
--function-name ChimeSDKCallHandler \
--runtime nodejs18.x \
--role arn:aws:iam::${ACCOUNT_ID}:role/ChimeSDKLambdaRole \
--handler index.handler \
--zip-file fileb://lambda/function.zip
```
此 Lambda 函數會使用語音訊息回應來電，然後掛斷。
**Example ：新增 Amazon Chime SDK 的 Lambda 許可**
將叫用 Lambda 函數的許可授予 Amazon Chime SDK 服務。
```
# Get your AWS account ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
aws lambda add-permission \
--function-name ChimeSDKCallHandler \
--statement-id ChimeSDK \
--action lambda:InvokeFunction \
--principal voiceconnector.chime.amazonaws.com \
--source-account ${ACCOUNT_ID}
```
此命令允許 Amazon Chime SDK Voice Connector 服務調用 Lambda 函數。
## 建立 SIP 媒體應用程式
SIP 媒體應用程式會將 Lambda 函數連線至 PSTN 音訊服務。在本節中，您將建立使用 Lambda 函數的 SIP 媒體應用程式。
**Example ：建立 SIP 媒體應用程式**
```
# Get your Lambda function ARN
LAMBDA_ARN=$(aws lambda get-function --function-name ChimeSDKCallHandler --query Configuration.FunctionArn --output text)
aws chime-sdk-voice create-sip-media-application \
--aws-region us-east-1 \
--name "MyCallHandlerApp" \
--endpoints "[{\"LambdaArn\":\"${LAMBDA_ARN}\"}]"
```
SIP 媒體應用程式可做為 PSTN 音訊服務與 Lambda 函數之間的橋樑。
**Example ：取得 SIP 媒體應用程式 ID**
建立 SIP 媒體應用程式之後，您需要擷取其 ID 以供教學課程稍後使用。
```
SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
--query "SipMediaApplications[?Name=='MyCallHandlerApp'].SipMediaApplicationId" \
--output text)
echo "SIP Media Application ID: ${SIP_MEDIA_APP_ID}"
```
請記下此命令傳回的 SIP 媒體應用程式 ID，因為在建立 SIP 規則時需要它。
## 使用 SIP 規則設定通話轉接
SIP 規則決定如何將來電路由到您的 SIP 媒體應用程式。您可以根據電話號碼或 Voice Connector 主機名稱建立規則。
**Example ：使用電話號碼觸發條件建立 SIP 規則**
若要根據電話號碼路由通話，請使用下列命令：
```
# Get an unassigned phone number from your inventory
PHONE_NUMBER=$(aws chime-sdk-voice list-phone-numbers \
--query "PhoneNumbers[?Status=='Unassigned'].E164PhoneNumber | [0]" \
--output text)
# If no unassigned phone number is found, you'll need to provision one
if [ -z "$PHONE_NUMBER" ] || [ "$PHONE_NUMBER" == "None" ]; then
echo "No unassigned phone numbers found. Please provision a phone number first."
exit 1
fi
echo "Using phone number: ${PHONE_NUMBER}"
aws chime-sdk-voice create-sip-rule \
--name "IncomingCallRule" \
--trigger-type ToPhoneNumber \
--trigger-value "${PHONE_NUMBER}" \
--target-applications "[{\"SipMediaApplicationId\":\"${SIP_MEDIA_APP_ID}\",\"Priority\":1}]"
```
此命令會建立 SIP 規則，將對電話號碼的呼叫路由到您的 SIP 媒體應用程式。
**Example ：使用請求 URI 主機名稱觸發條件建立 SIP 規則**
或者，您可以根據傳入語音連接器 SIP 呼叫的請求 URI 路由呼叫：
```
# Replace with your Voice Connector hostname
VOICE_CONNECTOR_HOST="example.voiceconnector.chime.aws"
aws chime-sdk-voice create-sip-rule \
--name "VoiceConnectorRule" \
--trigger-type RequestUriHostname \
--trigger-value "${VOICE_CONNECTOR_HOST}" \
--target-applications "[{\"SipMediaApplicationId\":\"${SIP_MEDIA_APP_ID}\",\"Priority\":1}]"
```
將主機名稱取代為您 Voice Connector 的傳出主機名稱。
## 使用多個 SIP 媒體應用程式設定備援
對於備援和容錯移轉，您可以在相同的 AWS 區域中建立多個 SIP 媒體應用程式，並指定其優先順序。
**Example ：建立備份 Lambda 函數**
首先，在相同區域中建立備份 Lambda 函數。
```
cat > lambda/backup-index.js >< EOF
exports.handler = async (event) => {
console.log('Received event in backup handler:', JSON.stringify(event, null, 2));
// Simple call handling logic for backup
const response = {
SchemaVersion: '1.0',
Actions: [
{
Type: 'Speak',
Parameters: {
Engine: 'neural',
Text: 'Hello! This is the backup handler for Amazon Chime SDK PSTN Audio.',
VoiceId: 'Matthew'
}
},
{
Type: 'Hangup',
Parameters: {
SipResponseCode: '200'
}
}
]
};
return response;
};
EOF
```
```
cd lambda
zip -r backup-function.zip backup-index.js
cd ..
```
```
# Get your AWS account ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
aws lambda create-function \
--function-name ChimeSDKBackupHandler \
--runtime nodejs18.x \
--role arn:aws:iam::${ACCOUNT_ID}:role/ChimeSDKLambdaRole \
--handler backup-index.handler \
--zip-file fileb://lambda/backup-function.zip
```
**Example ：將 Amazon Chime SDK 的 Lambda 許可新增至備份函數**
```
# Get your AWS account ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
aws lambda add-permission \
--function-name ChimeSDKBackupHandler \
--statement-id ChimeSDK \
--action lambda:InvokeFunction \
--principal voiceconnector.chime.amazonaws.com \
--source-account ${ACCOUNT_ID}
```
**Example ：建立備份 SIP 媒體應用程式**
```
# Get your backup Lambda function ARN
BACKUP_LAMBDA_ARN=$(aws lambda get-function --function-name ChimeSDKBackupHandler --query Configuration.FunctionArn --output text)
aws chime-sdk-voice create-sip-media-application \
--aws-region us-east-1 \
--name "BackupCallHandlerApp" \
--endpoints "[{\"LambdaArn\":\"${BACKUP_LAMBDA_ARN}\"}]"
# Get the backup SIP media application ID
BACKUP_SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
--query "SipMediaApplications[?Name=='BackupCallHandlerApp'].SipMediaApplicationId" \
--output text)
```
**Example ：取得 SIP 規則 ID**
```
SIP_RULE_ID=$(aws chime-sdk-voice list-sip-rules \
--query "SipRules[?Name=='IncomingCallRule'].SipRuleId" \
--output text)
```
**Example ：更新 SIP 規則以包含具有優先順序的兩個應用程式**
```
aws chime-sdk-voice update-sip-rule \
--sip-rule-id ${SIP_RULE_ID} \
--target-applications "[{\"SipMediaApplicationId\":\"${SIP_MEDIA_APP_ID}\",\"Priority\":1},{\"SipMediaApplicationId\":\"${BACKUP_SIP_MEDIA_APP_ID}\",\"Priority\":2}]"
```
此命令會更新 SIP 規則，以將主要和備份 SIP 媒體應用程式包含各自的優先順序。
## 建立外撥通話
您也可以使用 `CreateSIPMediaApplicationCall` API 建立叫用 Lambda 函數的傳出呼叫。
```
# Use a phone number from your inventory for outbound calling
FROM_PHONE_NUMBER=${PHONE_NUMBER}
TO_PHONE_NUMBER="+12065550102" # Replace with a valid destination number
aws chime-sdk-voice create-sip-media-application-call \
--from-phone-number "${FROM_PHONE_NUMBER}" \
--to-phone-number "${TO_PHONE_NUMBER}" \
--sip-media-application-id ${SIP_MEDIA_APP_ID}
```
以有效的號碼取代目的地電話號碼。您需要有庫存中的電話號碼才能進行實際呼叫。
## 在作用中呼叫期間觸發 Lambda
您可以使用 `UpdateSIPMediaApplicationCall` API 在作用中呼叫期間觸發 Lambda 函數。
```
# Replace with an actual transaction ID from an active call
TRANSACTION_ID="txn-3ac9de3f-6b5a-4be9-9e7e-EXAMPLE33333"
aws chime-sdk-voice update-sip-media-application-call \
--sip-media-application-id ${SIP_MEDIA_APP_ID} \
--transaction-id ${TRANSACTION_ID} \
--arguments '{"action":"custom-action"}'
```
通話作用中時，傳送至 Lambda 函數的事件資料會提供交易 ID。
## 清除資源
完成本教學課程後，您應該刪除您建立的資源，以避免產生額外費用。
**Example ：刪除 SIP 規則**
```
# Get the SIP rule ID if you don't have it
SIP_RULE_ID=$(aws chime-sdk-voice list-sip-rules \
--query "SipRules[?Name=='IncomingCallRule'].SipRuleId" \
--output text)
aws chime-sdk-voice delete-sip-rule --sip-rule-id ${SIP_RULE_ID}
```
**Example ：刪除 SIP 媒體應用程式**
```
# Get SIP media application IDs if you don't have them
SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
--query "SipMediaApplications[?Name=='MyCallHandlerApp'].SipMediaApplicationId" \
--output text)
BACKUP_SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
--query "SipMediaApplications[?Name=='BackupCallHandlerApp'].SipMediaApplicationId" \
--output text)
aws chime-sdk-voice delete-sip-media-application --sip-media-application-id ${SIP_MEDIA_APP_ID}
aws chime-sdk-voice delete-sip-media-application --sip-media-application-id ${BACKUP_SIP_MEDIA_APP_ID}
```
**Example ：刪除 Lambda 函數**
```
aws lambda delete-function --function-name ChimeSDKCallHandler
aws lambda delete-function --function-name ChimeSDKBackupHandler
```
**Example ：刪除 IAM 角色**
```
aws iam detach-role-policy --role-name ChimeSDKLambdaRole \
--policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
aws iam delete-role --role-name ChimeSDKLambdaRole
```
**Example ：釋出電話號碼**
如果您不再需要電話號碼，您可以釋出它們：
```
# List phone numbers
aws chime-sdk-voice list-phone-numbers
# Delete a specific phone number
aws chime-sdk-voice delete-phone-number --phone-number-id ${PHONE_NUMBER}
```
請注意，電話號碼會輸入「ReleaseInProgress」狀態 7 天，之後才會完全釋出。在此期間，您可以視需要使用 `restore-phone-number`命令來還原它們。
## 生產環境部署須知
本教學課程示範使用 Amazon Chime SDK PSTN 音訊將呼叫路由到 Lambda 函數的基本功能。不過，對於生產環境，您應該考慮下列最佳實務：
### 安全考量
+ 實作最低權限許可。建立自訂 IAM 政策，僅授予 Lambda 函數所需的特定許可。
+ 將來源 ARN 條件新增至 Lambda 許可。限制哪些 SIP 媒體應用程式可以叫用 Lambda 函數。
+ 實作輸入驗證。將驗證新增至 Lambda 函數，以確保它們只處理有效的事件。
+ 考慮 VPC 部署。為了增強安全性，請使用適當的安全群組在 VPC 中部署 Lambda 函數。
+ 加密敏感資料。使用 AWS Key Management Service 來加密應用程式使用的任何敏感資料。
### 架構考量事項
+ 實作監控和記錄。設定 CloudWatch 警示和日誌，以監控應用程式的運作狀態和效能。
+ 新增錯誤處理。在 Lambda 函數中實作全面的錯誤處理。
+ 考慮擴展限制。請注意服務配額，並在需要時請求增加高通話量。
+ 實作基礎設施做為程式碼。使用 CloudFormation 或 AWS CDK 部署您的 基礎設施。
+ 設定 CI/CD 管道。為您的 Lambda 函數實作持續整合和部署。
如需建置生產就緒應用程式的詳細資訊，請參閱：
+ [AWS Well-Architected 架構](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html)
+ [安全性、身分與合規的最佳實務](https://aws.amazon.com/architecture/security-identity-compliance/)
+ [無伺服器應用程式鏡頭](https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/welcome.html)
## 後續步驟
現在您已了解如何使用 Amazon Chime SDK PSTN 音訊將呼叫路由到 Lambda 函數，您可以探索更進階的功能：
+ 與 Amazon Lex 整合，以管理智慧代理程式案例的對話方塊互動。如需詳細資訊，請參閱[為 Amazon Chime SDK 訊息建立 Amazon Lex V2 機器人](create-lex-bot.md)。
+ 設定語音分析，從通話中取得洞見。如需詳細資訊，請參閱[使用 Amazon Chime SDK 的呼叫分析從呼叫產生洞見](call-analytics.md)。
+ 探索進階通話控制動作，以建置複雜的通話流程。如需詳細資訊，請參閱[使用 Amazon Chime SDK 的通話分析組態](using-call-analytics-configurations.md)。
# 了解如何使用 Amazon Chime SDK PSTN 音訊服務通話端
PSTN 音訊服務可以在一或多個通話腳上操作。例如，當您錄製或交付語音郵件時，您有一個通話分支，而當您加入 Amazon Chime SDK 會議時，您有多個通話分支。
下圖顯示單一呼叫的流程。
![\[單一呼叫分支架構的圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/single-leg-architecture.png)
下圖顯示多腳呼叫的架構。
![\[多腿呼叫架構的圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/multi-leg-architecture.png)
下圖顯示多腿橋接通話的流程。
![\[多腿橋接通話的架構圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/Multi-Leg-Architecture-w-Bridge.png)
# 了解 Amazon Chime SDK PSTN 音訊的通話流程
此圖表顯示透過 Amazon Chime SDK PSTN 音訊服務和客戶 AWS Lambda 函數的通話流程。在此範例中，應用程式會向發起人播放提示、收集雙音多頻率 (DTMF) 數字，然後將它們連接到 Amazon Chime SDK 會議。
圖表中的數字對應至圖表下方的編號說明。
![\[透過 PSTN 音訊服務和 AWS Lambda 函數的基本通話流程圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/pstn-call-flow-diagram.png)
在圖表中：
1. Amazon Chime SDK PSTN 音訊服務會收到對 SIP 規則中佈建之電話號碼的呼叫。
1. PSTN 音訊服務會擷取相關聯的 SIP 媒體應用程式，並使用`NEW_INBOUND_CALL`事件 (LEG-A) 叫用相關聯的 AWS Lambda 函數。
1. AWS Lambda 函數會傳回動作清單，包括 `PlayAudioAndGetDigits`，指示 PSTN 音訊服務接聽通話、播放音訊檔案給發起人，以及收集發起人輸入的 DTMF 數字。
1. PSTN 音訊服務會接聽通話、播放音訊提示，以及收集發起人的 DTMF 數字輸入。
1. PSTN 音訊服務會使用 DTMF 數字輸入叫用 AWS Lambda 函數。 AWS Lambda 函數使用 AWS SDK 來建立 Amazon Chime SDK 會議和會議出席者。
1. 一旦 AWS SDK 傳回 `MeetingId`和 `AttendeeId`， AWS Lambda 函數便會傳回 動作，將呼叫加入 Amazon Chime SDK 會議 (LEG-B)。
1. 即時傳輸通訊協定 (RTP) 工作階段是在來電者從公有交換電話網路 (PSTN) 與 Amazon Chime SDK 媒體服務之間建立。
1. 當 PSTN 呼叫者掛斷時，PSTN 音訊服務會使用 HANGUP 事件叫用函數 AWS Lambda ，而 AWS Lambda 函數會刪除出席者。
# 為 Amazon Chime SDK PSTN 音訊服務建置 AWS Lambda 函數
本節中的主題說明如何建置 PSTN 音訊服務所使用的 AWS Lambda 函數。
**Topics**
+ [了解 Amazon Chime SDK PSTN 音訊服務的電話語音事件](pstn-invocations.md)
+ [了解 Amazon Chime SDK PSTN 音訊服務動作](about-actions.md)
+ [了解叫用 Amazon Chime SDK PSTN 音訊服務 AWS Lambda 函數的電話語音事件](invoking-Lambda.md)
+ [使用 Amazon Chime SDK PSTN 音訊服務以動作清單回應調用](invoke-on-call-leg.md)
+ [Amazon Chime SDK PSTN 音訊服務的支援動作](specify-actions.md)
+ [在 Amazon Chime SDK PTSN 音訊服務中使用 SIP 標頭](sip-headers.md)
+ [在 Amazon Chime SDK PTSN 音訊服務中使用通話詳細資訊記錄](attributes.md)
+ [了解 Amazon Chime SDK PTSN 音訊服務的逾時和重試](timeouts.md)
+ [Amazon Chime SDK PTSN 音訊服務的偵錯和故障診斷](debug-pstn.md)
+ [了解 VoiceFocus Amazon Chime SDK PTSN 音訊服務](voice-focus.md)
+ [Amazon Chime SDK PSTN 音訊服務詞彙表](chm-dg-glossary.md)
# 了解 Amazon Chime SDK PSTN 音訊服務的電話語音事件
當通話期間發生特定事件時，Audio Service 會叫用您的 AWS AWS Lambda 函數。下列範例顯示事件，以及範例說明每個事件之後的文字。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "event-type",
"CallDetails": {
"TransactionId": "transaction-id-1",
"AwsAccountId": "aws-acct-id-1",
"AwsRegion": "us-east-1",
"SipMediaApplicationId": "sip-media-app-id-1",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "e164PhoneNumber",
"From": "e164PhoneNumber",
"Direction": "Inbound/Outbound",
"StartTimeInMilliseconds": "1641998241509",
"Status": "Connected/Disconnected"
}
]
}
}
```
**SchemaVersion**
用來建立此事件物件的結構描述版本。
**Sequence**
叫用函數的事件序列 AWS Lambda 。每次在呼叫期間叫用函數時，序列都會遞增。
**InvocationEventType**
觸發 AWS Lambda 調用的事件類型。如需詳細資訊，請參閱本主題後面部分的 [Event types (事件類型)](#pstn-event-types)。
**CallDetails**
與 AWS Lambda 調用相關聯的呼叫資訊。
**TransactionId**
與 AWS Lambda 呼叫相關聯的呼叫 ID。
**AwsAccountId**
與導致通話轉接的 SIP 媒體應用程式相關聯的 AWS 帳戶 ID。
**SipMediaApplicationId**
與呼叫相關聯的 SIP 媒體應用程式的 ID。
**Participants**
叫用 AWS AWS Lambda 函數之通話參與者的相關資訊。
**CallId**
指派給每個參與者的唯一 ID。
**ParticipantTag**
每個通話參與者都會取得標籤 `LEG-A`或 `LEG-B`。
**To**
參與者「收件人」電話號碼，格式為 E.164。
**From**
參與者「寄件人」電話號碼，格式為 E.164。
**Direction**
呼叫腿的來源方向。 `Inbound`代表對音訊服務的呼叫。 `Outbound`代表從音訊服務發出的呼叫。
**StartTimeInMilliseconds**
以毫秒為單位的 epoch 時間，從參與者加入通話開始。
**Status**
參與者是 `Connected`還是 `Disconnected`
## Event types (事件類型)
Audio Service 會使用下列事件類型叫用 Lambda 函數：
**NEW\$1INBOUND\$1CALL**
與您的 SIP 媒體應用程式相關聯的電話號碼已啟動新呼叫。
**NEW\$1OUTBOUND\$1CALL**
已透過 [CreateSipMediaApplicationCall](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html) API 進行新的外撥通話。
**ACTION\$1SUCCESSFUL**
從 AWS Lambda 函數傳回的動作已成功。成功的動作包括`ActionData`符合成功動作的動作。
```
"ActionData": {
// The previous successful action
},
```
**ACTION\$1FAILED**
從 AWS Lambda 函數傳回的動作未成功。不成功的動作包括與失敗動作`ActionData`相符的動作、錯誤類型，以及描述失敗的錯誤訊息：
```
"ActionData": {
// The previous unsuccessful action
"ErrorType": "error-type",
"ErrorMessage": "error message"
},
```
**ACTION\$1INTERRUPTED**
執行過程中的動作被 [ UpdateSipMediaApplicationCall](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 呼叫中斷。`ActionData` 包含中斷的動作：
```
"ActionData": {
// The action that was interrupted
},
```
**HANGUP**
使用者或應用程式掛斷通話腿。`ActionData` 包含有關事件的這些詳細資訊：
```
"ActionData": {
"Type": "Hangup",
"Parameters": {
"SipResponseCode": 486,
"CallId": "c70f341a-adde-4406-9dea-1e01d34d033d",
"ParticipantTag": "LEG-A"
}
},
```
**Type**
掛斷。
**Parameters**
`HANGUP` 事件的相關資訊：
+ **SipResponseCode** – 與事件相關聯的回應代碼。最常見的代碼為：
+ **0** – 正常清除
+ **480** – 無回應
+ **486** – 使用者忙碌
+ **CallId** 掛斷的參與者 ID。
+ **ParticipantTag** 掛斷的參與者標籤。
**CALL\$1ANSWERED**
Audio Service 已接聽來電。除非呼叫橋接，否則此事件會在撥出呼叫時傳回。
**INVALID\$1LAMBDA\$1RESPONSE**
提供給上次調 AWS Lambda 用的回應會導致問題。`ActionData` 包含下列其他欄位：
```
"ErrorType": "error-type-1",
"ErrorMessage": "error-msg-1"
```
**DIGITS\$1RECEIVED**
應用程式在`ReceiveDigits`動作完成後收到 DTMF 數字。`ActionData` 包含收到的數字。
```
"ActionData": {
"ReceivedDigits": ###
// The ReceiveDigits action data
},
```
**CALL\$1UPDATE\$1REQUESTED**
[UpdateSipMediaApplicationCall](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 已叫用。`ActionData` 包含更新請求的相關資訊：
```
"ActionData": {
"Type": "CallUpdateRequest",
"Parameters": {
"Arguments": {
"leg": "LEG-A"
}
}
},
}
```
**RINGING**
通話分支正在響鈴
# 了解 Amazon Chime SDK PSTN 音訊服務動作
在 PSTN 音訊服務中，SIP 媒體應用程式會觸發 AWS Lambda 函數。然後， AWS Lambda 函數可以傳回稱為*動作*的指示清單。動作是您想要在通話中執行的項目，例如傳送或接收數字、加入會議等。動作也可以傳回資料，因此您可以將動作視為具有資料欄位的物件。如需 PSTN 音訊服務調用之動作的詳細資訊，請參閱 [了解 Amazon Chime SDK PSTN 音訊服務的電話語音事件](pstn-invocations.md)。
# 了解叫用 Amazon Chime SDK PSTN 音訊服務 AWS Lambda 函數的電話語音事件
Audio Service 會叫用 AWS Lambda 函數以回應不同的事件。每個調用都會指定調用事件類型，並在適用時提供呼叫詳細資訊，包括其參與者。下列主題說明叫用 AWS Lambda 函數的 Audio Service 事件。
# 使用 Amazon Chime SDK PSTN 音訊服務進行外撥通話
若要建立外撥通話，請使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html) API。API 會叫用指定 的端點`SIP media application ID`。客戶可以透過提供與端點不同的訊號和[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_SipMediaApplication.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_SipMediaApplication.html)動作來控制通話流程。
如果成功回應，API 會傳回 202 http 狀態碼與 transactionId，您可以將其與 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 搭配使用，以更新進行中的呼叫。
下圖顯示對傳出呼叫的 AWS Lambda 函數端點發出的呼叫。
![\[圖表顯示對 AWS Lambda 端點發出的調用程式設計流程。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/sip-api-1.png)
針對 SIP 媒體應用程式設定的端點會針對撥出通話的不同狀態叫用。當客戶起始呼叫時，Amazon Chime SDK 會使用`NEW_OUTBOUND_CALL`呼叫事件類型叫用端點。
此範例顯示 的典型調用事件`NEW_OUTBOUND_CALL`。
```
{
"SchemaVersion": "1.0",
"Sequence": 1,
"InvocationEventType": "NEW_OUTBOUND_CALL",
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+1xxxx",
"From": "+1xxxxxxx",
"Direction": "Outbound",
"StartTimeInMilliseconds": "159700958834234"
}
]
}
}
```
會忽略事件相關調 AWS Lambda 用的任何回應。
當我們從接收者收到`RINGING`通知時，Amazon Chime SDK 會再次叫用設定的端點。
此範例顯示 的典型調用事件`RINGING`。
```
{
"SchemaVersion": "1.0",
"Sequence": 1,
"InvocationEventType": "RINGING",
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+1xxxx",
"From": "+1xxxxxxx",
"Direction": "Outbound",
"StartTimeInMilliseconds": "159700958834234"
}
]
}
}
```
會忽略事件相關調 AWS Lambda 用的任何回應。
如果接收者未接聽通話，或通話因錯誤而失敗，Chime 會中斷通話，並使用`Hangup`事件類型叫用端點。如需`Hangup`事件類型的詳細資訊，請參閱 [使用 Amazon Chime SDK PSTN 音訊服務結束通話](case-5.md)。
如果通話已接聽，Chime 會使用 `CALL_ANSWERED`動作叫用端點。此範例顯示典型的調用事件。
```
{
"SchemaVersion": "1.0",
"Sequence": 1,
"InvocationEventType": "CALL_ANSWERED",
"CallDetails": {
""TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+1xxxx",
"From": "+1xxxxxxx",
"Direction": "Outbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
}
]
}
}
```
此時，您可以使用動作清單回應調用，以傳回動作。如果您不想執行任何動作，請以空白清單回應。您每次 AWS Lambda 呼叫最多可以回應 10 個動作，而且每次呼叫可以叫用 Lambda 函數 1，000 次。如需使用一組動作回應的詳細資訊，請參閱 [使用 Amazon Chime SDK PSTN 音訊服務以動作清單回應調用](invoke-on-call-leg.md)。
# 使用 Amazon Chime SDK PSTN 音訊服務接聽來電
`NEW_INCOMING_CALL` 事件發生時，Audio Service 會建立唯一`TransactionID`且唯一的 `CallID`，持續到`HANGUP`事件發生為止。
您可以透過多種方式回應`NEW_INCOMING_CALL`事件。例如：
+ 傳送 `PlayAudio` 或 `RecordAudio`動作並自動接聽通話。
+ 傳送`Pause`動作。
+ 傳送`Hangup`動作，在這種情況下，通話不會接聽，也不會向客戶收費。
+ 傳送`CallAndBridge`動作，並將其他使用者新增至通話。
+ 不採取任何動作，呼叫嘗試會在 30 秒後逾時。
收到新的傳入呼叫時，SIP 媒體應用程式會呼叫具有此承載的 AWS Lambda 函數。
```
{
"SchemaVersion": "1.0",
"Sequence": 2,
"InvocationEventType": "NEW_INBOUND_CALL"
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+12065551212",
"From": "+15105550101",
"Direction": "Inbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
}
]
}
}
```
# 指定動作以回應 Amazon Chime SDK PSTN 音訊服務的電話語音事件
在音訊服務中，SIP 媒體應用程式會叫用 AWS Lambda 函數。反之，Lambda 函數可以傳回稱為*動作*的指示清單。動作是您想要在通話中執行的項目，例如傳送或接收數字、加入會議等。如需 PSTN 音訊服務調用之動作的詳細資訊，請參閱 [了解 Amazon Chime SDK PSTN 音訊服務的電話語音事件](pstn-invocations.md)。
當 SIP 媒體應用程式成功執行動作清單時，應用程式會呼叫叫用事件類型為 的 AWS Lambda 函數`ACTION_SUCCESSFUL`。如果有任何動作無法完成，SIP 媒體應用程式會使用 `ACTION_FAILED`事件呼叫 AWS Lambda 函數。
只有當清單中的所有動作都成功`ACTION_SUCCESSFUL`時，SIP 媒體應用程式才會傳回 。如果清單中的任何動作失敗，SIP 媒體應用程式會使用 `ACTION_FAILED`事件叫用 AWS Lambda 函數，並在失敗之後清除清單中的剩餘動作。然後，SIP 媒體應用程式會執行 AWS Lambda 函數傳回的下一個動作。您可以使用 `ActionData`金鑰來識別叫用函數的呼叫。
下列事件顯示`PlayAudioAndGetDigits`動作後`ACTION_SUCCESSFUL`調用事件類型的範例承載。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "PlayAudioAndGetDigits",
"Parameters" : {
"CallId": "call-id-1",
"AudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "failure-audio-file.wav"
},
"FailureAudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "failure-audio-file.wav"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
},
"ReceivedDigits": "123"
}
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+12065551212",
"From": "+15105550101",
"Direction": "Inbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
}
]
}
}
}
```
當清單中的任何動作無法成功完成時，SIP 媒體應用程式會叫用 AWS Lambda 函數來通知您失敗，並取得要在該呼叫上執行的新動作集。下列事件顯示`PlayAudio`動作後`ACTION_FAILED`調用事件類型的範例承載。
```
{
"SchemaVersion": "1.0",
"Sequence": 4,
"InvocationEventType": "ACTION_FAILED",
"ActionData": {
"Type": "PlayAudio",
"Parameters" : {
"CallId": "call-id-1",
"AudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "audio-file.wav"
}
},
"ErrorType": "InvalidAudioSource",
"ErrorMessage": "Audio Source parameter value is invalid."
}
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+12065551212",
"From": "+15105550101",
"Direction": "Inbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
}
]
}
}
}
```
# 接收 Amazon Chime SDK PSTN 音訊服務的來電者輸入
您可以使用 `ReceiveDigits`動作來收集傳入 DTMF 數字，並將其與規則表達式比對。當 SIP 媒體應用程式收到符合規則表達式的數字時，它會呼叫具有 `ACTION_SUCCESSFUL`事件的 AWS Lambda 函數。收集的數字會出現在 `ActionData` 物件中的 `ReceivedDigits`值中。
例如：
```
{
"SchemaVersion": "1.0",
"Sequence": 4,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"ReceivedDigits": "",
"Type": "ReceiveDigits",
"Parameters": {
"CallId": "call-id-1",
"InputDigitsRegex": "^\d{2}#$",
"InBetweenDigitsDurationInMilliseconds": 5000,
"FlushDigitsDurationInMilliseconds": 10000
}
},
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+12065551212",
"From": "+15105550101",
"Direction": "Inbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
}
]
}
}
```
呼叫者輸入符合您規則表達式模式的數字後，SIP 媒體應用程式會叫用 AWS Lambda 函數，傳回下列類型的承載：
```
{
"SchemaVersion": "1.0",
"Sequence": 5,
"InvocationEventType": "DIGITS_RECEIVED",
"ActionData": {
"ReceivedDigits": "11#",
"Type": "ReceiveDigits",
"Parameters": {
"CallId": "call-id-1",
"InputDigitsRegex": "^\d{2}#$",
"InBetweenDigitsDurationInMilliseconds": 5000,
"FlushDigitsDurationInMilliseconds": 10000
}
},
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+12065551212",
"From": "+15105550101",
"Direction": "Inbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
}
]
}
}
```
請參閱 GitHub 上的工作範例：https：//[https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# 更新 Amazon Chime SDK PTSN 音訊的進行中呼叫
作為 PSTN 音訊服務的一部分，SIP 媒體應用程式可讓您根據呼叫事件叫用使用者定義的 Lambda 函數，例如傳入呼叫或 DTMF 數字，來設定在呼叫上執行的動作。[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 可讓您在呼叫作用中時隨時觸發 Lambda 函數，以調用傳回的新動作取代目前的動作。
**工作流程**
您可以在各種情況下使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API，例如將參與者新增至會議、將使用者靜音和解除靜音、中斷連線等。下列使用案例說明典型的工作流程。
使用者在 Amazon Chime SDK 設定會議時呼叫和聆聽音樂。設定完成後，Amazon Chime SDK 會停止音訊，並將發起人加入會議。接著，假設使用管理會議的個別系統 `MyMeetingService`。每個傳入呼叫都應保留。Chime 會通知 MyMeetingService 有關傳入呼叫，然後 MyMeetingService 會為每個呼叫建立出席者，當 MyMeetingService 準備好開始會議時，它會通知 SIP 媒體應用程式，並提供加入會議的權杖。
若要處理此案例，Lambda 函數必須實作下列邏輯。
+ 當新的來電送達時，Lambda 會與`NEW_INBOUND_CALL`事件一起叫用。Lambda 會呼叫 `MyMeetingService`並傳遞可識別目前呼叫`transactionId`的 ，然後傳回 `PlayAudio`動作。
+ 當 `MyMeetingService` 準備好將發起人新增至會議時，服務會呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API，並傳遞呼叫的 `transactionId`和 `JoinToken` 作為其引數的一部分。此 API 呼叫會再次觸發 Lambda 函數，現在使用 `CALL_UPDATE_REQUESTED`事件。MyMeetingService 會將 傳遞`JoinToken`至 Lambda 函數，做為事件的一部分，並使用權杖將`JoinChimeMeeting`動作傳回至 SIP 媒體應用程式，這會中斷`PlayAudio`動作並將呼叫者連線至會議。
![\[顯示 UpdateSipMediaApplicationCall API 中資料流程的圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/update-sip-call-flow3.png)
**注意**
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 會傳回 HTTP 202 （已接受）。SIP 媒體應用程式會確認呼叫正在進行中並可以更新，因此會嘗試叫用 Lambda 函數。調用會以非同步方式執行，因此 API 的成功回應並不保證 Lambda 函數已啟動或完成。
下列範例顯示請求語法。
```
{
"SipMediaApplicationId": "string",
"TransactionId": "string",
"Arguments": {
"string": "string"
}
}
```
**請求參數**
+ `SipMediaApplicationId` – 處理呼叫的 SIP 媒體應用程式的 ID。
+ `TransactionId` – 呼叫交易的 ID。對於傳入呼叫，`TransactionId`可以從第一次調用時傳遞給 Lambda 函數`NEW_INCOMING_CALL`的事件中取得 。對於傳出呼叫， `TransactionId` 會在 的回應中傳回[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html)。
+ **引數** – 作為`CallUpdateRequest`動作資料的一部分提供給 Lambda 函數的自訂引數。可以包含 0 到 20 個鍵值對。
下列範例顯示典型的請求。
```
aws chime update-sip-media-application-call --sip-media-application-id feb37a7e-2b66-49fb-b2dd-30f4780dc36d --transaction-id 1322a4e7-c106-4e70-aaaf-a8fa4c77c0cb --arguments '{"JoinToken": "abc123"}'
```
**回應語法**
```
{
"SipMediaApplicationCall": {
"TransactionId": "string"
}
}
```
**回應元素**
+ **TransactionId** – 呼叫交易的 ID，與請求相同的 ID。
下列範例顯示`CALL_UPDATE_REQUESTED`調用事件。
```
{
"SchemaVersion": "1.0",
"Sequence": 2,
"InvocationEventType": "CALL_UPDATE_REQUESTED",
"ActionData": {
"Type": "CallUpdateRequest",
"Parameters": {
"Arguments": {
"string": "string"
}
}
},
"CallDetails": {
...
}
}
```
**事件元素**
+ **SchemaVersion** – JSON 結構描述的版本 (1.0)
+ **序列** – 呼叫中事件的序列編號
+ **InvocationEventType** – Lambda 調用事件的類型，在此情況下， `CALL_UPDATE_REQUESTED`
+ **ActionData** – 與`CallUpdateRequest`動作相關聯的資料。
+ **類型** – 動作類型，在此情況下， `CallUpdateRequest`
+ **參數** – 動作的參數
+ **引數** – 做為 `UpdateSipMediaApplicationCall` API 請求的一部分傳遞的引數
+ **CallDetails** – 目前呼叫狀態的相關資訊
**了解可中斷和不可中斷的動作**
當 Lambda 函數在現有動作執行時傳回新的動作清單時，所有後續進行中動作的動作都會取代為新的動作。在某些情況下，Lambda 函數會中斷進行中的動作，以立即執行新的動作。
下圖顯示典型的範例。圖表下方的文字說明邏輯。
![\[顯示如何在進行中的 SIP 媒體應用程式呼叫期間取代動作的圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/update-sip-actions.png)
如果動作 2 可中斷，我們會停止它並改為執行新的動作 1。
如果動作 2 無法中斷，它會在新的動作 1 啟動之前完成。
在這兩種情況下，動作 3 都不會執行。
如果某件事中斷動作，則會使用`ACTION_INTERRUPTED`事件叫用 Lambda 函數。此事件僅用於資訊用途。SIP 媒體應用程式會忽略此調用傳回的所有動作。
可中斷動作的類型：
+ `PlayAudio`
+ `RecordAudio`
+ `Pause`
**Lambda 函數範例**
此範例顯示典型的 Lambda 函數，可播放音訊檔案、傳遞聯結字符，以及更新呼叫。
```
const MMS = require('my-meeting-service');
const myMeetingServiceClient = new MMS.Client();
exports.handler = async (event) => {
console.log('Request: ' + JSON.stringify(event));
const playAudio = () => {
return {
Type: 'PlayAudio',
Parameters: {
ParticipantTag: 'LEG-A',
AudioSource: {
Type: 'S3',
BucketName: 'chime-meetings-audio-files-bucket-name',
Key: 'welcome.wav'
}
}
}
}
const joinChimeMeeting = (joinToken) => {
return {
Type: 'JoinChimeMeeting',
Parameters: {
JoinToken: joinToken
}
}
}
const response = (...actions) => {
const r = {
SchemaVersion: '1.0',
Actions: actions
};
console.log('Response: ' + JSON.stringify(r));
return r;
};
switch (event.InvocationEventType) {
case 'NEW_INBOUND_CALL':
myMeetingServiceClient.addPendingCall(event.CallDetails.TransactionId);
return response(playAudio());
case 'CALL_UPDATE_REQUESTED':
const joinToken = event.ActionData.Parameters.Arguments['JoinToken']
return response(joinChimeMeeting(joinToken));
default:
return response();
}
}
```
# 使用 Amazon Chime SDK PSTN 音訊服務結束通話
您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html) API 來結束外撥通話。API 會叫用指定 **SIP 媒體應用程式 ID** 的端點。客戶可以透過將動作傳回 SIP 媒體應用程式來控制通話的流程。
如果成功回應，API 會傳回 202 http 狀態碼與 `transactionId`，您可以將其與 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 搭配使用，以更新進行中的呼叫。
下圖顯示對傳出呼叫的 AWS Lambda 函數端點發出的呼叫。
![\[叫用 CreateSipMediaApplicationCall API 時的資料流程。當外撥通話的狀態變更時，API 會叫用不同的端點。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/sip-api-1.png)
針對 SIP 媒體應用程式設定的端點會針對撥出通話的不同狀態叫用。當客戶和 呼叫時，Amazon Chime SDK 會使用`HANGUP`呼叫事件類型叫用端點。
此範例顯示 的典型調用事件`HANGUP`。
```
{
"SchemaVersion": "1.0",
"Sequence": 6,
"InvocationEventType": "HANGUP",
"ActionData": {
"Type": "Hangup",
"Parameters": {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A"
}
},
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"Direction": "Inbound",
"To": "+12065551212",
"From": "+15105550101",
"StartTimeInMilliseconds": "1597009588",
"Status": "Disconnected"
}
]
}
}
// if LEG-B receives a hangup in a bridged call, such as a meeting ending
{
"SchemaVersion": "1.0",
"Sequence": 6,
"InvocationEventType": "HANGUP",
"ActionData": {
"Type": "ReceiveDigits",
"Parameters": {
"CallId": "call-id-2",
"ParticipantTag": "LEG-B"
}
},
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "Leg-A",
"To": "+12065551212",
"From": "+15105550101",
"Direction": "Inbound",
"StartTimeInMilliseconds": "1597009588",
"Status": "Connected"
},
{
"CallId": "call-id-2",
"ParticipantTag": "Leg-B",
"To": "+17035550122",
"From": "SMA",
"Direction": "Outbound",
"StartTimeInMilliseconds": "15010595",
"Status": "Disconnected"
}
]
}
}
```
# 了解 end-to-end呼叫
此使用案例提供從 PSTN 來電者接聽電話、以音訊訊息問候來電者、從來電者取得會議 PIN 碼、播放音訊，以及將來電者加入會議的範例代碼。
**呼叫事件和動作**
Audio Service 會將調用事件傳遞給 做為 JSON 物件 AWS Lambda 。物件包含調用事件類型和任何相關的中繼資料。此 AWS Lambda 函數也會將 SIP 媒體應用程式動作傳回為 JSON 物件，而這些物件包含動作類型和任何相關的中繼資料。
當您收到呼叫事件時，下表列出呼叫事件`ActionData.Type`，以及可能的 。
| 調用事件 | ActionData.Type |
| --- | --- |
| ACTION\$1SUCCESSFUL | CallAndBridge ReceiveDigits PlayAudio PlayAudioAndGetDigits JoinChimeMeeting ModifyChimeMeetingAttendees RecordMeeting |
| ACTION\$1FAILED | CallAndBridge PlayAudio PlayAudioAndGetDigits ModifyChimeMeetingAttendees RecordMeeting |
| HANGUP | HangUp |
| DIGITS\$1RECEIVED | ReceiveDigits |
**注意**
若要實作下列使用案例，您的 Amazon Chime SDK 庫存中至少需要一個電話號碼、使用 Amazon Resource Name (ARN) 函數 AWS Lambda 的 SIP 媒體應用程式受管物件，以及使用電話號碼做為其觸發條件的 SIP 規則。
當 Amazon Chime SDK 收到對規則中指定電話號碼的呼叫時，PSTN 音訊服務會叫用具有`NEW_INBOUND_CALL`叫用事件類型的 AWS Lambda 函數。
```
{
"SchemaVersion": "1.0",
"Sequence": 1,
"InvocationEventType": "NEW_INBOUND_CALL",
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+11234567890",
"From": "+19876543210",
"Direction": "Inbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
}
]
}
}
```
您可以編寫 AWS Lambda 函數以驗證呼叫詳細資訊，並存放以供日後使用。對於`NEW_INBOUND_CALL`事件， AWS Lambda 函數會回應一組動作，播放歡迎提示並要求會議 PIN 碼。
音訊檔案有下列需求：
+ 您必須從 Amazon Simple Storage Service (S3) 儲存貯體播放音訊檔案。S3 儲存貯體必須屬於與 SIP 媒體應用程式相同的 AWS 帳戶。此外，您必須將 `s3:GetObject`許可授予 Amazon Chime SDK Voice Connector 服務主體：`voiceconnector.chime.amazonaws.com`。您可以使用 S3 主控台或命令列界面 (CLI) 來執行此操作。
+ 您必須使用大小不超過 50 MB 的 PCM WAV 檔案。Amazon Chime SDK 建議 8 KHz 單機。
+ 每個 WAV 檔案的 S3 中繼資料必須包含 `{'ContentType': 'audio/wav'}`。
```
{
"SchemaVersion": "1.0",
"Actions": [
{
"Type" : "PlayAudio",
"Parameters" : {
"CallId": "call-id-1",
"AudioSource": {
"Type": "S3",
"BucketName": "chime-meetings-audio-files-bucket-name",
"Key": "welcome-to-meetings.wav"
}
}
},
{
"Type": "PlayAudioAndGetDigits",
"Parameters" : {
"ParticipantTag": "LEG-A",
"AudioSource": {
"Type": "S3",
"BucketName": "chime-meetings-audio-files-bucket-name",
"Key": "enter-meeting-pin.wav"
},
"FailureAudioSource": {
"Type": "S3",
"BucketName": "chime-meetings-audio-files-bucket-name",
"Key": "invalid-meeting-pin.wav"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
}
}
]
}
```
SIP 媒體應用程式會在呼叫分支 A 上執行這些動作。假設`PlayAudioAndGetDigits`動作接收數字，則 SIP 媒體應用程式會使用`ACTION_SUCCESSFUL`事件類型叫用 AWS Lambda 函數。
```
{
"SchemaVersion": "1.0",
"Sequence": 2,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "PlayAudioAndGetDigits",
"Parameters" : {
"ParticipantTag": "LEG-A",
"AudioSource": {
"Type": "S3",
"BucketName": "chime-meetings-audio-files-bucket-name",
"Key": "enter-meeting-pin.wav"
},
"FailureAudioSource": {
"Type": "S3",
"BucketName": "chime-meetings-audio-files-bucket-name",
"Key": "invalid-meeting-pin.wav"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
},
"ReceivedDigits": "12345" // meeting PIN
},
"CallDetails": {
... // same as in previous event
}
}
}
```
您可以編寫 AWS Lambda 函數的程式，根據`CallDetails`資料識別發起人。您也可以驗證先前收到的會議 PIN 碼。假設 PIN 碼正確，然後使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html)和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateAttendee.html) APIs 來建立 Amazon Chime SDK 會議，並產生會議出席者使用的聯結字符。 AWS Lambda 函數會以 動作回應，以加入 Amazon Chime SDK 會議。
```
{
"SchemaVersion": "1.0",
"Actions": [
{
"Type": "JoinChimeMeeting",
"Parameters": {
"JoinToken": "meeting-attendee-join-token"
}
}
]
}
```
假設 `JoinToken` 有效，則 SIP 媒體應用程式會加入 Amazon Chime SDK 會議，並使用 `ACTION_SUCCESSFUL`事件叫用 AWS Lambda 函數，其中 `CallDetails`包含來自 SIP 媒體應用程式和 Chime Media 服務 (`LEG-B`) 的資料
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type" : "JoinChimeMeeting",
"Parameters" : {
"JoinToken": "meeting-attendee-join-token"
}
},
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+11234567890",
"From": "+19876543210",
"Direction": "Inbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
},
{
"CallId": "call-id-2",
"ParticipantTag": "LEG-B",
"To": "SMA",
"From": "+17035550122",
"Direction": "Outbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
}
]
}
}
```
如果此時想要停止對通話或通話分支執行動作，您可以使用空的動作集來回應。
```
{
"SchemaVersion": "1.0"
"Actions": []
}
```
呼叫者掛斷後，SIP 媒體應用程式會使用 `HANGUP`事件叫用 AWS Lambda 函數。
```
{
"SchemaVersion": "1.0",
"Sequence": 4,
"InvocationEventType": "HANGUP",
"ActionData": {
"Type": "Hangup",
"Parameters": {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A"
}
},
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+11234567890",
"From": "+19876543210",
"Direction": "Inbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Disconnected"
},
{
"CallId": "call-id-2",
"ParticipantTag": "LEG-B",
"To": "SMA",
"From": "+17035550122",
"Direction": "Outbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Disconnected"
}
]
}
}
```
如果您使用 動作回應`Hangup`事件，如果沒有其他 `Participants` 顯示 ，則 SIP 媒體應用程式會忽略`Status`該動作`Connected`。
# 使用 Amazon Chime SDK PSTN 音訊服務以動作清單回應調用
您可以使用要在通話中個別參與者上執行的動作清單來回應 AWS Lambda 調用事件。對於每次 AWS Lambda 呼叫，您最多可以回應 10 個動作，而且每次呼叫可以叫用 AWS Lambda 函數 1，000 次。
根據預設，如果 Lambda 函數在 20 秒後沒有回應，SIP 媒體應用程式會逾時。
下列範例顯示一般回應結構。
```
{
"SchemaVersion": "1.0",
"Actions": [
{
"Type": "PlayAudio",
"Parameters": {
"ParticipantTag": "LEG-A",
"AudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "audio-file.wav"
}
}
},
{
"Type": "RecordAudio",
"Parameters": {
"DurationInSeconds": "10",
"RecordingTerminators": ["#"],
"RecordingDestination": {
"Type": "S3",
"BucketName": "bucket-name"
}
}
}
]
}
```
當 AWS Lambda 函數將動作清單傳回至 SIP 媒體應用程式時，會發生下列操作：
1. 應用程式完成對呼叫執行目前的動作。
1. 然後，應用程式會將舊動作集取代為從最新調用事件收到的一組新動作。
如果 SIP 媒體應用程式收到`NULL`動作集，它會保留現有的動作。
# Amazon Chime SDK PSTN 音訊服務的支援動作
您可以在 AWS Lambda 函數的回應中指定不同類型的訊號和媒體動作。每個動作都有不同的屬性。下列主題提供範例程式碼，並說明如何使用 動作。
**Topics**
+ [使用 TransactionAttributes](transaction-attributes.md)
+ [使用通話錄音](sip-apps-call-record.md)
+ [CallAndBridge](call-and-bridge.md)
+ [Hangup](hangup.md)
+ [JoinChimeMeeting](join-chime-meeting.md)
+ [ModifyChimeMeetingAttendee （靜音和取消靜音音訊）](mute-unmute.md)
+ [Pause](pause.md)
+ [PlayAudio](play-audio.md)
+ [PlayAudioAndGetDigits](play-audio-get-digits.md)
+ [ReceiveDigits](listen-to-digits.md)
+ [RecordAudio](record-audio.md)
+ [SendDigits](send-digits.md)
+ [Speak](speak.md)
+ [SpeakAndGetDigits](speak-and-get-digits.md)
+ [StartBotConversation](start-bot-conversation.md)
# 使用 TransactionAttributes
您可以使用`TransactionAttributes`資料結構來存放應用程式特有的資訊，例如呼叫狀態或會議 IDs，然後將該資料傳遞給 AWS Lambda 調用。此結構消除了將資料儲存在 Amazon DynamoDB 等外部資料庫中的需求。
`TransactionAttributes` 是包含金鑰/值對的 [JSON 物件](https://www.w3schools.com/js/js_json_objects.asp)。物件最多可包含 100 個金鑰/值對，且物件的最大承載大小為 20 KB。`TransactionAttributes` 結構中的資料在交易的生命週期內會持續存在。
當 AWS Lambda 函數傳遞`TransactionAttributes`至 SIP 媒體應用程式時，應用程式會更新任何儲存的屬性。如果您傳遞具有現有金鑰集的`TransactionAttributes`物件，則會更新儲存的值。如果您傳遞不同的金鑰集，您可以將現有的值取代為來自該不同金鑰集的值。傳遞空的映射 `{}` () 會清除任何儲存的值。
**Topics**
+ [設置 TransactionAttributes](set-trans-attributes.md)
+ [更新 TransactionAttributes](update-trans-attributes.md)
+ [清除 TransactionAttributes](clear-trans-attributes.md)
+ [處理ACTION\$1SUCCESSFUL事件](attribute-trans-success.md)
+ [無效的輸入](attribute-trans-invalid.md)
# 設置 TransactionAttributes
下列範例示範如何`TransactionAttributes`設定 [PlayAudio](play-audio.md) 動作，並將屬性從 AWS Lambda 函數傳遞至 SIP 媒體應用程式。
```
{
"SchemaVersion": "1.0",
"Actions": [
{
"Type": "PlayAudio",
"Parameters": {
"ParticipantTag": "LEG-A",
"AudioSource": {
"Type": "S3",
"BucketName": "mtg1-sipmedia-app-iad",
"Key": "Welcome3.wav"
}
}
}
],
"TransactionAttributes": {
"key1": "value1",
"key2": "value2"
}
}
```
# 更新 TransactionAttributes
若要修改已儲存的 `TransactionAttributes`，請使用新值更新 JSON 物件的內容。在下列範例中，金鑰 `NewKey1`和 `NewKey2` 會新增至 `TransactionAttributes`。這些金鑰會`NewValue2`分別與值 `NewValue1`和 配對。
```
{
"SchemaVersion": "1.0",
"Actions": [
{
"Type": "PlayAudio",
"Parameters": {
"ParticipantTag": "LEG-A",
"AudioSource": {
"Type": "S3",
"BucketName": "mtg1-sipmedia-app-iad",
"Key": "Welcome3.wav"
}
}
}
],
"TransactionAttributes": {
"NewKey1": "NewValue1",
"NewKey2": "NewValue2"
}
}
```
如果您在上一個範例中傳遞`NewValue1`至 `key1`，則 的現有值`key1`將取代為 `NewValue1`。不過，傳遞值以`NewKey1`建立新的索引鍵/值對。
# 清除 TransactionAttributes
若要清除`TransactionAttributes`物件的內容，請使用空的 JSON 物件傳遞 `TransactionAttributes` 欄位：
```
{
"SchemaVersion": "1.0",
"Actions": [
{
"Type": "PlayAudio",
"Parameters": {
"ParticipantTag": "LEG-A",
"AudioSource": {
"Type": "S3",
"BucketName": "mtg1-sipmedia-app-iad",
"Key": "Welcome3.wav"
}
}
}
],
"TransactionAttributes": {
}
}
```
**注意**
您無法將結構的值設定為 來清除`TransactionAttributes`結構中的資料`null`。此外，省略`TransactionAttribute`結構並不會清除其資料。一律使用 傳遞空的 JSON 物件`TransactionAttributes`，以從物件清除資料。
# 處理ACTION\$1SUCCESSFUL事件
下列範例顯示成功如何[PlayAudio](play-audio.md)傳送 `TransactionAttributes` 作為 的一部分存放的 `CallDetails `。
```
{
"SchemaVersion": "1.0",
"Sequence": 2,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "PlayAudio",
"Parameters": {
"AudioSource": {
"Type": "S3",
"BucketName": "mtg1-sipmedia-app-iad",
"Key": "Welcome3.wav"
},
"Repeat": 1,
"ParticipantTag": "LEG-A"
}
},
"CallDetails": {
"TransactionId": "mtg1-tx-id",
"TransactionAttributes": {
"key1": "value1",
"key2": "value2"
},
"AwsAccountId": "166971021612",
"AwsRegion": "us-east-1",
"SipRuleId": "aafbd402-b7a2-4992-92f8-496b4563c492",
"SipMediaApplicationId": "e88f4e49-dd21-4a3f-b538-bc84eae11505",
"Participants": [
{
"CallId": "bbff30c5-866a-41b5-8d0a-5d23d5e19f3e",
"ParticipantTag": "LEG-A",
"To": "+14345550101",
"From": "+14255550199",
"Direction": "Inbound",
"StartTimeInMilliseconds": "1644539405907",
"Status": "Connected"
}
]
}
}
```
# 無效的輸入
下列範例顯示無效的輸入。在此情況下，JSON 物件會將太多項目傳遞至 SIP 媒體應用程式。
```
{
"SchemaVersion": "1.0",
"Actions": [
{
"Type": "PlayAudio",
"Parameters": {
"ParticipantTag": "LEG-A",
"AudioSource": {
"Type": "S3",
"BucketName": "mtg1-sipmedia-app-iad",
"Key": "Welcome3.wav"
}
}
}
],
"TransactionAttributes": {
"key1": "value1",
"key2": "value2",
"key3": "value3",
"key4": "value4",
"key5": "value5",
"key6": "value6",
"key7": "value7",
"key8": "value8",
"key9": "value9",
"key10": "value10",
"key11": "value11"
}
}
```
下列範例顯示對先前指定輸入的回應。此輸出會從 SIP 媒體應用程式傳遞回叫用應用程式的 AWS Lambda 函數。
```
{
"SchemaVersion": "1.0",
"Sequence": 2,
"InvocationEventType": "INVALID_LAMBDA_RESPONSE",
"CallDetails": {
"TransactionId": "mtg1-tx-id",
"AwsAccountId": "166971021612",
"AwsRegion": "us-east-1",
"SipRuleId": "aafbd402-b7a2-4992-92f8-496b4563c492",
"SipMediaApplicationId": "e88f4e49-dd21-4a3f-b538-bc84eae11505",
"Participants": [
{
"CallId": "72cbec69-f098-45d8-9ad6-e26cb9af663a",
"ParticipantTag": "LEG-A",
"To": "+14345550101",
"From": "+14255550199",
"Direction": "Inbound",
"StartTimeInMilliseconds": "1644540839987"
}
]
},
"ErrorType": "TransactionAttributesInvalidMapSize",
"ErrorMessage": "Transaction Attributes has too many mappings. Maximum number of mappings is 10"
}
```
# 使用通話錄音
SIP 媒體應用程式的通話錄音動作可讓您針對各種用途建置通話錄音和通話後轉錄解決方案。例如，您可以記錄客戶服務呼叫，並將其用於訓練。
您可以搭配 SIP 媒體應用程式使用通話錄音動作。您也可以使用隨需或 動作來回應 SIP 事件。
+ 若要在 SIP 媒體應用程式中開始隨需記錄通話，您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice_chime_UpdateSipMediaApplication.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice_chime_UpdateSipMediaApplication.html) API 叫用應用程式並傳回 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartCallRecording.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartCallRecording.html)動作。
+ 若要開始通話錄音以回應 SIP 事件，您會在應用程式中傳回 `StartCallRecording`動作。
您可以暫停和繼續進行中的記錄。若要暫停，請使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_PauseCallRecording.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_PauseCallRecording.html)動作。若要繼續，請使用 `ResumeCallRecording`動作。每次您暫停或繼續錄製時，動作都會擷取提示暫停或恢復的音調。當您暫停時，動作會記錄靜音，Amazon Chime SDK 會使用此靜音來追蹤暫停的長度，並在您的帳單中包含暫停。您可以視需要暫停和繼續錄製。
若要停止通話錄音，請傳回 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopCallRecording.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopCallRecording.html)動作。不過，當通話停止時，通話錄音會自動停止，在這種情況下，您不需要明確傳回`StopCallRecording`動作。對於個別通話分支，您只能開始和停止錄製一次。
Amazon Chime SDK 會將通話錄音傳送到您選取的 Amazon S3 儲存貯體。儲存貯體必須屬於 AWS 您的帳戶。一旦呼叫停止，SIP 媒體應用程式會將錄音傳送到 [StartCallRecording](start-call-recording.md)動作的 `Destination` 參數中指定的資料夾。Amazon Chime SDK 會以開放的 WAV 格式記錄呼叫。記錄傳入和傳出軌道的通話會使用立體聲模式，左側通道的傳入軌道和右側通道的傳出軌道。如果您只記錄傳入或傳出軌道，系統會使用單一模式。
**注意**
使用此功能進行的錄製可能受到有關記錄電子通訊的法律和法規的約束。您和您的最終使用者有責任遵守有關記錄的所有適用法律，包括正確通知記錄工作階段或通訊中的所有參與者正在記錄工作階段或通訊，並取得他們的同意。
## 通話錄音的帳單
Amazon Chime SDK 會在啟用通話錄音的時間向您收取每分鐘費用，該時間包含所有暫停。一旦通話錄音傳送到 Amazon S3 儲存貯體，就會向您收取通話錄音用量的費用。
# 錄製音軌
您可以只記錄來電或撥出通話的音軌，或同時記錄通話的音軌。
此影像顯示典型的單邊或非橋接來電。
![\[僅與 SIP 媒體應用程式通訊的來電。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/call-record-sma-one-leg.png)
呼叫只有一個具有 **call-id-1** `callID` 的分支。`INCOMING` 音軌是從發起人到 SIP 媒體應用程式的音訊。`OUTGOING` 音軌是從 SIP 媒體應用程式到來電者的音訊。您的 SIP 媒體應用程式會指定您想要記錄`CallId`的通話的 。若要記錄撥打電話的參與者，請指定 `INCOMING`。若要記錄回應呼叫的參與者，請指定 `OUTGOING`。若要記錄兩個參與者，請指定 `BOTH`。
此影像顯示有兩個參與者的典型橋接通話。
![\[與 SIP 媒體應用程式和第二個參與者通訊的來電。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/call-record-sma-bridged.png)
在此範例中，呼叫有兩個呼叫分支：**Call-id-1** 和 **call-id-2**，且 **call-id-1** 橋接至 **call-id-2**。這會建立四個音訊軌，也就是兩個通話 IDs傳入和傳出音訊串流。您可以指定要記錄的通話 IDs 和音軌。例如，如果您想要從已呼叫的參與者記錄音軌，您可以透過將 **call-id-2** 指定為 `CallId`，並將 指定`INCOMING`為音軌來記錄`INCOMING`音軌。
如果您想要記錄發起人聽到的所有`OUTGOING`內容，您可以透過將 **call-id-1 指定為 ，並將 call-id-1** 指定`OUTGOING`為音軌來記錄音軌。 `CallId`如果您想要記錄 所`Caller`說和聽到的所有音訊，您可以透過將 指定`call-id-1`為 `CallId`，並將 `BOTH`指定為音軌來記錄`BOTH`音訊音軌。
# 範例使用案例
SIP 媒體應用程式提供通話記錄動作做為建置區塊。它們可讓您靈活地為業務使用案例建置通話記錄解決方案。下列案例說明一些常見的使用案例。
**Topics**
+ [案例 1：記錄涉及 SIP 動作的單一長度呼叫](#recording-case-1)
+ [案例 2：選擇性地記錄橋接通話中的音訊](#recording-case-2)
+ [案例 3：記錄多個通話分支](#recording-case-3)
+ [案例 4：隨需錄製搭配暫停和繼續](#on-demand-pause-resume)
## 案例 1：記錄涉及 SIP 動作的單一長度呼叫
您可以記錄來電者以及 SIP 媒體應用程式動作所產生的任何音訊，例如 [PlayAudio](play-audio.md)和 [PlayAudioAndGetDigits](play-audio-get-digits.md)動作。在記錄期間，如果發起人按下數字，記錄會擷取該數字的音調。此範例使用 `PlayAudioAndGetDigits`動作，但互動式語音回應 (IVR) 可以是一系列複雜的 SIP 媒體應用程式動作。
在此範例中，SIP 媒體應用程式會記錄發起人與 SIP 媒體應用程式本身之間的音軌。建立通話時開始錄製，並在呼叫者掛斷時停止錄製。帳單會在通話建立時開始，並在來電者掛斷時停止。
![\[在這種情況下，在發起人和應用程式本身之間記錄兩個音軌的 SIP 媒體應用程式圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/sma-recording-case-1.png)
## 案例 2：選擇性地記錄橋接通話中的音訊
您可以選擇性地記錄單一通話參與者的音軌。您可以使用此功能，僅針對特定參與者選擇性地啟用通話錄音。
在此範例中，SIP 媒體應用程式會透過將 **call-id-2** 指定為 `CallId`，並將 `INCOMING`指定為軌道，來記錄被呼叫方與 SIP 媒體應用程式本身之間的傳入音訊軌。呼叫者橋接至通話方時，通話錄音就會開始，這也是計費開始時。當被呼叫方掛斷時，錄音會停止，這也是計費結束時。此錄製只有被呼叫方的音軌。
![\[SIP 媒體應用程式選擇性地錄製一個音軌的圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/sma-recording-case-2.png)
## 案例 3：記錄多個通話分支
您可以記錄多個通話分支。例如，假設您橋接對參與者的呼叫。當該參與者掛斷時，通話會橋接到另一個參與者。您可以為這三個通話分支啟用通話記錄。
此範例顯示三個不同的錄製檔案。第一個通話的錄音會擷取發起人、您的應用程式和橋接至通話的兩個參與者之間的對話。第二個通話的錄音會擷取發起人與第一個參與者之間的對話。第三個通話的錄音會擷取發起人與第二個參與者之間的對話。
此案例會建立三個通話分支，而帳單會套用至每個通話分支的開始和結束。換句話說，系統會將三個錄音傳送到您的 S3 儲存貯體，而且會向您收取每個錄音的費用。
![\[SIP 媒體應用程式記錄多個通話分支的圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/sma-recording-case-3.png)
## 案例 4：隨需錄製搭配暫停和繼續
您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 開始、停止、暫停和繼續隨需通話錄音。您可以建置呼叫 `UpdateSipMediaApplicationCall` API 的用戶端應用程式，並叫用 SIP 媒體應用程式以傳回呼叫錄製動作。
您的最終使用者使用用戶端應用程式來控制通話錄音。例如，在呼叫中心，客服人員會使用桌面用戶端應用程式觸發隨需通話錄音動作。在呼叫中心範例中，客服人員可能會要求發起人記錄通話的許可，他們可以按一下用戶端應用程式，在發起人同意後開始記錄。在另一個範例中，發起人可能需要提供社會安全號碼 (SSN) 等資訊。不過，客服中心政策要求客服人員不應記錄客戶 SSN 等資訊。客服人員可以在客戶提供資訊時按一下應用程式來暫停錄音，然後再次按一下以繼續錄音。客服人員處理來電者的請求後，客服人員會按一下應用程式以停止錄音並掛斷通話。
在此使用案例中，SIP 媒體應用程式會記錄發起人與 SIP 媒體應用程式之間的音軌。由於`call-id-1`腿部會橋接至`call-id-2`腿部，因此系統會記錄雙腿、來電者和 呼叫的音訊。當 `UpdateSipMediaApplicationCall` API 叫用 `StartCallRecording`動作時，就會開始記錄和計費。當 `UpdateSipMediaApplicationCall` API 叫用 `StopCallRecording`動作時，記錄和計費會停止。提醒您，暫停錄音不會變更其持續時間，而且會向您收取所有暫停的費用。
![\[SIP 媒體應用程式隨需錄製的圖表，錄製已暫停並恢復。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/sma-recording-on-demand.png)
# SIP 媒體應用程式的通話記錄動作
您可以在來自 SIP 媒體應用程式的 AWS Lambda 函數的回應中指定不同的通話錄音動作。下列主題提供範例程式碼，並說明如何使用 動作。
**Topics**
+ [StartCallRecording](start-call-recording.md)
+ [StopCallRecording](stop-call-recording.md)
+ [PauseCallRecording](pause-call-recording.md)
+ [ResumeCallRecording](resume-call-recording.md)
# StartCallRecording
`StartCallRecording` 動作會開始記錄通話分支。您可以隨需或回應 SIP 事件，在 SIP 媒體應用程式中開始通話錄音。
+ 若要開始隨需記錄通話，您可以使用 `UpdateSipMediaApplication` API 來叫用應用程式並傳回 `StartCallRecording`動作。
+ 若要開始通話錄音以回應 SIP 事件，您會在應用程式中傳回 `StartCallRecording`動作。
您可以指定要記錄傳入腿部、傳出腿部或兩者的音軌。下列各節說明如何使用 `StartCallRecording`動作。
**注意**
使用此功能進行的錄製可能受到有關記錄電子通訊的法律和法規的約束。您和您的最終使用者有責任遵守有關記錄的所有適用法律，包括適當地通知記錄工作階段或通訊中的所有參與者正在記錄工作階段或通訊，並取得他們的同意。
**Topics**
+ [請求 StartCallRecording 動作](#request-start)
+ [指定錄製目的地](#recording-destination)
+ [授予 Amazon S3 儲存貯體許可](#grant-s3-perms)
+ [動作成功回應](#action-successful)
+ [動作錯誤回應](#action-error)
## 請求 StartCallRecording 動作
下列範例示範如何請求 `BOTH`軌跡`StartCallRecording`的動作。
```
{
"SchemaVersion": "1.0",
"Actions": [
{
"Type": "StartCallRecording",
"Parameters":
{
"CallId": "call-id-1",
"Track": "BOTH",
"Destination":
{
"Type": "S3",
"Location": "valid-bucket-name-and-optional-prefix"
}
}
}
]
}
```
**CallId**
*描述* – `CallId` AWS Lambda 函數調用 `CallDetails` 中的參與者描述
*允許的值* – 有效的呼叫 ID
*必要* – 是
*預設值* — 無
**追蹤**
*描述* – 通話錄音`Track`的音訊。
*允許的值* – `INCOMING`、 `BOTH`或 `OUTGOING`
*必要* – 是
*預設值* — 無
**Destination.Type**
*描述* – 目的地的類型。僅允許 Amazon S3。
*允許的值* – Amazon S3
*必要* – 是
*預設值* — 無
**Destination.Location**
*描述* – 有效的 Amazon S3 儲存貯體和選用的 Amazon S3 金鑰字首。儲存貯體必須具有 Amazon Chime SDK Voice Connector 服務主體的許可，https：//voiceconnector.chime.amazonaws.com。
*允許的值* – Amazon Chime SDK 對 和 動作具有權限的有效 Amazon S3 路徑。 `s3:PutObject` `s3:PutObjectAcl`
*必要* – 是
*預設值* — 無
## 指定錄製目的地
Amazon Chime SDK 會將通話錄音傳送到您的 Amazon S3 儲存貯體。儲存貯體必須屬於 AWS 您的帳戶。您可以在 `StartCallRecording`動作的 `Destination` 參數中指定儲存貯體的位置。`Destination` 參數中的 `Type` 欄位必須是 `S3`。`Location` 欄位包含您的 Amazon S3 儲存貯體，以及傳遞通話記錄的選用物件金鑰字首。
SIP 媒體應用程式使用指定的 `Location`、通話分支的日期和時間、交易 ID 和通話 ID 來格式化 Amazon S3 物件金鑰。`StartCallRecording` 動作回應會傳回完整的 Amazon S3 物件金鑰。
當您在 `Location` 欄位中只提供 Amazon S3 儲存貯體時，SIP 媒體應用程式會將預設字首 附加`Amazon-Chime-SMA-Call-Recordings`至 Amazon S3 路徑。SIP 媒體應用程式也會附加呼叫開始時間的年、月和日，以協助組織錄音。下列範例顯示具有預設字首的 Amazon S3 路徑的一般格式。此範例使用 `myRecordingBucket`做為 `Location`值。
```
myRecordingBucket/Amazon-Chime-SMA-Call-Recordings/2019/03/01/2019–03–01–17–10–00–010_c4640e3b–1478–40fb-8e38–6f6213adf70b_7ab7748e–b47d–4620-ae2c–152617d3333c.wav
```
下列範例顯示通話記錄 Amazon S3 路徑中呈現的資料。
```
s3Bucket/Amazon-Chime-SMA-Call-Recordings/year/month/date/year-month-date-hour-minute-second-millisecond_transactionId_callId.wav
```
當您在 `Location` 欄位中提供 Amazon S3 儲存貯體和物件金鑰字首時，SIP 媒體應用程式會使用目的地 Amazon S3 路徑中的物件金鑰字首，而非預設字首。下列範例顯示使用 字首記錄 Amazon S3 路徑的一般格式。例如，您可以將 myRecordingBucket/technicalSupport/english 指定為 `Location`。
```
myRecordingBucket/technicalSupport/english/2019/03/01/2019–03–01–17–10–00–010_c4640e3b1478–40fb–8e38-6f6213adf70b_7ab7748e–b47d–4620–ae2c–152617d3333c.wav
```
下列範例顯示 Amazon S3 路徑中的資料。
```
s3Bucket/yourObjectKeyPrefix/year/month/date/year-month-date-hour-minute-second-millisecond_transactionId_callId.wav
```
傳送至 Amazon S3 儲存貯體的錄音包含有關通話分支的其他 [ Amazon S3 物件中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。下表列出支援的 Amazon S3 物件中繼資料。
| 名稱 | 描述 |
| --- | --- |
| transaction-id | 電話的交易 ID |
| call-id | AWS Lambda 函數呼叫的 CallDetails 中參與者的 CallIdCallId |
| recording-duration | 通話記錄持續時間，以秒為單位 |
| recording-audio-file-format | 以網際網路媒體類型表示的通話錄音音訊檔案格式 |
## 授予 Amazon S3 儲存貯體許可
您的目的地 Amazon S3 儲存貯體必須屬於與您應用程式相同的 AWS 帳戶。此外， 動作必須向 Amazon Chime SDK Voice Connector 服務主體 授予 `s3:PutObject`和 `s3:PutObjectAcl`許可`voiceconnector.chime.amazonaws.com`。下列範例會授予適當的許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SIP media applicationRead",
"Effect": "Allow",
"Principal": {
"Service": "voiceconnector.chime.amazonaws.com"
},
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::bucket-name/*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
}
}
}
]
}
```
------
PSTN 音訊服務會代表 Sip Media Application 讀取和寫入您的 S3 儲存貯體。若要避免[混淆代理人問題](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)，您可以將 S3 儲存貯體許可限制為單一 SIP 媒體應用程式。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SIP media applicationRead",
"Effect": "Allow",
"Principal": {
"Service": "voiceconnector.chime.amazonaws.com"
},
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::bucket-name/*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333",
"aws:SourceArn": "arn:aws:chime:us-east-1:111122223333:sma/sip-media-application-id"
}
}
}
]
}
```
------
## 動作成功回應
當通話錄音在通話腿上成功啟動時，SIP 媒體應用程式會使用 `ACTION_SUCCESSFUL` 事件類型叫用 AWS Lambda 函數。回應中會傳回通話錄音的位置。
```
{
"SchemaVersion": "1.0",
"Sequence": INTEGER,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type" : "StartCallRecording",
"Parameters": {
"CallId": "call-id-1",
"Track": "BOTH",
"Destination": {
"Type": "S3",
"Location": "valid-bucket-name"
}
}
"CallRecordingDestination": {
"Type": "S3",
"Location": "call-recording-bucket-and-key"
}
}
"CallDetails": {
...
}
}
```
## 動作錯誤回應
對於驗證錯誤，SIP 媒體應用程式會使用適當的錯誤訊息呼叫 AWS Lambda 函數。下表列出錯誤訊息。
| 錯誤 | 訊息 | Reason |
| --- | --- | --- |
| `InvalidActionParameter` | `CallId` 動作的 參數無效 | 任何參數都是無效的。 |
| `SystemException` | 執行 動作時發生系統錯誤。 | 執行 動作時發生另一種類型的系統錯誤。 |
當動作無法在通話腿上記錄媒體時，SIP 媒體應用程式會使用`ActionFailed`事件類型叫用 AWS Lambda 函數。
下列範例顯示典型的錯誤回應。
```
{
"SchemaVersion": "1.0",
"Sequence": 5,
"InvocationEventType": "ACTION_FAILED",
"ActionData": {
"Type" : "StartCallRecording",
"Parameters": {
"CallId": "call-id-1",
"Track": "BOTH",
"Destination": {
"Type": "S3",
"Location": "valid-bucket-name"
}
}
"Error": "NoAccessToDestination: Error while accessing destination"
}
"CallDetails": {
...
}
}
```
請參閱 GitHub 上的工作範例：https：//[https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# StopCallRecording
`StopCallRecording` 動作會停止記錄通話分支。當呼叫結束時，錄製會自動停止，而且您的應用程式不需要明確傳回`StopCallRecording`動作。一旦通話分支的錄音停止，就無法再次開始，且錄音會交付至 `StartCallRecording`動作中指定的目的地。
下列範例會停止記錄`call-id-1`通話分支。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "StopCallRecording",
"Parameters": {
"CallId": "call-id-1"
}
}
]
}
```
**CallId**
*描述* – `CallId` AWS Lambda 函數調用 `CallDetails` 中的參與者描述
*允許的值* – 有效的呼叫 ID
*必要* – 是
*預設值* — 無
請參閱 GitHub 上的工作範例：https：//[https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# PauseCallRecording
`PauseCallRecording` 動作會暫停通話分支的錄製。每次暫停錄音時，錄音都會擷取表示暫停的音調。當您暫停時，錄製會繼續，但只會擷取靜音。暫停錄製不會影響錄製的總持續時間。您可以視需要暫停和繼續錄製。
下列範例會暫停錄製。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "PauseCallRecording",
"Parameters": {
"CallId": "call-id-1"
}
}
]
}
```
**CallId**
*描述* – `CallId` AWS Lambda 函數調用 `CallDetails` 中的參與者描述
*允許的值* – 有效的呼叫 ID
*必要* – 是
*預設值* — 無
請參閱 GitHub 上的工作範例：https：//[https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# ResumeCallRecording
`ResumeCallRecording` 動作會繼續記錄通話分支。在記錄重新啟動之前，會播放簡短的音調。您可以在通話期間暫停和繼續錄製多次。
下列範例會繼續錄製。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "ResumeCallRecording",
"Parameters": {
"CallId": "call-id-1"
}
}
]
}
```
**CallId**
*描述* – `CallId` AWS Lambda 函數調用 `CallDetails` 中的參與者描述
*允許的值* – 有效的呼叫 ID
*必要* – 是
*預設值* — 無
請參閱 GitHub 上的工作範例：https：//[https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# CallAndBridge
建立對 PSTN 電話號碼的外撥通話，或設定為 Amazon Chime SDK Voice Connector 或 Amazon Chime SDK Voice Connector 群組的 SIP 幹線，然後將其與現有通話橋接。您在撥打電話號碼`PSTN`和撥打 SIP 中繼線`AWS`時使用 。
現有呼叫可以是使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html) API 建立的外撥呼叫，或由使用`NewInboundCall`事件呼叫函數的 SIP 規則建立的 AWS Lambda 傳入呼叫。當您對語音連接器或語音連接器群組端點實作`CallAndBridge`動作時，您必須指定語音連接器或語音連接器群組的 Amazon Resource Number (ARN)。
您也可以將自訂 SIP 標頭新增至外撥通話和 AWS Lambda 函數。自訂標頭可讓您傳遞樓層號碼和郵遞區號等值。如需自訂標頭的詳細資訊，請參閱 [在 Amazon Chime SDK PTSN 音訊服務中使用 SIP 標頭](sip-headers.md)。
使用 呼叫和橋接函數時，請務必注意，每個呼叫都會計入用於計算 SMA 作用中呼叫限制的作用中並行呼叫計數。考慮到這一點，在管理呼叫和橋接的 SMA 作用中通話限制時，您應該計算每 1 個呼叫和橋接動作的 2 個呼叫。如需詳細資訊，請參閱 中的 [SIP 中繼和語音配額](https://docs.aws.amazon.com/general/latest/gr/chime-sdk.html#chm-sdk-pstn-quotas)*AWS 一般參考*。
下列範例程式碼顯示橋接至 PSTN 端點的典型動作。
```
{
"SchemaVersion": "1.0",
"Actions": [{
"Type": "CallAndBridge",
"Parameters": {
"CallTimeoutSeconds": 30,
"CallerIdNumber": "e164PhoneNumber", // required
"Endpoints": [{
"BridgeEndpointType": "PSTN", // required
"Uri": "e164PhoneNumber", // required
}],
}
}
]
}
```
下列範例顯示使用語音連接器或語音連接器群組的典型動作，以及自訂 SIP 標頭。
```
{
"SchemaVersion":"1.0",
"Actions":[
{
"Type":"CallAndBridge",
"Parameters":{
"CallTimeoutSeconds":30,
"CallerIdNumber": "e164PhoneNumber", // required
"RingbackTone": { // optional
"Type": "S3",
"BucketName": "s3_bucket_name",
"Key": "audio_file_name"
},
"Endpoints":[
{
"BridgeEndpointType":"AWS", // enum type, required
"Arn":"arn:aws:chime:us-east-1:0123456789101:vc/abcdefg1hijklm2nopq3rs" //VC or VCG ARN, required for AWS endpoints
"Uri":"ValidString", // required, see description below
}
],
"SipHeaders": {
"x-String":"String"
}
}
}
]
}
```
**CallTimeoutSeconds**
*描述* – 呼叫逾時之前的間隔。計時器會在呼叫設定時啟動。
*允許的值* – 介於 1 到 120 之間，包含
*必要* – 否
*預設值* – 30
**CallerIdNumber**
*描述* – 屬於客戶的號碼，或 A Leg 的寄件者號碼
*允許的值* – E.164 格式的有效電話號碼
*必要* – 是
*預設值* — 無
**Endpoints**
*描述* – 呼叫的端點
*允許的值*：
+ `BridgeEndpointType` – `AWS`適用於語音連接器和語音連接器群組，否則為 `PSTN`。
+ `Arn` – Voice Connector 或 Voice Connector 群組的 ARN。只有在使用 `AWS`做為 時才需要`BridgeEndpointType`。
+ `Uri` – URI 值取決於端點的類型。
對於`PSTN`端點，URI 必須是有效的 E.164 電話號碼。
針對`AWS`端點，URI 值會設定 `user`的一部分`Request-URI`。您必須使用[增強的 Backus-Naur 格式](https://datatracker.ietf.org/doc/html/rfc2234)。必要長度：介於 1 到 36 之間，包含 。使用下列值： `a-z, A-Z, 0-9, &, =, +, $, /, %, -, _, !, ~, *, `(`,`)、 (`.`)
的主機值`Request-URI`衍生自目標語音連接器的傳入路由。下列範例顯示具有 `AWS`端點`CallAndBridge`的動作。
```
{
"SchemaVersion":"1.0",
"Actions":[
{
"Type":"CallAndBridge",
"Parameters":{
"CallTimeoutSeconds":30,
"CallerIdNumber": "+18005550122",
"Endpoints":[
{
"BridgeEndpointType":"AWS",
"Arn":"arn:aws:chime:us-east-1:0123456789101:vc/abcdefg1hijklm2nopq3rs",
"Uri":"5550"
}
],
"SipHeaders": {
"x-String":"String"
}
}
}
]
}
```
如需傳入路由和語音連接器的詳細資訊，請參閱[編輯 Amazon Chime SDK Voice Connector 設定](https://docs.aws.amazon.com/chime-sdk/latest/ag/edit-voicecon.html)。
*必要* – 是
*預設值* — 無
**SipHeaders**
*描述* – 可讓您傳遞其他值。僅使用 與`AWS`端點類型。
*允許的值* – 有效的 SIP 標頭
*必要* – 否
*預設值* — 無
下列範例顯示使用 PSTN 端點的成功`CallAndBridge`動作：
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "CallAndBridge",
"Parameters": {
"CallTimeoutSeconds": 30,
"CallerIdNumber": "e164PhoneNumber",
"Endpoints":[
{
"BridgeEndpointType": "PSTN",
"Uri": "e164PhoneNumber"
}
],
"CallId": "call-id-1"
}
},
"CallDetails":{
.....
.....
"Participants":[
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
.....
"Status": "Connected"
},
{
"CallId": "call-id-2",
"ParticipantTag": "LEG-B",
.....
"Status": "Connected"
}
]
}
}
```
下列範例顯示失敗`CallAndBridge`的動作。
```
{
"SchemaVersion": "1.0",
"Sequence":2,
"InvocationEventType": "ACTION_FAILED",
"ActionData":{
"Type": "CallAndBridge",
"Parameters":{
"CallTimeoutSeconds": 30,
"CallerIdNumber": "e164PhoneNumber",
"Endpoints": [
{
"BridgeEndpointType": "PSTN",
"Uri": "e164PhoneNumber"
}
],
"CallId": "call-id-1"
},
"ErrorType": "CallNotAnswered",
"ErrorMessage": "Call not answered"
},
"CallDetails":{
.....
.....
"Participants":[
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
.....
}
]
}
}
```
## 呼叫流程
`CallAndBridge` 動作為現有的通話腳提供不同的通話訊號和音訊體驗，具體取決於參數和腳是否已連接。
下圖顯示已連接傳入通話分支 A 時具有不同參數的通話流程。
![\[透過 CallAndBridge動作的已接聽呼叫流程。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/call-bridge-ans-2.png)
下圖顯示未接聽通話的通話流程。
![\[透過 CallAndBridge動作進行未接聽呼叫的流程。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/SMA_Bridging_NotAns.png)
**其他詳細資訊**
請記住這些有關 `CallAndBridge`動作的事實。
+ `CallTimeoutSeconds` – 此計時器會在 B-Leg 上傳送 SIP 邀請時啟動。您可以設定所需的目標值，但上游電信業者可以忽略此值。
+ `CallerIdNumber` – 此電話號碼必須屬於客戶，或是 A-Leg 的寄件者號碼。
+ **掛斷行為和邊緣案例** – 如果一個通話分支掛斷，另一個通話分支不會自動掛斷通話。將`Hangup`事件傳送至 AWS Lambda 函數時，必須獨立中斷剩餘的腿部連線。如果通話腿保持停滯不前，通話會計費，直到掛斷為止。例如，以下案例可能會導致意外費用：
+ 您嘗試橋接到目的地電話號碼。目的地忙碌中，並直接將通話傳送至語音信箱。從音訊服務的角度來看，前往語音信箱是接聽的通話。A-Leg 掛斷電話，但 B-Leg 會繼續接聽語音信箱訊息。當 B-Leg 接聽時，您會收到帳單。
+ 最佳實務是使用 AWS Lambda 函數或呼叫另一端的一方，獨立掛斷每個呼叫腳。
+ **帳單** – 使用 時需支付下列費用`CallAndBridge`：
+ 對 PSTN 建立的每個呼叫分支的作用中呼叫分鐘數 (A-Leg、B-Leg 等）。
+ Audio Service 用量分鐘。
請參閱 GitHub 上的工作範例：
+ [https://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)
+ [https://github.com/aws-samples/amazon-chime-sma-call-forwarding](https://github.com/aws-samples/amazon-chime-sma-call-forwarding)
+ [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# Hangup
使用 將`Hangup`值`SipStatusCode`傳送至呼叫的任何分支。
當音訊服務對通話分支執行`Hangup`動作時：
+ 對於只有一個呼叫分支的呼叫，SIP 媒體應用程式會使用`HANGUP`事件叫用 AWS Lambda 函數，並忽略回應。然後，通話會中斷連線。
+ 對於橋接到另一個呼叫腿部 (B 區段） 的呼叫腿部 (A 區段），如果`Hangup`動作與橋接呼叫腿部 (B 區段） 相關聯，則 PSTN 音訊服務會中斷橋接呼叫腿部的連線，然後呼叫 Lambda 函數與腿部 B `HANGUP`的事件。PSTN 音訊服務接著會執行從該 Lambda 呼叫傳回的任何動作。
+ 對於橋接到另一個呼叫腿部 (Leg B) 的呼叫腿部 (Leg A)，如果`Hangup`動作與原始呼叫腿部 (Leg A) 相關聯，則 PSTN 音訊服務會中斷與原始呼叫腿部的連線，然後呼叫 Lambda 函數與腿部 A `HANGUP`的事件。PSTN 音訊服務接著會執行從該 Lambda 呼叫傳回的任何動作。
+ 對於使用 `JoinMeeting`動作加入會議的通話分支，如果`Hangup`動作與會議分支相關聯 （通常是 B 分支），則發起人會中斷與會議的連線，並接收該`Hangup`動作`ACTION_SUCCESSFUL`的事件。
下列範例顯示典型`Hangup`動作。
```
{
"Type": "Hangup",
"Parameters": {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"SipResponseCode": "0"
}
}
```
**CallId**
*描述* – `CallId` AWS Lambda 函數調用 `CallDetails` 中的參與者描述
*允許的值* – 有效的呼叫 ID
*必要* – 否
*預設值* — 無
**ParticipantTag**
*描述* – `ParticipantTag` 中其中一個已連線參與者的描述 `CallDetails`
*允許的值* – `LEG-A`或 `LEG-B`
*必要* – 否
*預設值* - 如果您指定 `ParticipantTag` ，則叫用`callLeg`忽略的預設值 `CallId`
**SipResponseCode**
*描述* – 任何支援的 SIP 回應代碼
*允許值* – 480–無法使用；486–忙碌；0–正常終止
*必要* – 否
*預設值* – 0
使用者結束呼叫後，SIP 媒體應用程式會使用 中列出的程式碼叫用 AWS Lambda 函數[使用 Amazon Chime SDK PSTN 音訊服務結束通話](case-5.md)。
請參閱 GitHub 上的工作範例：
+ [https://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)
+ [https://github.com/aws-samples/amazon-chime-sma-call-forwarding](https://github.com/aws-samples/amazon-chime-sma-call-forwarding)
+ [https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# JoinChimeMeeting
提供出席者加入權杖，以加入 Amazon Chime SDK 會議。若要執行此操作，您可以呼叫 AWS [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html)和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateAttendee.html) APIs 來取得權杖，並在 動作中傳遞權杖。請參閱以下範例。
**注意**
您無法在橋接通話上執行此動作。
```
{
"Type": "JoinChimeMeeting",
"Parameters": {
"JoinToken": "meeting-attendee-join-token",
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"MeetingId": "meeting-id"
}
}
```
**JoinToken**
*描述* – Amazon Chime SDK 會議出席者的有效聯結字符
*允許的值* – 有效的聯結字符
*必要* – 是
*預設值* — 無
**CallId**
*描述* – `CallId` AWS Lambda 函數調用 中的參與者`CallDetails`描述
*允許的值* – 有效的呼叫 ID
*必要* – 否
*預設值* — 無
**ParticipantTag**
*描述* – `ParticipantTag` 中其中一個已連線參與者的描述 `CallDetails`
*允許的值* – `LEG-A`
*必要* – 否
*預設值* – 如果您指定 ，則叫`ParticipantTag`用`callLeg`忽略的預設值 `CallId`
**MeetingId**
*描述* – 與 相關聯的有效 Amazon Chime SDK 會議 ID`JoinToken`。如果會議是使用 [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間中的 API 建立的，則不需要會議 ID。如果會議是使用 [Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) 命名空間中的 API 建立的，則需要會議 ID。使用用來建立會議的 API 端點加入會議。
*允許的值* – 有效的會議 ID。
*必要* – 否。
*預設值* – 無。
SIP 媒體應用程式一律會在執行此動作後叫用 AWS Lambda 函數。它傳回 `ACTION_SUCCESSFUL`或 `ACTION_FAILED` 調用事件類型。下列範例顯示成功的調用事件結構。
```
{
"SchemaVersion": "1.0",
"Sequence": 4,
"InvocationEvent": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "JoinChimeMeeting",
"Parameters": {
"JoinToken": "meeting-attendee-join-token",
"CallId": "call-id-1"
"ParticipantTag": "LEG-A"
}
}
"CallDetails": {
...
}
}
```
**錯誤處理**
當橋接會議時發生驗證錯誤時，SIP 應用程式會使用下表中顯示的其中一個錯誤訊息呼叫其 AWS Lambda 函數。
| 錯誤 | 訊息 | 原因 |
| --- | --- | --- |
| `InvalidActionParameter` | `JoinToken` 參數值無效。 | 動作的任何其他參數無效或遺失。 |
| `SystemException` | 執行動作時發生系統錯誤。 | 執行 動作時發生另一種類型的系統錯誤。 |
下列範例顯示典型的失敗事件。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEvent": "ACTION_FAILED",
"ActionData": {
"Type": "JoinChimeMeeting",
"Parameters": {
"JoinToken": "meeting-attendee-join-token",
"CallId": "call-id-1",
"ParticipantTag": "LEG-A"
},
"Error": "ErrorJoiningMeeting: Error while joining meeting."
}
"CallDetails": {
...
}
}
```
請參閱 GitHub 上的工作範例：https：//[https://github.com/aws-samples/amazon-chime-sma-update-call](https://github.com/aws-samples/amazon-chime-sma-update-call)
# ModifyChimeMeetingAttendee （靜音和取消靜音音訊）
允許 SIP 媒體應用程式透過提供 Amazon Chime SDK 會議 ID 和出席者清單來修改電話出席者的狀態。
**注意**
此動作目前支援電話語音出席者的靜音和取消靜音操作。此外，使用者必須使用 `JoinChimeMeeting`動作加入會議。此動作可以在 `participantTag=“LEG-B”`或對應的 上執行`CallId`。
此動作僅適用於從 SIP 媒體應用程式加入至 `"+`*13605550122*`"`、LEG-B 的 callLeg，或從 SIP 媒體應用程式加入至會議的腿。
```
{
"SchemaVersion": "1.0",
"Actions": [
{
"Type" : "ModifyChimeMeetingAttendees",
"Parameters" : {
"Operation": "Mute",
"MeetingId": "meeting-id",
"CallId": "call-id",
"ParticipantTag": LEG-B",
"AttendeeList": ["attendee-id-1", "attendee-id-2"]
}
}
]
}
```
**Operation**
*描述* – 在出席者清單上執行的操作
*允許的值* – 靜音、取消靜音
*必要* – 是
*預設值* — 無
**MeetingId**
*描述* – 出席者所屬之會議的 ID
*允許的值* – 有效的會議 ID。靜音或取消靜音的人員也必須屬於會議。
*必要* – 是
*預設值* — 無
**CallId**
*描述* – 出席者所屬之會議的 ID
*允許的值* – 有效的呼叫 ID。
*必要* – 否
*預設值* — 無
**ParticipantTag**
*描述* – 指派給出席者的標籤。
*允許的值* – 有效的標籤。
*必要* – 否
*預設值* — 無
**AttendeeList**
*描述* – 要靜音或取消靜音的出席者 IDs 清單
*允許的值* – 有效出席者 IDs的清單
*必要* – 是
*預設值* – 無，上限為 100
執行此動作後，Audio Service 一律會使用 `ACTION_SUCCESSFUL`或 `ACTION_FAILED`叫用事件類型叫用 AWS Lambda 函數。下列範例程式碼顯示典型`ACTION_SUCCESSFUL`的調用事件。
```
{
"SchemaVersion": "1.0",
"Sequence": INTEGER,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type" : "ModifyChimeMeetingAttendees",
"Parameters" : {
"Operation": "Mute",
"MeetingId": "meeting-id",
"CallId": "call-id",
"ParticipantTag": "LEG-B",
"AttendeeList": ["attendee-id-1", "attendee-id-2"]
}
}
"CallDetails": {
...
}
}
```
**錯誤處理**
在指令參數無效或 API 失敗的情況下，SIP 媒體應用程式會呼叫 AWS Lambda 函數，其中包含失敗指令或 API 特有的錯誤訊息。
| 錯誤 | 訊息 | Reason |
| --- | --- | --- |
| `InvalidActionParameter` | `ModifyChimeMeetingAttendees Operation` 參數值無效 | `Operation` 值必須是靜音或取消靜音。 |
| | 會議 ID 參數值無效。 | 會議 ID 為空。 |
| | 出席者清單參數值無效。 | 出席者 ID 清單為空，或超過上限 100。 |
| | 呼叫的動作無效。 | 呼叫不會橋接。 |
| | 通話未連線至 Chime 會議。 | 出席者未連線至 Chime 會議。 |
| | 一或多個出席者不屬於此會議。所有出席者都必須是此會議的一部分。 | 出席者無權修改會議的出席者。 |
| `SystemException` | 執行動作時發生系統錯誤。 | 執行 動作時發生系統錯誤。 |
下列範例程式碼顯示典型的失敗事件：
```
{
"SchemaVersion": "1.0",
"Sequence": INTEGER,
"InvocationEventType": "ACTION_FAILED",
"ActionData": {
"Type" : "ModifyChimeMeetingAttendees",
"Parameters" : {
"Operation": "Mute",
"MeetingId": "meeting-id",
"CallId": "call-id",
"ParticipantTag": "LEG-B",
"AttendeeList": ["attendee-id-1", "attendee-id-2"]
},
"ErrorType": "",
"ErrorMessage": "",
"ErrorList": []
}
"CallDetails": {
...
}
}
```
請參閱 GitHub 上的工作範例：
+ https：//[https://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)。
+ [https://github.com/aws-samples/amazon-chime-sma-update-call](https://github.com/aws-samples/amazon-chime-sma-update-call)
# Pause
在指定的時間內暫停通話。
```
{
"Type": "Pause",
"Parameters": {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"DurationInMilliseconds": "3000"
}
}
```
**CallId**
*描述* – `CallId` AWS Lambda 函數調用 `CallDetails` 中的參與者描述
*允許的值* – 有效的呼叫 ID
*必要* – 否
*預設值* — 無
**ParticipantTag**
*描述* – `ParticipantTag` 中其中一個已連線參與者的描述 `CallDetails`
*允許的值* – `LEG-A`或 `LEG-B`
*必要* – 否
*預設值* - 如果您指定 `ParticipantTag` ，則叫用`callLeg`忽略的預設值 `CallId`
**DurationInMilliseconds**
*描述* – 暫停持續時間，以毫秒為單位
*允許的值* – 整數 >0
*必要* – 是
*預設值* — 無
請參閱 GitHub 上的工作範例：
+ [https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# PlayAudio
在通話的任何腿上播放音訊檔案。音訊可以重複任意次數。可使用 中設定的 DTMF 數字來終止進行中音訊`PlaybackTerminators`。
目前，Amazon Chime SDK 僅支援從 Amazon Simple Storage Service (Amazon S3) 儲存貯體播放音訊檔案。S3 儲存貯體必須屬於與 SIP 媒體應用程式相同的 AWS 帳戶。此外，您必須將 `s3:GetObject`許可授予 Amazon Chime SDK Voice Connector 服務主體。您可以使用 S3 主控台或命令列界面 (CLI) 來執行此操作。
下列程式碼範例顯示典型的儲存貯體政策。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SMARead",
"Effect": "Allow",
"Principal": {
"Service": "voiceconnector.chime.amazonaws.com"
},
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::bucket-name/*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
}
}
}
]
}
```
------
Audio Service 會代表 Sip Media Application 讀取和寫入您的 S3 儲存貯體。若要避免[混淆代理人問題](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)，您可以限制 S3 儲存貯體存取單一 SIP 媒體應用程式。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SMARead",
"Effect": "Allow",
"Principal": {
"Service": "voiceconnector.chime.amazonaws.com"
},
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::bucket-name/*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333",
"aws:SourceArn": "arn:aws:chime:us-east-1:111122223333:sma/sip-media-application-id"
}
}
}
]
}
```
------
下列程式碼範例顯示典型的動作。
```
{
"Type": "PlayAudio",
"Parameters": {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"PlaybackTerminators": ["1", "8", "#"],
"Repeat": "5",
"AudioSource": {
"Type": "S3",
"BucketName": "valid-S3-bucket-name",
"Key": "wave-file.wav"
}
}
}
```
**CallID**
*描述* – 中的`CallId`參與者`CallDetails`。
*允許的值* – 有效的呼叫 ID。
*必要* – 否，如果 `ParticipantTag` 存在。
*預設值* – 無。
**ParticipantTag**
*描述* – `ParticipantTag` 中其中一個連線參與者的描述`CallDetails`。
*允許的值* – `LEG-A`或 `LEG-B`。
*必要* – 否，如果 `CallId` 存在。
*預設值* – 調用 `ParticipantTag` 的 `callLeg`。如果您指定 ，則忽略`CallId`。
**PlaybackTerminator**
*描述* – 使用來自使用者的 DTMF 輸入終止進行中音訊
*允許值* – 下列值的陣列：「0」、「1」、「2」、「3」、「4」、「5」、「6」、「7」、「8」、「9」、「\$1」、「\$1」
*必要* – 否
*預設值* — 無
**Repeat**
*描述* – 重複指定次數的音訊
*允許的值* – 大於零的整數
*必要* – 否
*預設值* – 1
**AudioSource.Type**
*描述* – 音訊檔案的來源類型。
*允許的值* – S3。
*必要* – 是。
*預設值* – 無。
**AudioSource.BucketName**
*描述* – 對於 S3 來源類型，S3 儲存貯體必須屬於與 SIP 應用程式相同的 AWS 帳戶。儲存貯體必須能夠存取 Amazon Chime SDK Voice Connector 服務主體，也就是 voiceconnector.chime.amazonaws.com。
*允許的值* – Amazon Chime SDK 可存取`s3:GetObject`動作的有效 S3 儲存貯體。
*必要* – 是。
*預設值* – 無。
**AudioSource.key**
*描述* – 對於 S3 來源類型，來自`AudioSource.BucketName`屬性中指定之 S3 儲存貯體的檔案名稱。
*允許的值* – 有效的音訊檔案。
*必要* – 是。
*預設值* – 無。
SIP 媒體應用程式會嘗試播放來源 URL 的音訊。您可以使用大小不超過 50 MB 的原始未壓縮 PCM .wav 檔案。Amazon Chime SDK 建議 8 KHz 單機。
當撥號計劃中的最後一個指示為 `PlayAudio`且檔案完成播放時，或者使用者使用按鍵停止播放時，應用程式會使用下列範例所示的事件叫用 AWS Lambda 函數。
```
{
"SchemaVersion": "1.0",
"Sequence": INTEGER,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "PlayAudio",
"Parameters" : {
"CallId": "call-id-1",
"AudioSource": {
"Type": "S3",
"BucketName": "valid-S3-bucket-name",
"Key": "wave-file.wav",
}
}
}
```
在終止數字停止音訊後，不會重複音訊。
**錯誤處理**
當驗證檔案包含錯誤，或執行動作時發生錯誤時，SIP 媒體應用程式會使用適當的錯誤碼呼叫 AWS Lambda 函數。
| 錯誤 | 訊息 | Reason |
| --- | --- | --- |
| `InvalidAudioSource` | 音訊來源參數無效。 | 此錯誤可能因多種原因而發生。例如，由於許可問題或 URL 問題，SIP 媒體應用程式無法存取 檔案。或者，音訊檔案可能會因格式、持續時間、大小等而驗證失敗。 |
| `SystemException` | 執行動作時發生系統錯誤。 | 執行 動作時發生另一個系統錯誤。 |
| `InvalidActionParameter` | 動作的 CallId 或 ParticipantTag 參數無效。 | 動作包含無效的參數。 |
下列程式碼範例顯示典型的調用失敗。
```
{
"SchemaVersion": "1.0",
"Sequence": 2,
"InvocationEventType": "ACTION_FAILED",
"ActionData": {
"Type": "PlayAudio",
"Parameters" : {
"CallId": "call-id-1",
"AudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "audio-file.wav"
},
},
"ErrorType": "InvalidAudioSource",
"ErrorMessage": "Audio Source parameter value is invalid."
}
"CallDetails": {
...
}
}
```
請參閱 GitHub 上的工作範例：
+ https：//[https://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)。
+ [https://github.com/aws-samples/amazon-chime-sma-call-forwarding](https://github.com/aws-samples/amazon-chime-sma-call-forwarding)
+ [https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
+ [https://github.com/aws-samples/amazon-chime-sma-update-call](https://github.com/aws-samples/amazon-chime-sma-update-call)
# PlayAudioAndGetDigits
播放音訊並收集 DTMF 數字。如果發生故障，例如使用者未輸入正確的 DTMF 位數，動作會播放「失敗」音訊，然後重播主要音訊，直到 SIP 媒體應用程式耗盡 `Repeat` 參數中定義的嘗試次數。
您必須從 S3 儲存貯體播放音訊檔案。S3 儲存貯體必須屬於與 SIP 媒體應用程式相同的 AWS 帳戶。此外，您必須將 `s3:GetObject`許可授予 [ Amazon Chime SDK Voice Connector 服務主體](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) `voiceconnector.chime.amazonaws.com`。您可以使用 S3 主控台或 CLI 來執行此操作。
下列程式碼範例顯示典型的 S3 儲存貯體政策。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SMARead",
"Effect": "Allow",
"Principal": {
"Service": "voiceconnector.chime.amazonaws.com"
},
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::bucket-name/*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
}
}
}
]
}
```
------
Audio Service 會代表 Sip Media Application 讀取和寫入 S3 儲存貯體。若要避免[混淆代理人問題](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)，您可以限制 S3 儲存貯體存取單一 SIP 媒體應用程式。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SMARead",
"Effect": "Allow",
"Principal": {
"Service": "voiceconnector.chime.amazonaws.com"
},
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::bucket-name/*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333",
"aws:SourceArn": "arn:aws:chime:us-east-1:111122223333:sma/sip-media-application-id"
}
}
}
]
}
```
------
下列範例顯示典型`PlayAudioAndGetDigits`的動作。
```
{
"Type" : "PlayAudioAndGetDigits",
"Parameters" : {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A"
"InputDigitsRegex": "^\d{2}#$",
"AudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "audio-file-1.wav"
},
"FailureAudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "audio-file-failure.wav"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
}
}
```
**CallId**
*描述* – `CallId` AWS Lambda 函數調用 `CallDetails` 中的參與者描述
*允許的值* – 有效的呼叫 ID
*必要* – 否
*預設值* — 無
**ParticipantTag**
*描述* – `ParticipantTag` 中其中一個已連線參與者的描述 `CallDetails`
*允許的值* – `LEG-A`或 `LEG-B`
*必要* – 否
*預設值* – 如果您指定 `ParticipantTag` ，則叫用`callLeg`忽略的預設值 `CallId`
**InputDigitsRegex**
*描述* – 規則表達式模式
*允許的值* – 有效的規則表達式模式
*必要* – 否
*預設值* — 無
**AudioSource.Type**
*描述* – 音訊檔案類型的來源類型
*允許的值* – S3 儲存貯體
*必要* – 是
*預設值* – `"S3"`
**AudioSource.BucketName**
*描述* – 對於 S3 `AudioSource.Type`值，S3 儲存貯體必須屬於與 SIP 媒體應用程式相同的 AWS 帳戶。儲存貯體 S3 必須能夠存取 [Amazon Chime SDK Voice Connector 服務主體](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) `voiceconnector.chime.amazonaws.com`。
*允許的值* – Amazon Chime SDK 具有`s3:GetObject`動作存取權的有效 S3 儲存貯體。
*必要* – 是
*預設值* — 無
**AudioSource.Key**
*描述* – `AudioSource.BucketName` S3 儲存貯體中音訊物件的金鑰名稱。
*允許的值* – 有效的音訊檔案
*必要* – 是
*預設值* — 無
**FailureAudioSource.Type**
*描述* – `FailureAudioSource.BucketName` S3 儲存貯體中音訊物件的金鑰名稱。
*允許的值* – S3
*必要* – 是
*預設值* — 無
**FailureAudioSource.BucketName**
*描述* – 對於 S3 來源類型，S3 儲存貯體必須屬於與 SIP 媒體應用程式相同的 AWS 帳戶。[Amazon Chime SDK Voice Connector 服務主體](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) `voiceconnector.chime.amazonaws.com`必須有 S3 儲存貯體的存取權。
*允許的值* – Amazon Chime SDK 具有`s3:GetObject`動作存取權的有效 S3 儲存貯體。
*必要* – 是
*預設值* — 無
**FailureAudioSource.Key**
*描述* – `FailureAudioSource.BucketName` S3 儲存貯體中音訊物件的金鑰名稱。
*允許的值* – 有效的音訊檔案
*必要* – 是
*預設值* — 無
**MinNumberOfDigits**
*描述* – 在逾時或播放「通話失敗」音訊之前要擷取的位數下限。
*允許的值* – >=0
*必要* – 否
*預設值* – 0
**MaxNumberOfDigits**
*描述* – 在停止之前擷取的位數上限，而不終止數字。
*允許的值* – >`MinNumberOfDigits`
*必要* – 否
*預設值* – 128
**TerminatorDigits**
*描述* – 使用者輸入小於 時用來結束輸入的數字 `MaxNumberOfDigits`
*允許的值* – 任何一個數字：0123456789\$1\$1
*必要* – 否
*預設值* – \$1
**InBetweenDigitsDurationInMilliseconds**
*描述* – 播放 之前，數字輸入之間的等待時間，以毫秒為單位`FailureAudio`。
*允許的值* – >0
*必要* – 否
*預設值* – 如果未指定，則預設為 `RepeatDurationInMilliseconds`值。
**Repeat**
*描述* – 嘗試取得數字的總數
*允許的值* – >0
*必要* – 否
*預設值* – 1
**RepeatDurationInMilliseconds**
*描述* – 在`Repeat`嘗試之間等待的時間，以毫秒為單位
*允許的值* – >0
*必要* – 是
*預設值* — 無
SIP 媒體應用程式一律會在執行 `PlayAudioAndGetDigits`動作後，以 `ACTION_SUCCESSFUL`或 叫用事件類型`ACTION_FAILED`叫用其 AWS Lambda 函數。當應用程式成功收集數字時，它會在 `ActionData` 物件中設定 `ReceivedDigits`值。下列範例顯示該 AWS Lambda 函數的調用事件結構。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "PlayAudioAndGetDigits",
"Parameters" : {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"InputDigitsRegex": "^\d{2}#$",
"AudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "audio-file-1.wav"
},
"FailureAudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "audio-file-failure.wav"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
},
"ErrorType": "InvalidAudioSource",
"ErrorMessage": "Audio Source parameter value is invalid."
},
"ReceivedDigits": "1234"
},
"CallDetails": {
...
}
}
```
**錯誤處理**
發生驗證錯誤時，SIP 媒體應用程式會使用 AWS Lambda 對應的錯誤訊息呼叫 函數。下表列出可能的錯誤訊息。
| 錯誤 | 訊息 | Reason |
| --- | --- | --- |
| `InvalidAudioSource` | 音訊來源參數值無效。 | 此錯誤可能因多種原因而發生。例如，由於許可問題或 S3 儲存貯體的問題，SIP 媒體應用程式無法存取 檔案。或者，音訊檔案可能會因持續時間、大小或不支援的格式而驗證失敗。 |
| `InvalidActionParameter` | `CallId` 動作的 或 `ParticipantTag` 參數無效。 | `CallId`、 `ParticipantTag`或其他 參數無效。 |
| `SystemException` | 執行 動作時發生系統錯誤。 | 執行 動作時發生系統錯誤。 |
當動作因為逾時或重試次數過多而無法收集指定的位數時，SIP 媒體應用程式會使用`ACTION_FAILED`叫用事件類型叫用 AWS Lambda 函數。
```
{
"SchemaVersion": "1.0",
"Sequence": 4,
"InvocationEventType": "ACTION_FAILED",
"ActionData": {
"Type": "PlayAudioAndGetDigits",
"Parameters" : {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"InputDigitsRegex": "^\d{2}#$",
"AudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "audio-file-1.wav"
},
"FailureAudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "audio-file-failure.wav"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
},
"ErrorType": "InvalidAudioSource",
"ErrorMessage": "Audio Source parameter value is invalid."
}
"CallDetails": {
...
}
}
```
請參閱 GitHub 上的工作範例：
+ https：//[https://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)。
+ [https://github.com/aws-samples/amazon-chime-sma-update-call](https://github.com/aws-samples/amazon-chime-sma-update-call)
# ReceiveDigits
當使用者輸入符合此動作中指定之規則表達式模式的數字時，SIP 媒體應用程式會叫用 AWS Lambda 函數。
```
{
"Type": "ReceiveDigits",
"Parameters": {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"InputDigitsRegex": "^\d{2}#$",
"InBetweenDigitsDurationInMilliseconds": 1000,
"FlushDigitsDurationInMilliseconds": 10000
}
}
```
**CallId**
*描述* – `CallId` AWS Lambda 函數調用 中的參與者`CallDetails`描述
*允許的值* – 有效的呼叫 ID
*必要* – 否
*預設值* — 無
**ParticipantTag**
*描述* – `ParticipantTag` 中其中一個已連線參與者的描述 `CallDetails`
*允許的值* – `LEG-A`或 `LEG-B`
*必要* – 否
*預設值* - 如果您指定 ，則叫`ParticipantTag`用`callLeg`忽略的預設值 `CallId`
**InputDigitsRegex**
*描述* – 規則表達式模式
*允許的值* – 有效的規則表達式模式
*必要* – 是
*預設值* — 無
**InBetweenDigitsDurationInMilliseconds**
*描述* – 檢查輸入是否符合規則表達式模式之前，數字之間的間隔
*允許值* – 持續時間，以毫秒為單位
*必要* – 是
*預設值* — 無
**FlushDigitsDurationInMilliseconds**
*描述* – 接收到的 DTMF 數字經過的間隔會排清並傳送至 AWS Lambda 函數。如果 SIP 媒體應用程式在間隔結束後收到新的數字，計時器會再次啟動。
*允許的值* – `InBetweenDigitsDurationInMilliseconds`
*必要* – 是
*預設值* — 無
SIP 媒體應用程式會在呼叫期間捨棄 DTMF 數字，直到收到新的`ReceiveDigits`動作為止。此`FlushDigitsDurationInMilliseconds`間隔會在 SIP 媒體應用程式收到第一個 DTMF 數字時開始。如果使用者在間隔過期之前輸入正確的數字，SIP 媒體應用程式會叫用 中所述的 AWS Lambda 函數[接收 Amazon Chime SDK PSTN 音訊服務的來電者輸入](case-4.md)。
如果使用者輸入不符合規則表達式模式，SIP 媒體應用程式會重複「失敗」音訊檔案訊息，直到應用程式耗盡重複計數或使用者輸入有效數字為止。
請參閱 GitHub 上的工作範例：
+ [https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
+ [https://github.com/aws-samples/amazon-chime-sma-update-call](https://github.com/aws-samples/amazon-chime-sma-update-call)
# RecordAudio
允許 SIP 媒體應用程式記錄來自指定呼叫 ID 的媒體。例如，語音郵件應用程式和會議參與者公告。應用程式會記錄，直到達到您設定的持續時間，或使用者按下其中一個 `RecordingTerminators`，或應用程式偵測到靜音為止。在這些情況下， 動作會指示應用程式將產生的媒體檔案放入指定的 S3 儲存貯體。S3 儲存貯體必須屬於與 SIP 媒體應用程式相同的 AWS 帳戶。此外， 動作必須向 Amazon Chime SDK Voice Connector 服務主體 [Amazon Chime SDK Voice Connector 服務主體](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) 授予 `s3:PutObject`和 `s3:PutObjectAcl`許可`voiceconnector.chime.amazonaws.com`。
**注意**
使用此功能進行的錄製可能受到有關記錄電子通訊的法律和法規的約束。您和您的最終使用者有責任遵守有關記錄的所有適用法律，包括適當地通知記錄工作階段或通訊中的所有參與者正在記錄工作階段或通訊，並取得他們的同意。
下列範例將 `s3:PutObject`和 `s3:PutObjectAcl`許可授予 Amazon Chime SDK Voice Connector 服務主體。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SMARead",
"Effect": "Allow",
"Principal": {
"Service": "voiceconnector.chime.amazonaws.com"
},
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::bucket-name/*"
}
]
}
```
------
以下範例會在呼叫者按下井字號 (\$1) 或經過 10 秒沒有活動，或呼叫者保持靜音 3 秒時停止記錄，並將產生的媒體檔案寫入 `RecordingDestination` 參數定義的位置。
**注意**
此範例使用 `CallId` 參數。您可以改為使用 `ParticipantTag` 參數，但不能同時使用兩者。
```
{
"Type": "RecordAudio",
"Parameters": {
"CallId": "call-id-1",
"DurationInSeconds": "10",
"SilenceDurationInSeconds": 3,
"SilenceThreshold": 100,
"RecordingTerminators": [
"#"
],
"RecordingDestination": {
"Type": "S3",
"BucketName": "valid-bucket-name",
"Prefix": "valid-prefix-name"
}
}
}
```
**CallId**
*描述* – `CallId` AWS Lambda 函數調用 `CallDetails` 中的參與者描述
*允許的值* – 有效的呼叫 ID
*必要* – 否
*預設值* — 無
**ParticipantTag**
*描述* – `ParticipantTag` 中其中一個已連線參與者的描述 `CallDetails`
*允許的值* – `LEG-A`或 `LEG-B`
*必要* – 否
*預設值* – 如果您指定 `ParticipantTag` ，則叫用`callLeg`忽略的預設值 `CallId`
**RecordingDestination.Type**
*描述* – 目的地的類型。只有 S3。
*允許的值* – S3
*必要* – 是
*預設值* — 無
**RecordingDestination.BucketName**
*描述* – 有效的 S3 儲存貯體名稱。儲存貯體必須能夠存取 [Amazon Chime SDK Voice Connector 服務主體](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) `voiceconnector.chime.amazonaws.com`。
*允許的值* – Amazon Chime SDK 可存取 `s3:PutObject`和 `s3:PutObjectAcl`動作的有效 S3 儲存貯體。
*必要* – 是
*預設值* — 無
****RecordingDestination.Prefix****
*描述* – 錄製檔案的 S3 字首
*允許的值* – 包含最多 979 個安全字元的有效字首名稱。如需安全字元的詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的[安全字元](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-guidelines-safe-characters)。
*必要* – 否
*預設* – 無。如果未指定，則記錄會儲存到 S3 儲存貯體的根目錄。
**DurationInSeconds**
*描述* – 記錄的持續時間，以秒為單位
*允許的值* – >0
*必要* – 否
*預設值* — 無
****SilenceDurationInSeconds****
*描述* – 靜音的持續時間，以秒為單位，之後錄音會停止。如果未指定，則會停用靜音偵測。
*允許的值* – 【1；1000】
*必要* – 否
*預設值* – 200
****SilenceThreshold****
*描述* – 被視為「靜音」的雜訊等級。如果您未指定 `SilenceDurationInSeconds`，則會忽略此參數。
**參考值 （將雜訊等級和閾值視為靜音）：**
+ 1-30dB 或以下，例如安靜的房間
+ 100-40-50 dB，例如低語或安靜的辦公室
+ 200-60dB，例如擁擠的辦公室
+ 1000-75 dB，例如大聲人物或音樂
*允許的值* – 【1；1000】
*必要* – 否
*預設值* – 200
**RecordingTerminators**
*描述* – 列出所有可用的錄製終止程式。
*允許的值* – 來自 [123456789\$10\$1 的單一數字和符號陣列】
*必要* – 是
*預設值* — 無
## 處理 ACTION\$1SUCCESSFUL 事件
當錄製結束時，Amazon Chime SDK SIP 媒體應用程式會呼叫 AWS Lambda 函數，並將 ACTION\$1SUCCESSFUL 事件連同調用結果傳遞給該函數。
```
{
"SchemaVersion": "1.0",
"Sequence": INTEGER,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type" : "RecordAudio",
"Parameters": {
...
},
"RecordingDestination": {
"Type": "S3",
"BucketName": "valid-bucket-name",
"Key": "valid-S3-key"
},
"RecordingTerminatorUsed":"#"
},
"CallDetails": {
...
}
}
```
`ACTION_SUCCESSFUL` 事件包含 `ActionData`，其中包含下列欄位：
**Type**
*描述* – 動作的類型 `RecordAudio`。
**Parameters**
*描述* – 動作的參數。
**RecordingDestination.Type**
*描述* – 目的地的類型。只有 S3。
**RecordingDestination.BucketName**
*描述* – 包含錄製檔案的 S3 儲存貯體。
**RecordingDestination.Key**
*描述* – 錄製檔案的 S3 金鑰。
**RecordingTerminatorUsed**
*描述* - 用來停止記錄的終止程式 - 其中一個在 `RecordingTerminators` 參數中傳遞的終止程式。如果記錄在達到最長持續時間 (`DurationInSeconds`) 或因為靜音 (`SilenceDurationInSeconds`) 而停止，則此鍵/值對不會包含在輸出中。
**錯誤處理**
對於驗證錯誤，SIP 媒體應用程式會使用適當的錯誤訊息呼叫 AWS Lambda 函數。下表列出可能的錯誤訊息。
| 錯誤 | 訊息 | Reason |
| --- | --- | --- |
| `InvalidActionParameter` | `CallId` 動作的 或 `ParticipantTag` 參數無效。 `DurationInSeconds` 參數值無效。 `SilenceDurationInSeconds` 參數值無效。 `SilenceThreshold` 參數值無效。 `RecordingDestination` 參數值無效。 將錄製上傳至 S3 儲存貯體時發生錯誤。 | 任何參數都是無效的。 |
| `SystemException` | 執行 動作時發生系統錯誤。 | 執行 動作時發生另一種類型的系統錯誤。 |
## 處理ACTION\$1FAILED事件
當動作無法在通話腿上記錄媒體時，SIP 媒體應用程式會使用`ACTION_FAILED`事件類型叫用 AWS Lambda 函數。請參閱以下範例。
```
{
"SchemaVersion": "1.0",
"Sequence": 5,
"InvocationEventType": "ACTION_FAILED",
"ActionData": {
"Type" : "RecordAudio",
"Parameters": {
...
},
"ErrorType": "InvalidActionParameter",
"ErrorMessage": "RecordingDestination parameter value is invalid."
},
"CallDetails": {
...
}
}
```
請參閱 GitHub 上的工作範例：https：//[https://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)
# SendDigits
在通話的任何腿上傳送最多 50 個雙音多頻率 (DTMF) 數字。這些訊號可以包括下列項目：
+ 數字 0 到 9
+ 特殊字元星號 (\$1) 和井字號 (\$1)
+ 網路控制訊號 A、B、C、D
+ 逗號字元 (，)。此訊號會在先前和下一個訊號之間新增 0.5 秒的延遲。
**Topics**
+ [使用 SendDigits動作](#send-digits-action)
+ [處理ACTION\$1SUCCESSFUL事件](#send-digit-success)
+ [處理ACTION\$1FAILED事件](#send-digit-fail)
+ [呼叫流程](#send-digits-call-flow)
## 使用 SendDigits動作
下列範例顯示典型`SendDigits`動作：
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "SendDigits",
"Parameters": {
"CallId": "call-id-1", // required
"Digits": ",,*1234,56,7890ABCD#", // required
"ToneDurationInMilliseconds": 100 // optional
}
}
]
}
```
**CallId**
*描述* – 函數調用 `CallId` 中參與者`CallDetails`的 AWS Lambda
*允許的值* – 有效的呼叫 ID
*必要* – 是
*預設值* — 無
**Digits**
*描述* – 在對應至 的呼叫腳上傳送的數字 `CallId`
*允許值* – 0-9、\$1、\$1、A、B、C、D、逗號 (、)
*必要* – 是
*預設值* — 無
**ToneDurationInMilliseconds**
*描述* – 傳輸每個數字的允許時間，以毫秒為單位。
*允許值* – 介於 50 和 24000 之間的任何整數
*必要* – 否
*預設值* – 250
## 處理ACTION\$1SUCCESSFUL事件
下列範例顯示 `SendDigits`動作的典型`ACTION_SUCCESSFUL`事件。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "SendDigits",
"Parameters": {
"Digits": "1,2A#",
"ToneDurationInMilliseconds": 100,
"CallId": "call-id-1"
},
"CallDetails": {
...
}
}
}
```
## 處理ACTION\$1FAILED事件
下列範例顯示 `SendDigits`動作的典型`ACTION_FAILED`事件。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_FAILED",
"ActionData": {
"Type": "SendDigits",
"Parameters": {
"Digits": "1,2A#",
"ToneDurationInMilliseconds": 20000000,
"CallId": "call-id-1"
},
"ErrorType": "InvalidActionParameter",
"ErrorMessage": "ToneDuration parameter value is invalid."
},
"CallDetails": {
...
}
}
}
```
## 呼叫流程
下圖顯示從來電者將數字傳送至受話方的程式流程。
![\[顯示 SendDigits動作之程式流程的圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/send-digits-1.png)
# Speak
您可以透過提供文字，在任何通話腿部播放語音。您可以使用純文字或語音合成標記語言 (SSML)。SSML 可透過新增暫停、強調特定單字或變更說話風格，進一步控制 Amazon Chime SDK 如何產生語音。
Amazon Chime SDK 使用 Amazon Polly 服務將text-to-speech。Amazon Polly 可讓您選擇標準或神經引擎，以提升語音品質。Amazon Polly 支援超過 20 種語言和 60 種語音，以自訂應用程式的使用者體驗。Amazon Chime SDK 免費提供語音功能，但您需付費使用 Amazon Polly。如需定價資訊，請參閱 Amazon Polly [定價頁面](https://aws.amazon.com/polly/pricing/)或帳單儀表板。
**重要**
使用 Amazon Polly 受 [ AWS 服務條款 ](https://aws.amazon.com/service-terms/)的約束，包括 AWS Machine Learning 和人工智慧服務的特定條款。
**Topics**
+ [使用 Speak動作](#speak-action)
+ [處理ACTION\$1SUCCESSFUL事件](#speak-action-success)
+ [處理ACTION\$1FAILED事件](#speak-action-fail)
+ [程式流程](#speak-flow)
## 使用 Speak動作
下列範例顯示 `Speak`動作的典型使用方式。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "Speak",
"Parameters": {
"Text": "Hello, World!", // required
"CallId": "call-id-1", // required
"Engine": "neural", // optional. Defaults to standard
"LanguageCode": "en-US", // optional
"TextType": "text", // optional
"VoiceId": "Joanna" // optional. Defaults to Joanna
}
}
]
}
```
**CallId**
*描述* – Lambda 函數調用 `CallId` 中的參與者`CallDetails`的
*允許的值* – 有效的呼叫 ID
*必要* – 是
*預設值* — 無
**Text**
*描述* – 指定要合成為語音的輸入文字。如果您將 指定`ssml`為 `TextType`，請遵循輸入文字的 SSML 格式。
*允許的值* – 字串
*必要* – 是
*預設值* — 無
**Engine**
*描述* – 指定處理語音合成文字時要使用的引擎 - 標準或神經。
*允許的值* – 標準 \$1 神經
*必要* – 否
*預設值* – 標準
**LanguageCode**
*描述* – 指定語言代碼。只有在使用雙語語音時才需要。如果您使用不含語言代碼的雙語語音，則會使用雙語語音的預設語言。
*允許的值* – [ Amazon Polly 語言代碼](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-LanguageCode)
*必要* – 否
*預設值* — 無
**TextType**
*描述* – 指定輸入文字、純文字或 SSML 的類型。如果未指定輸入類型，則會使用純文字做為預設值。如需 SSML 的詳細資訊，請參閱《*Amazon Polly 開發人員指南*》中的[從 SSML 文件產生語音](https://docs.aws.amazon.com/polly/latest/dg/ssml.html)。
*允許的值* – ssml \$1 文字
*必要* – 否
*預設值* — 無
**VoiceId**
*描述* – 指定您要使用的語音 ID。
*允許的值* – [Amazon Polly IDs](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-VoiceId)
*必要* – 否
*預設值* – Joanna
## 處理ACTION\$1SUCCESSFUL事件
以下範例顯示動作的典型`ACTION_SUCCESSFUL`事件，該動作使用 Amazon Polly 的`Joanna`語音，將文字 "Hello World" 合成為英文語音。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "Speak",
"Parameters": {
"CallId": "call-id-1",
"Engine": "neural",
"LanguageCode": "en-US",
"Text": "Hello World",
"TextType": "text",
"VoiceId": "Joanna"
}
},
"CallDetails":{
...
}
}
```
## 處理ACTION\$1FAILED事件
下列範例顯示與上一個範例中使用之相同`ACTION_FAILED`事件的典型事件。
```
{
"SchemaVersion": "1.0",
"Sequence":2,
"InvocationEventType": "ACTION_FAILED",
"ActionData":{
"Type": "Speak",
"Parameters": {
"CallId": "call-id-1",
"Engine": "neural",
"LanguageCode": "en-US",
"Text": "Hello World",
"TextType": "text",
"VoiceId": "Joanna"
},
"ErrorType": "SystemException",
"ErrorMessage": "System error while running action"
},
"CallDetails":{
...
}
}
```
**錯誤處理**
此資料表會列出並描述 `Speak`動作擲回的錯誤訊息。
| 錯誤 | 訊息 | 原因 |
| --- | --- | --- |
| `AccessDenied` | `AWSServiceRoleForAmazonChimeVoiceConnector` 服務連結角色未正確設定。 | 用於向 Amazon Polly 提出請求的服務連結角色不存在或缺少許可。若要解決此問題，請參閱 [使用 Amazon Chime SDK Voice Connector 服務連結角色](speak-and-get-digits.md#speak-digits-policy)一節中的步驟 |
| `InvalidActionParameter` | | 驗證動作參數時發生錯誤。如需參數的詳細資訊，請參閱《*Amazon Polly 開發人員指南*》中的 [SynthesizeSpeech API](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech)。 |
| ActionExecutionThrottled | Amazon Polly 正在調節合成語音的請求。 | 對 Amazon Polly 的請求會傳回限流例外狀況。如需 Amazon Polly 限流限制的詳細資訊，請參閱 [ https：//https://docs.aws.amazon.com/polly/latest/dg/limits.html\$1limits-throttle。 ](https://docs.aws.amazon.com/polly/latest/dg/limits.html#limits-throttle) |
| `MissingRequiredActionParameter` | `Text` 是必要的參數。 | 有動作參數必須具有 `Text`值 |
| `MissingRequiredActionParameter` | `Text` 限制為 1，000 個字元 | 文字超過字元限制。 |
| `SystemException` | 執行動作時發生系統錯誤。 | 執行 動作時發生系統錯誤。 |
## 程式流程
下圖顯示為發起人啟用 `Speak`動作的程式流程。在此範例中，來電者聽到的文字
![\[圖表顯示啟用呼叫者Speak動作的程式流程。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/Speak1.png)
**在圖表中**
使用軟體電話，來電者輸入已註冊至 SIP 媒體應用程式的號碼。應用程式使用 SIP `INVITE`方法，並傳送`Trying (100)`回應給呼叫者。這表示下一躍點伺服器收到呼叫請求。然後， SIP 應用程式會使用 `INVITE`來聯絡端點。建立連線後，應用程式會傳送`Ringing (180)`回應給發起人，並開始提醒。
然後，SIP 媒體應用程式會將`NEW_INBOUND_CALL`事件傳送至 Lambda 函數，該函數會回應包含呼叫者 ID 和您要轉換為語音的文字`Speak`的動作。然後，SIP 應用程式會傳送`200 (OK)`回應，指出已接聽通話。通訊協定也會啟用媒體。
如果`Speak`動作成功並將文字轉換為語音，則會將`ACTION_SUCCESSFUL`事件傳回 SIP 媒體應用程式，並傳回下一組動作。如果動作失敗，SIP 媒體應用程式會將`ACTION_FAILED`事件傳送至 Lambda 函數，該函數會以一組`Hangup`動作回應。應用程式掛斷呼叫者，並將`HANGUP`事件傳回 Lambda 函數，而該函數不會採取進一步的動作。
下圖顯示 程式流程，而不是 啟用受話方`Speak`的動作。
![\[圖表顯示啟用受話方Speak動作的程式流程。您可以在任何橋接通話上執行此操作。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/Speak2.png)
**在圖表中**
呼叫者輸入已註冊至 SIP 媒體應用程式的號碼，應用程式會如上圖所述回應。當 Lambda 函數收到`NEW_INBOUND_CALL`事件時，它會將[CallAndBridge](call-and-bridge.md)動作傳回 SIP 應用程式。然後，應用程式會使用 SIP `INVITE`方法將 `Trying (100)`和 `Ringing (180)`回應傳送給受話方。
如果受話方接聽，SIP 媒體應用程式會接收`200 (OK)`回應，並傳送相同的回應給來電者。這會建立媒體，而 SIP 應用程式會將[CallAndBridge](call-and-bridge.md)動作`ACTION_SUCCESSFUL`的事件傳送至 Lambda 函數。然後， 函數會將 Speak 動作和資料傳回至 SIP 應用程式，該應用程式會轉換
# SpeakAndGetDigits
透過提供文字並從使用者收集雙音多頻率 (DTMF) 數字來播放語音。文字可以是純文字或語音合成標記語言 (SSML) 增強文字，透過新增暫停、強調特定單字或變更說話風格等支援 SSML 功能，提供更多對 Amazon Chime SDK 如何產生語音的控制。如果發生失敗，例如使用者未輸入正確的 DTMF 數字數，動作會播放「失敗」語音，然後重播主要語音，直到 SIP 媒體應用程式耗盡 `Repeat` 參數中定義的嘗試次數。
Amazon Chime SDK 使用 Amazon Polly，這是一種將文字轉換為逼真的語音的雲端服務，Amazon Polly 同時提供標準和神經引擎，以提高語音品質、超過 20 種支援的語言和 60 個語音。Amazon Polly 免費提供語音功能，但您需付費使用 Amazon Polly。如需定價資訊，請參閱 Amazon Polly [定價頁面](https://aws.amazon.com/polly/pricing/)或帳單儀表板。
**重要**
使用 Amazon Polly 受[AWS 服務條款 的約束](https://aws.amazon.com/service-terms/)，包括 AWS Machine Learning and Artificial Intelligence Services 特有的條款。
**Topics**
+ [使用 SpeakAndGetDigits動作](#speak-digits-action)
+ [處理ACTION\$1SUCCESSFUL事件](#speak-digits-success)
+ [處理ACTION\$1FAILED事件](#speak-digits-fail)
+ [使用 Amazon Chime SDK Voice Connector 服務連結角色](#speak-digits-policy)
## 使用 SpeakAndGetDigits動作
下列範例顯示 `SpeakAndGetDigits`動作的典型使用方式：
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "SpeakAndGetDigits",
"Parameters": {
"CallId": "call-id-1", // required
"InputDigitsRegex": "^\d{2}#$", // optional
"SpeechParameters": {
"Text": "Hello World", // required
"Engine": "neural", // optional. Defaults to standard
"LanguageCode": "en-US", // optional
"TextType": "text", // optional
"VoiceId": "Joanna" // optional. Defaults to Joanna
},
"FailureSpeechParameters": {
"Text": "Hello World", // required
"Engine": "neural", // optional. Defaults to the Engine value in SpeechParameters
"LanguageCode": "en-US", // optional. Defaults to the LanguageCode value in SpeechParameters
"TextType": "text", // optional. Defaults to the TextType value in SpeechParameters
"VoiceId": "Joanna" // optional. Defaults to the VoiceId value in SpeechParameters
},
"MinNumberOfDigits": 3, // optional
"MaxNumberOfDigits": 5, // optional
"TerminatorDigits": ["#"], // optional
"InBetweenDigitsDurationInMilliseconds": 5000, // optional
"Repeat": 3, // optional
"RepeatDurationInMilliseconds": 10000 // required
}
}
]
}
```
**CallId**
*描述* – Lambda 函數調用`CallId`的 CallDetails 中參與者的 。
*允許的值* – 有效的 `callID`
*必要* – 是
*預設值* – 否
**InputDigitsRegex**
*描述* – 有助於確保使用者輸入正確數字和字母的規則表達式模式。
*允許的值* – 有效的規則表達式模式
*必要* – 否
*預設值* — 無
**SpeechParameters.Engine**
*描述* – 指定處理語音合成的文字時要使用的引擎 – 標準或神經。
*允許的值* – `standard` \$1 `neural`
*必要* – 否
*預設值* – 標準
**SpeechParameters.LanguageCode**
*描述* – 指定語言代碼。只有在使用雙語語音時才需要這樣做。如果使用雙語語音且未指定語言代碼，則會使用雙語語音的預設語言。
*允許的值* – [ Amazon Polly 語言代碼](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-LanguageCode)
*必要* – 否
*預設值* — 無
**SpeechParameters.Text**
*描述* – 指定輸入文字。如果您將 指定`ssml`為 `SpeechParameters.TextType`，則必須遵循輸入文字的 SSML 格式。如需 SSML 的詳細資訊，請參閱《*Amazon Polly 開發人員指南*》中的[從 SSML 文件產生語音](https://docs.aws.amazon.com/polly/latest/dg/ssml.html)。
*允許的值* – 字串
*必要* – 是
*預設值* — 無
**SpeechParameters.TextType**
*描述* – 指定 的文字格式`SpeechParameters.Text`。如果未指定，預設`text`會使用 。如需 SSML 的詳細資訊，請參閱《*Amazon Polly 開發人員指南*》中的[從 SSML 文件產生語音](https://docs.aws.amazon.com/polly/latest/dg/ssml.html)。
*允許的值* – `ssml` \$1 `text`
*必要* – 否
*預設值* – `text`
**SpeechParameters.VoiceId**
*描述* – 用於在 中說出文字的 Amazon Polly 語音 ID`SpeechParameters.Text`。
*允許的值* – [Amazon Polly IDs](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-VoiceId)
*必要* – 否
*預設值* – Joanna
**FailureSpeechParameters.Engine**
*描述* – 指定在處理客戶輸入無效語音合成回應時使用的引擎 – 標準或神經。
*允許的值* – `standard` \$1 `neural`
*必要* – 否
*預設值* – `SpeechParameters.Engine`值
**FailureSpeechParameters.LanguageCode**
*描述* – 指定當客戶輸入無效的回應時所使用的語言代碼。只有在使用雙語語音時才需要。如果您使用雙語語音而不指定語言代碼，則會使用雙語語音的預設語言。
*允許的值* – [ Amazon Polly 語言代碼](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-LanguageCode)
*必要* – 否
*預設值* – `SpeechParameters.LanguageCode`值。
**FailureSpeechParameters.Text**
*描述* – 指定客戶輸入無效回應時所說的輸入文字。如果您將 指定`ssml`為 `FailureSpeechParameters.TextType`，則必須遵循輸入文字的 SSML 格式。
*允許的值* – 字串
*必要* – 是
*預設值* — 無
**FailureSpeechParameters.TextType**
*描述* – 指定在 中指定的輸入文字`FailureSpeechParameters.Text`是純文字還是 SSML。預設值為純文字。如需詳細資訊，請參閱《*Amazon Polly 開發人員指南*》中的[從 SSML 文件產生語音](https://docs.aws.amazon.com/polly/latest/dg/ssml.html)。
*允許的值* – `ssml` \$1 `text`
*必要* – 否
*預設值* – `SpeechParameters.Text`值
**FailureSpeechParameters.VoiceId**
*描述* – 用於在 中說出字串的語音 ID`FailureSpeechParameters.Text`。
*允許的值* – [Amazon Polly IDs](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-VoiceId)
*必要* – 是
*預設值* – `SpeechParameters.VoiceId`值
**MinNumberOfDigits**
*描述* – 在逾時或播放「呼叫失敗」訊息之前要擷取的位數下限。
*允許的值* – 大於或等於零
*必要* – 否
*預設值* – 0
**MaxNumberOfDigits**
*描述* – 在停止之前擷取的位數上限，而不終止數字。
*允許的值* – 大於 `MinNumberOfDigits`
*必要* – 否
*預設值* – 128
**TerminatorDigits**
*描述* – 如果使用者輸入小於 MaxNumberOfDigits
*允許值* – 任何一個：0 1 2 3 4 5 6 7 8 9 \$1 或 \$1
*必要* – 否
*預設值* – \$1
**InBetweenDigitsDurationInMilliseconds**
*描述* – 播放失敗語音之前，數字輸入之間的等待時間，以毫秒為單位。
*允許的值* – 大於零
*必要* – 否
*預設值* – 如果未指定，則預設為 `RepeatDurationInMilliseconds`值
**Repeat**
*描述* – 嘗試取得數字的總數。如果您省略此參數，則預設為嘗試收集數字一次。
*允許的值* – 大於零
*必要* – 否
*預設值* – 1
**RepeatDurationInMilliseconds**
*描述* – 每次嘗試取得數字時，以毫秒為單位的逾時。
*允許的值* – 大於零
*必要* – 是
*預設值* — 無
## 處理ACTION\$1SUCCESSFUL事件
下列範例顯示典型`ACTION_SUCCESSFUL`事件。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "SpeakAndGetDigits",
"Parameters": {
"CallId": "call-id-1",
"InputDigitsRegex": "^\d{2}#$",
"SpeechParameters": {
"Engine": "neural",
"LanguageCode": "en-US",
"Text": "Hello World",
"TextType": "text",
"VoiceId": "Joanna"
},
"FailureSpeechParameters": {
"Engine": "neural",
"LanguageCode": "en-US",
"Text": "Hello World",
"TextType": "text",
"VoiceId": "Joanna"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
},
"ReceivedDigits": "1234"
},
"CallDetails":{
...
}
}
```
## 處理ACTION\$1FAILED事件
下列範例顯示典型`ACTION_FAILED`事件。
```
{
"SchemaVersion": "1.0",
"Sequence":2,
"InvocationEventType": "ACTION_FAILED",
"ActionData":{
"Type": "SpeakAndGetDigits",
"Parameters": {
"CallId": "call-id-1",
"InputDigitsRegex": "^\d{2}#$",
"SpeechParameters": {
"Engine": "neural",
"LanguageCode": "en-US",
"Text": "Hello World",
"TextType": "text",
"VoiceId": "Joanna"
},
"FailureSpeechParameters": {
"Engine": "neural",
"LanguageCode": "en-US",
"Text": "Hello World",
"TextType": "text",
"VoiceId": "Joanna"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
},
"ErrorType": "SystemException",
"ErrorMessage": "System error while running action"
},
"CallDetails":{
...
}
}
```
**錯誤處理**
此資料表會列出並描述 `Speak`動作擲回的錯誤訊息。
| 錯誤 | 訊息 | 原因 |
| --- | --- | --- |
| `AccessDenied` | `AWSServiceRoleForAmazonChimeVoiceConnector` 角色未正確設定。 | 用於向 Amazon Polly 提出請求的角色不存在或缺少許可。若要解決此問題，請參閱 [使用 Amazon Chime SDK Voice Connector 服務連結角色](#speak-digits-policy)一節中的步驟 |
| `InvalidActionParameter` | | 驗證動作參數時發生錯誤。若要檢閱此動作的可用參數及其選項，請參閱《Amazon Polly 開發人員指南》中的 [SynthesizeSpeech](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html)。 |
| `MissingRequiredActionParameter` | `Text` 是必要的參數。 | 動作參數必須具有 `Text`值 |
| `MissingRequiredActionParameter` | `Text` 限制為 1，000 個字元 | 文字超過字元限制。 |
| `SystemException` | 執行動作時發生系統錯誤。 | 執行 動作時發生系統錯誤。 |
## 使用 Amazon Chime SDK Voice Connector 服務連結角色
您不需要手動為 `Speak`或 `SpeakAndGetDigits`動作建立服務連結角色。當您在 Amazon Chime SDK 主控台、 AWS Command Line Interface或 AWS API 中建立或更新 SIP 媒體應用程式時，Amazon Chime SDK 會為您建立服務連結角色。
如需詳細資訊，請參閱《[Amazon Chime SDK 管理員指南》中的使用 Amazon Chime 服務連結角色](https://docs.aws.amazon.com/chime/latest/ag/using-service-linked-roles-stream.html)。 **
# StartBotConversation
`StartBotConversation` 動作會在最終使用者和 Amazon Lex v2 機器人之間建立語音對話。使用者提供所需的資訊給機器人。機器人接著會將資訊傳回至公有交換電話網路 (PSTN) Audio Lambda 函數，該函數會執行請求的任務。
例如，機器人可以在對話開始時播放選用的歡迎訊息，以簡短描述 PSTN 音訊 Lambda 函數可執行的任務。使用者和機器人之間的對話會來回進行，直到機器人收集必要的資訊為止。對話結束後，Amazon Chime SDK 會使用動作成功事件叫用您的 PSTN 音訊 Lambda 函數，其中包含機器人收集的資訊。您的 PSTN 音訊 Lambda 函數會處理資訊並執行請求的任務。
Audio Service 與您的使用者提供逼真的對話互動。例如，使用者可以中斷機器人並在音訊提示完成之前回答問題。更重要的是，使用者可以使用語音和 DTMF 數字的任意組合來提供資訊。機器人會等待使用者提供輸入再回應。您可以設定機器人在解譯任何語音輸入之前，等待使用者完成說話的時間。使用者也可以指示機器人在通話期間需要時間擷取其他資訊時等待，例如信用卡號碼。
`StartBotConversation` 動作會在機器人對話期間使用 Amazon Lex 和 Amazon Polly。適用標準 Amazon Lex 和 Amazon Polly 成本。如需定價詳細資訊，請參閱 [Amazon Lex 串流對話定價](https://aws.amazon.com/lex/pricing/)和 [Amazon Polly 定價](https://aws.amazon.com/polly/pricing/)頁面。
**注意**
您無法在橋接通話或已參加 Amazon Chime SDK 會議的通話上執行此動作。
**重要**
Amazon Lex 和 Amazon Polly 的使用受[AWS 服務條款 ](https://aws.amazon.com/service-terms/)的約束，包括 AWS Machine Learning和人工智慧服務的特定條款。
**Topics**
+ [StartBotConversation 語法](#startbot-syntax)
+ [使用 StartBotConversation動作](#using-startbot)
+ [處理ACTION\$1SUCCESSFUL事件](#bot-action-success)
+ [處理ACTION\$1FAILED事件](#bot-action-fail)
+ [授予使用機器人的許可](#bot-permissions)
+ [設定語音和 DTMF 逾時](#bot-timeouts)
+ [在對話期間使用 DTMF 輸入](#bot-dtmf)
+ [帳單和服務配額](#bot-billing)
## StartBotConversation 語法
下列範例顯示典型`StartBotConversation`語法。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "StartBotConversation",
"Parameters": {
"CallId": "string",
"ParticipantTag": "string",
"BotAliasArn": "string",
"LocaleId": "string",
"Configuration": {
"SessionState": {
"SessionAttributes": {
"string": "string"
},
"DialogAction" : {
"Type": "string"
}
},
"WelcomeMessages": [
{
"Content": "string",
"ContentType": "string"
}
]
}
}
}
]
}
```
**CallId**
*描述* – AWS Lambda 函數調用 `CallID` 中參與者`CallDetails`的 。`StartBotConversation` 動作使用此 ID 做為機器人的 `SessionId`。在通話上進行的所有機器人對話都會共用相同的對話工作階段。您可以使用 [Amazon Lex API PutSession](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_PutSession.html)修改使用者和機器人之間的工作階段狀態。如需詳細資訊，請參閱《[Amazon Lex 開發人員指南》中的使用 Amazon Lex v2 API 管理工作階段](https://docs.aws.amazon.com/lexv2/latest/dg/using-sessions.html)。 *Amazon Lex *
*允許的值* – 有效的呼叫 ID。
*必要* – 否，如果 `ParticipantTag` 存在。
*預設值* – 無。
**ParticipantTag**
*描述* – 中其中一個已連線參與者`ParticipantTag`的 `CallDetails`。
*允許的值* – `LEG-A`。
*必要* – 否，如果 `CallId` 存在。
*預設值* – 調用 `ParticipantTag` 的 `callLeg`。如果您指定 ，則忽略`CallDetails`。
**BotAliasArn**
*描述* – Lex 機器人的機器人別名 ARN。您必須在與 PSTN 音訊應用程式相同的 AWS 區域中建立機器人。有效的 Amazon Lex 機器人別名具有此格式：`arn:aws:lex:region:awsAccountId:bot-alias/botId/botAliasId`，其中 *`region`*是機器人所在的 AWS 區域。`awsAccountId` 是建立 Amazon Lex 機器人的 AWS 帳戶 ID。`botId` 值是建立機器人時指派給機器人的識別符。您可以在機器人詳細資訊頁面的 Amazon Lex 主控台中找到機器人 ID。 ****`botAliasId` 是建立機器人別名時指派給機器人別名的識別符。您可以在別名****頁面的 Amazon Lex 主控台中找到機器人別名 ID。
*允許的值* – 有效的機器人 ARN。
*必要* - 是。
*預設值* –無。
**LocaleId**
*描述* – 您用於機器人的地區設定識別符。如需地區設定和語言代碼的清單，請參閱 [Amazon Lex 支援的語言和地區設定](https://docs.aws.amazon.com/lexv2/latest/dg/how-languages.html)。
*允許的值* – [ Amazon Lex 支援的語言和地區設定。](https://docs.aws.amazon.com/lexv2/latest/dg/how-languages.html)
*必要* – 否。
*預設值* – `en_US`。
**Configuration**
*描述* – 對話組態，包括工作階段狀態和歡迎訊息。`Configuration` 物件的 JSON 字串表示法總大小限制為 10 KB。
*允許的值* – `Configuration` 物件。
*必要* – 否。
*預設值* – 無。
**Configuration.SessionState**
*描述* – 使用者使用 Amazon Lex v2 的工作階段狀態。
*允許的值* – `SessionState` 物件。
*必要* – 否。
*預設值* – 無。
**Configuration.SessionState.SessionAttributes**
*描述* – 代表工作階段特定內容資訊的鍵/值對映射。此映射包含 Amazon Lex v2 與用戶端應用程式之間傳遞的應用程式資訊。
*允許的值* – 字串對字串映射。
*必要* – 否。
*預設值* – 無。
**Configuration.SessionState.DialogAction.Type**
*描述* – 機器人在與使用者互動時採取的下一個動作。可能的值如下：
+ *委派* Amazon Lex v2 決定下一個動作。
+ *ElicitIntent* 下一個動作會從使用者引發意圖。
*允許的值* – `Delegate` \$1 `ElicitIntent`。
*必要* – 否。
*預設值* – 無。
**Configuration.WelcomeMessages**
*描述* – 在對話開始時傳送給使用者的訊息清單。如果您設定 `welcomeMessage` 欄位，則必須將 `DialogAction.Type`值設定為 `ElicitIntent`。
*允許的值* – 訊息物件
*必要* – 否。
*預設值* – 無。
**Configuration.WelcomeMessages.Content**
*描述* – 歡迎訊息文字。
*允許的值* – 字串。
*必要* – 否。
*預設值* – 無。
**Configuration.WelcomeMessages.ContentType**
*描述* – 指出歡迎訊息類型。
*允許的值* –` PlainText` \$1 `SSML`
+ *PlainText* – 訊息包含純 UTF-8 文字。
+ *SSML* – 訊息包含語音輸出的文字格式。
*必要* – 是。
*預設值* – 無。
## 使用 StartBotConversation動作
下列範例顯示典型`StartBotConversation`的動作。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "StartBotConversation",
"Parameters": {
"CallId": "call-id-1",
"BotAliasArn": "arn:aws:lex:us-east-1:123456789012:bot-alias/ABCDEFGHIH/MNOPQRSTUV",
"LocaleId": "en_US",
"Configuration": {
"SessionState": {
"SessionAttributes": {
"mykey1": "myvalue1"
},
"DialogAction" : {
"Type": "ElicitIntent"
}
},
"WelcomeMessages": [
{
"Content": "Welcome. How can I help you?",
"ContentType": "PlainText"
}
]
}
}
}
]
}
```
## 處理ACTION\$1SUCCESSFUL事件
下列範例顯示 `StartBotConversation`動作的典型`ACTION_SUCCESSFUL`事件。
```
{
"SchemaVersion": "1.0",
"Sequence": number,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData":
{
"CallId": "string",
"Type": "StartBotConversation",
"Parameters": {
// parameters provided in the StartBotConversation action.
},
"CallDetails": {
// Information about the call associated with the AWS Lambda invocation.
},
"IntentResult": {
"SessionId": "string",
"SessionState": {
"SessionAttributes": {
"string": "string"
},
"Intent": {
"Name": "string",
"Slots": {
"string": {
"Value": {
"OriginalValue": "string",
"InterpretedValue": "string",
"ResolvedValues": ["string"]
},
"Values": []
}
},
"State": "string",
"ConfirmationState": "string"
}
},
"Interpretations": [
{
"NluConfidence": {
"Score": number
},
"Intent": {
"Name": "string",
"Slots": {
"string": {
"Value": {
"OriginalValue": "string",
"InterpretedValue": "string",
"ResolvedValues": ["string"]
},
"Values": []
}
},
"State": "string",
"ConfirmationState": "string"
}
}
]
}
}
}
```
**IntentResult**
使用者與機器人之間的對話結果。
**SessionId**
機器人對話工作階段的識別符。當使用者開始與您的機器人對話時，Amazon Lex 會建立工作階段。工作階段會封裝使用者與機器人之間交換的資訊。`StartBotConversation` 動作會使用呼叫 ID 做為機器人的 `SessionId`。您可以使用 Lex [https://docs.aws.amazon.com/lexv2/latest/dg/API_runtime_PutSession.html](https://docs.aws.amazon.com/lexv2/latest/dg/API_runtime_PutSession.html) API 修改使用者和機器人之間的工作階段狀態。如需詳細資訊，請參閱《[Amazon Lex 開發人員指南》中的使用 Amazon Lex V2 API 管理工作階段](https://docs.aws.amazon.com/lexv2/latest/dg/using-sessions.html)。 *Amazon Lex *
**SessionState**
使用者 Amazon Lex v2 工作階段的狀態。
**SessionState.SessionAttributes**
代表工作階段特定內容資訊的金鑰/值對映射。映射包含在連接至機器人的 Lambda 函數與 PSTN 音訊 Lambda 函數之間傳遞的機器人對話資訊。
**解譯**
Amazon Lex 衍生的意圖清單，可滿足客戶的表達用語。`NluConfidence` 得分最高的意圖會成為 的意圖`SessionState`。
**Interpretations.NluConfidence.Score**
指出 Amazon Lex v2 對意圖滿足使用者意圖的可信度的分數。範圍介於 0.00 到 1.00 之間。分數越高表示可信度越高。
**Intent**
使用者想要執行的動作。
**Intent.Name**
意圖的名稱。
**Intent.Slots**
意圖的所有槽映射。槽的名稱會映射到槽的值。如果尚未填充插槽，則值為 null。
**Intent.Slots.Value**
槽的值。
**Intent.Slots.Values**
使用者為插槽提供的一或多個值清單。
**Intent.Slots.Value.OriginalValue**
使用者回覆的文字，針對槽輸入。
**Intent.Slots.Value.InterpretedValue**
*描述* – Amazon Lex v2 為插槽決定的值。實際值取決於機器人的值選擇策略設定。您可以選擇使用使用者輸入的值，也可以讓 Amazon Lex v2 選擇`resolvedValues`清單中的第一個值。
**Intent.Slots.Value.ResolvedValues**
Amazon Lex v2 為插槽識別的其他值清單。
**Intent.State**
*描述* – 意圖的履行資訊。可能的值如下：
+ `Failed` – Lambda 函數無法滿足意圖。
+ `Fulfilled` – Lambda 函數實現了意圖。
+ `ReadyForFulfillment` – 意圖的資訊存在，您的 Lambdafunction 可以滿足意圖。
**Intent.ConfirmationState**
*描述* – 表示意圖的確認。可能的值如下：
+ *已確認* – 已滿足意圖。
+ *拒絕* – 使用者回應「否」確認提示。
+ *無* – 未提示使用者進行確認，或提示使用者但未確認或拒絕提示。
## 處理ACTION\$1FAILED事件
下列範例顯示 `StartBotConversation`動作的典型`ACTION_FAILED`事件。
```
{
"SchemaVersion": "1.0",
"Sequence": number,
"InvocationEventType": "ACTION_FAILED",
"ActionData":{
"CallId": "string",
"Type": "StartBotConversation",
"Parameters": {
// parameters provided in the StartBotConversation action
},
"ErrorType": "string",
"ErrorMessage": "string"
},
"CallDetails":{
}
}
```
**ErrorType**
唯一識別錯誤條件的字串。
**ErrorMessage**
錯誤條件的一般描述。
### 錯誤代碼
下表列出 Lambda 函數可在`ACTION_FAILED`事件中傳回的錯誤訊息。
| 錯誤 | Description |
| --- | --- |
| `InvalidActionParameter` | 一或多個動作參數無效。錯誤訊息說明無效的參數。 |
| `SystemException` | 執行 動作時發生系統錯誤。 |
| `ResourceNotFound` | 找不到指定的機器人。 |
| `ResourceAccessDenied` | 對機器人的存取遭拒。 |
| `ActionExecutionThrottled` | 超過機器人對話服務限制。錯誤訊息說明超過的特定服務限制。 |
## 授予使用機器人的許可
下列範例授予 Amazon Chime SDK 呼叫 Amazon Lex [https://docs.aws.amazon.com/lexv2/latest/dg/API_runtime_StartConversation.html](https://docs.aws.amazon.com/lexv2/latest/dg/API_runtime_StartConversation.html) APIs許可。您必須明確授予 Audio Service 許可才能使用您的機器人。服務主體需要 條件區塊。條件區塊必須使用全域內容索引鍵 `AWS:SourceAccount`和 `AWS:SourceArn`。`AWS:SourceAccount` 是您的 AWS 帳戶 ID。`AWS:SourceArn` 是叫用 Lex 機器人的 PSTN 音訊應用程式的資源 ARN。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowChimePstnAudioUseBot",
"Effect": "Allow",
"Principal": {
"Service": "voiceconnector.chime.amazonaws.com"
},
"Action": "lex:StartConversation",
"Resource": "arn:aws:lex:us-east-1:123456789012:bot-alias/botId/aliasId",
"Condition": {
"StringEquals": {
"AWS:SourceAccount": "123456789012"
},
"ArnEquals": {
"AWS:SourceArn": "arn:aws:chime:us-east-1:123456789012:sma/smaId"
}
}
}
]
}
```
------
## 設定語音和 DTMF 逾時
您可以在擷取使用者輸入時設定語音和 DTMF 逾時。您可以在與機器人開始對話時，透過工作階段屬性設定逾時，並視需要在 Lex 機器人的 Lambda 函數中覆寫逾時。Amazon Lex 可讓您為意圖或機器人設定多個插槽。因為您可以指定工作階段屬性套用至意圖和插槽層級，所以您可以指定只有在收集特定類型的輸入時才設定屬性。例如，您可以在收集帳戶號碼時指定比收集日期更長的逾時時間。您可以在工作階段屬性索引鍵中使用萬用字元。
例如，若要將所有意圖的所有插槽語音逾時設定為 4000 毫秒，您可以使用 提供工作階段屬性： `x-amz-lex:start-timeout-ms:*:*`作為工作階段屬性名稱， `4000`作為工作階段屬性值。如需詳細資訊，請參閱《*Amazon Lex 開發人員指南*》中的[設定擷取使用者輸入的逾時](https://docs.aws.amazon.com/lexv2/latest/dg/session-attribs-speech.htm)。
## 在對話期間使用 DTMF 輸入
Amazon Lex 機器人在對話期間支援語音和鍵盤輸入。機器人會將鍵盤輸入解譯為 DTMF 數字。您可以提示聯絡人以井字號 (\$1) 結束輸入，並使用星號鍵 (\$1) 取消對話。如果您未提示客戶以井字號結束輸入，則 Lex 會在 5 秒後停止等待額外的按鍵。
## 帳單和服務配額
AWS 會向您收取下列費用：
+ 呼叫的 Amazon Chime SDK 用量。如需詳細資訊，請參閱 [Amazon Chime SDK 定價](https://aws.amazon.com/chime/chime-sdk/pricing/)。
+ 用於解譯使用者語音的 Amazon Lex 用量。如需詳細資訊，請參閱 [Amazon Lex 串流對話定價](https://aws.amazon.com/lex/pricing/)。
+ 從機器人合成文字回應的 Amazon Polly 用量。如需詳細資訊，請參閱 [ Amazon Polly 定價](https://aws.amazon.com/polly/pricing/)。
您也需要注意下列服務配額：
+ Amazon Chime SDK 具有可搭配 PSTN 音訊[StartBotConversation](#start-bot-conversation)動作使用的 Amazon Lex 機器人數量上限的服務配額。如需詳細資訊，請參閱《 *AWS 一般參考*》中的 [SIP 中繼和語音配額](https://docs.aws.amazon.com/general/latest/gr/chime-sdk.html#chm-sdk-pstn-quotas)。
+ Amazon Lex 對於每個 Lex 機器人的並行語音對話數量上限具有服務配額。您可以聯絡 Amazon Lex 服務團隊以增加配額。如需詳細資訊，請參閱《Amazon Lex *開發人員指南》中的 Amazon Lex *[指導方針和配額](https://docs.aws.amazon.com/lexv2/latest/dg/quotas.html)。
+ Amazon Polly 具有用於合成文字回應的服務配額。您可以聯絡 Amazon Polly 服務團隊以增加配額。如需 Amazon Polly 服務配額的詳細資訊，請參閱《[Amazon Polly 開發人員指南》中的 Amazon Polly 中的配額](https://docs.aws.amazon.com/polly/latest/dg/limits.html)。 *Amazon Polly *
# 在 Amazon Chime SDK PTSN 音訊服務中使用 SIP 標頭
當您想要與 SIP 基礎設施交換通話內容資訊時，您現在可以在 AWS Lambda 函數中傳送和接收User-To-User標頭、轉換標頭和自訂 SIP 標頭。
+ User-to-User(UUI) 標頭可用來傳送呼叫控制資料。此資料由啟動工作階段的應用程式插入，並由接受工作階段的應用程式使用。它不會用於任何基本的 SIP 功能。例如，您可以使用呼叫中心中的 UUI 標頭，在客服人員之間傳遞有關呼叫的資訊。
+ Diversion 標頭用於顯示呼叫的來源和原因。您可以使用此標頭來查看來自其他 SIP 代理程式的轉移資訊，或將其傳遞。
+ 自訂 SIP 標頭可讓您傳遞任何其他您想要的資訊。例如，如果您想要傳遞帳戶 ID，您可以建立名為「X-Account-Id」的 X 標頭，並新增此資訊。
您必須在自訂 SIP 標頭前面加上 `x-`。標頭會在 AWS Lambda 函數中公開，並在傳入呼叫期間作為`NEW_INBOUND_CALL`事件的一部分接收。在觸發[CallAndBridge](call-and-bridge.md)動作或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplicationCall.html) API 時，您也可以將這些標頭包含在外撥通話中。
Lambda 函數的 `Participants`區段包含 `SipHeaders` 欄位。當您收到自訂標頭，或填入 `User-to-User`或 `Diversion`標頭時，即可使用此欄位。
此範例顯示 AWS Lambda 調用包含 SIP 標頭時的預期回應。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type":"actionType",
"Parameters":{
// Parameters vary by actionType
}
},
"CallDetails":{
.....
.....
"Participants":[
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
.....
"Status": "Connected"
"SipHeaders": {
"X-Test-Value": "String",
"User-to-User": "616d617a6f6e5f6368696d655f636f6e6e6563745f696e746567726174696f6e;encoding=hex",
"Diversion": "sip:+11234567891@public.test.com;reason=unconditional"
}
},
{
"CallId": "call-id-2",
"ParticipantTag": "LEG-B",
.....
"Status": "Connected"
}
]
}
}
```
下列範例顯示成功的[CallAndBridge](call-and-bridge.md)動作，因為 `SipHeaders` 參數的項目無效。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "CallAndBridge",
"Parameters":{
"CallTimeoutSeconds": 30,
"CallerIdNumber": "e164PhoneNumber", // required
"RingbackTone": { // optional
"Type": "S3",
"BucketName": "s3_bucket_name",
"Key": "audio_file_name"
},
"Endpoints":[
{
"Uri":"e164PhoneNumber", // required
"BridgeEndpointType":"PSTN" // required
}
],
"SipHeaders": {
"X-Test-Value": "String",
"User-to-User": "616d617a6f6e5f6368696d655f636f6e6e6563745f696e746567726174696f6e;encoding=hex",
"Diversion": "sip:+11234567891@public.test.com;reason=unconditional"
}
}
}
]
}
```
下列範例顯示無效`SipHeaders`參數導致的失敗[CallAndBridge](call-and-bridge.md)動作。
```
{
"SchemaVersion":"1.0",
"Sequence":3,
"InvocationEventType":"ACTION_FAILED",
"ActionData":{
"Type":"actionType",
"Parameters":{
// Parameters vary by Action Type
"SipHeaders": {
"X-AMZN": "String",
"User-to-User": "616d617a6f6e5f6368696d655f636f6e6e6563745f696e746567726174696f6e;encoding=hex",
"Diversion": "sip:+11234567891@public.test.com;reason=unconditional"
},
},
"ErrorType": "InvalidActionParameter",
"ErrorMessage": "Invalid SIP header(s) provided: X-AMZN"
},
"CallDetails":{
.....
"Participants":[
{
"CallId":"call-id-1",
"ParticipantTag":"LEG-A",
.....
"Status":"Connected"
},
{
"CallId":"call-id-2",
"ParticipantTag":"LEG-B",
.....
"Status":"Connected"
}
]
}
}
```
## 使用 SipHeaders 欄位
當您觸發 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplicationCall.html) API 時，選用`SipHeaders`欄位可讓您將自訂 SIP 標頭傳遞至外撥通話分支。有效的標頭索引鍵必須包含下列其中一項：
+ `x-` 字首
+ `User-to-User` 標頭
+ `Diversion` 標頭
`X-AMZN` 是預留標頭。如果您在 API 呼叫中使用此標頭，將會失敗。標頭的長度上限為 2048 個字元。
下列範例顯示命令列界面中具有選用`SipHeaders`參數的典型 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplicationCall.html) API。
```
create-sip-media-application-call
--from-phone-number value // (string)
--to-phone-number value // (string)
--sip-media-application-id value // (string)
--sip-headers // (map)
```
如需詳細資訊，請參閱在 [SIP 中傳輸User-to-User通話控制資訊的機制](https://datatracker.ietf.org/doc/html/rfc7433)和[在 SIP 中轉移指示](https://datatracker.ietf.org/doc/html/rfc5806)。
# 在 Amazon Chime SDK PTSN 音訊服務中使用通話詳細資訊記錄
Amazon Chime SDK 管理員可以設定 Amazon Chime SDK Voice Connectors 來存放*通話詳細資訊記錄* CDRs)。如需設定 Amazon Chime SDK Voice Connectors 以存放 CDRs 的詳細資訊，請參閱《[Amazon Chime SDK 管理指南》中的在 Amazon Chime SDK 中管理全域設定](https://docs.aws.amazon.com/chime-sdk/latest/ag/manage-global.html)。 **
啟用 CDRs 後，在每次呼叫後，SIP 媒體應用程式會將記錄傳送至 S3 儲存貯體中名為 **Amazon-Chime-SMADRs**資料夾。
下表列出 CDR 的屬性，並顯示其適當的格式。記錄包含此處針對所有呼叫列出的所有欄位。
| Value | Description |
| --- | --- |
| `"AwsAccountId":"AWS-account-ID"` | 與啟動 PSTN 用量的 SIP 媒體應用程式相關聯的 AWS 帳戶 ID |
| `"TransactionId":"transaction-ID" ` | 呼叫的交易 ID |
| `"CallId":"SIP-media-application-call-ID"` | 相關聯用量的參與者通話 ID |
| `"VoiceConnectorId":"voice-connector-ID"` | Amazon Chime SDK Voice Connector ID UUID |
| `"Status":"status"` | 呼叫狀態 （已完成、失敗） |
| `"BillableDurationSeconds":"billable-duration-in-seconds"` | 呼叫的計費持續時間，以秒為單位 |
| `"SchemaVersion":"schema-version"` | CDR 結構描述版本 |
| `"SourcePhoneNumber":"12075550155"` | E.164 起始電話號碼 |
| "SourcePhoneNumberName":"North Campus Reception" | 指派給來源電話號碼的名稱 |
| `"DestinationPhoneNumber":"13605551214"` | E.164 目的地電話號碼 |
| "DestinationPhoneNumberName":"South Campus Reception" | 指派給目的地電話號碼的名稱 |
| `"UsageType":"usage-type"` | 價格清單 API 中明細項目的使用詳細資訊 |
| `"ServiceCode":"service-code" ` | Price List API 中的服務程式碼 |
| `"Direction":"direction"` | 呼叫方向，`Outbound`或 `Inbound` |
| `"TimeStampEpochSeconds":"start-time-epochseconds"` | epoch/Unix 時間戳記格式的記錄時間戳記 |
| `"Region":"AWS-region"` | AWS Amazon Chime SDK Voice Connector 的區域 |
| `"SipRuleId":"sip-rule-id"` | 呼叫到達 PSTN 音訊服務時觸發的 SIP 規則 ID |
| `"SipApplicationId":"sip-application-id"` | 處理呼叫的 SIP 應用程式 ID |
| `"CallLegTriggerType":"trigger-type"` | 觸發呼叫的事件類型 |
| `"BillableVoiceFocusSeconds":"billable-voice-focus-in-seconds"` | Voice Focus 用量的計費數量，以秒為單位 |
# 了解 Amazon Chime SDK PTSN 音訊服務的逾時和重試
PSTN 音訊服務會與 AWS Lambda 函數同步互動。應用程式會等待 5 秒讓 AWS Lambda 函數回應，然後再重試呼叫。如果在 20 秒後未收到回應，PSTN Audio 服務將發出[掛斷](unexpected-hangups.md)。當函數傳回具有其中一個 4*XX* 狀態碼的錯誤時，根據預設，SIP 媒體應用程式只會重試一次叫用。如果您用完重試次數， 呼叫會以`480 Unavailable`錯誤碼終止。如需 AWS Lambda 錯誤的詳細資訊，請參閱[對 中的呼叫問題進行故障診斷 AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/troubleshooting-invocation.html)。
# Amazon Chime SDK PTSN 音訊服務的偵錯和故障診斷
使用以下資訊來協助您診斷和修正使用 Amazon Chime SDK PSTN 音訊服務時可能遇到的常見問題。
**Topics**
+ [檢查 Amazon Chime SDK PTSN 音訊服務的日誌](check-logs.md)
+ [在 Amazon Chime SDK PTSN 音訊服務中偵錯非預期的掛斷](unexpected-hangups.md)
+ [偵錯未預期的 ACTION\$1FAILED 事件](unexpected-action-fail.md)
# 檢查 Amazon Chime SDK PTSN 音訊服務的日誌
如果您要偵錯 SIP 媒體應用程式，請檢查 Cloudwatch 日誌是否有與應用程式相關聯的 AWS Lambda 函數。
接著，檢查與 SIP 媒體應用程式相關聯的日誌。您可以視需要設定 SIP 媒體應用程式進行記錄。如需詳細資訊，請參閱《*Amazon Chime SDK 管理員指南*》中的[使用 SIP 媒體應用程式](https://docs.aws.amazon.com/chime-sdk/latest/ag/use-sip-apps.html)。如果您啟用記錄，您可以在日誌群組中找到 Cloudwatch 上的`/aws/ChimeSipMediaApplicationSipMessages/`日誌。
# 在 Amazon Chime SDK PTSN 音訊服務中偵錯非預期的掛斷
如果您使用 PSTN 音訊服務的 AWS Lambda 函數遇到意外的掛斷或錯誤訊息，請完成下列疑難排解動作：
+ 確認您的 AWS Lambda 政策將 `lambda:InvokeFunction`許可授予 [voiceconnector.chime.amazonaws.com](http://voiceconnector.chime.amazonaws.com/) 服務主體。
+ 檢查 AWS Lambda 函數的日誌，以確保成功叫用。
+ 如果日誌顯示傳入的事件和傳回的動作，請確認在叫用 AWS Lambda 函數時，您沒有在 中傳回掛斷動作。
+ 檢查 SIP 媒體應用程式的 CloudWatch 日誌。下表列出您可能會遇到的一些訊息。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/unexpected-hangups.html)
# 偵錯未預期的 ACTION\$1FAILED 事件
如果您收到意外`ACTION_FAILED`事件，請檢查下列項目：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/unexpected-action-fail.html)
# 了解 VoiceFocus Amazon Chime SDK PTSN 音訊服務
可讓您將 Amazon Voice Focus 雜訊抑制套用至公有切換電話網路 (PSTN) 通話的傳入和傳出通話。當您套用 Amazon Voice Focus 時，它會減少背景雜訊，而不會影響人類語音。這可讓目前的發言者更容易聽到。
若要建立傳入通話分支，您可以使用 [SIP 規則](https://docs.aws.amazon.com/chime/latest/ag/manage-sip-applications.html)來呼叫具有`NewInboundCall`事件的 AWS Lambda 函數。您可以使用 [CallAndBridge](call-and-bridge.md)動作或使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplicationCall.html) API 操作來建立外撥通話分支。如需 Amazon Voice Focus 的詳細資訊，請參閱 [ Amazon Chime SDK 的雜訊消除如何運作](https://www.amazon.science/blog/how-amazon-chimes-challenge-winning-noise-cancellation-works)。
Amazon Voice Focus 可減少不必要的非語音雜訊，包括：
+ **環境噪音** - 風、風扇、自來水
+ **背景雜音 **- 草坪、搖狗
+ **前景噪音 **- 打字、換紙
**注意**
當您使用 Amazon Voice Focus 時， 會 AWS 向您收取每個通話區段的作用中通話分鐘，以及 SIP 媒體應用程式使用量的每分鐘費用。
此範例顯示典型`VoiceFocus`的動作。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "VoiceFocus",
"Parameters": {
"Enable": True|False, // required
"CallId": "call-id-1", // required
}
}
]
}
```
**Enable**
*描述* – 啟用或停用 Amazon Voice Focus
*允許的值* – `True` \$1 `False`
*必要* – 是
*預設值* — 無
**CallId**
*描述* – AWS Lambda 函數調用 中參與者`CallDetails`的 CallId
*允許的值* – 有效的呼叫 ID
*必要* – 是
*預設值* — 無
此範例顯示 `VoiceFocus`動作的成功`ACTION_SUCCESSFUL`事件。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "VoiceFocus",
"Parameters": {
"Enable": True,
"CallId": "call-id-1"
}
},
"CallDetails":{
.....
.....
"Participants":[
{
"CallId": "call-id-of-caller",
.....
"Status": "Connected"
},
{
"CallId": "call-id-of-callee",
.....
"Status": "Connected"
}
]
}
}
```
此範例顯示 `VoiceFocus`動作的典型`ACTION_FAILED`事件。
```
{
"SchemaVersion": "1.0",
"Sequence":2,
"InvocationEventType": "ACTION_FAILED",
"ActionData":{
"Type": "VoiceFocus",
"Parameters": {
"Enable": True,
"CallId": "call-id-1"
}
},
"ErrorType": "SystemException",
"ErrorMessage": "System error while running action"
},
"CallDetails":{
.....
.....
"Participants":[
{
"CallId": "call-id-of-caller",
.....
}
]
}
}
```
**錯誤處理**
基於安全考量，每個客戶帳戶 (CPS) 的 PSTN 音訊動作每秒有 5 個呼叫請求的限制。當呼叫請求超過 5 個 CPS 限制時，動作會傳回錯誤訊息。此資料表列出 `VoiceFocus`動作傳回的錯誤訊息。
| 錯誤 | 訊息 | Reason |
| --- | --- | --- |
| `ActionExecutionThrottled` | 無法執行動作。已達到每秒動作數上限。 | 每秒的 Voice Focus 動作請求數超過系統限制。 |
| `MissingRequiredActionParameter` | 缺少必要的動作參數。 | 執行動作時缺少一或多個必要參數。 |
| `SystemException` | 執行動作時發生系統錯誤。 | 執行 動作時發生系統錯誤。 |
**呼叫流程**
此圖表顯示為兩個 PSTN 呼叫之間的`CallAndBridge`動作啟用和停用 Amazon Voice Focus 的呼叫流程。
![\[啟用或停用兩個橋接 PSTN 呼叫的 Amazon Voice 焦點時的呼叫流程。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/voice_focus-pstn1.png)
對於外撥通話區段， AWS Lambda 函數會啟用來電者的 Amazon Voice 焦點，並傳回一組動作，包括 `CallAndBridge`。呼叫橋接後，`VoiceFocus`動作會傳回`ACTION_SUCCESSFUL`事件，而 Lambda 函數會傳回另一組事件，為被呼叫的人員啟用 Amazon Voice Focus。該組動作包括 `VoiceFocus`、`True`、 `Enable`和呼叫者的 ID。在來電者掛斷電話之前，不會採取進一步的動作。然後，Lambda 函數會將`Hangup`動作傳送至 SIP 媒體應用程式。應用程式會掛斷被呼叫的人員，並將 Hangup 函數傳回 Lambda 函數，而該函數不會採取進一步的動作。
# Amazon Chime SDK PSTN 音訊服務詞彙表
\$1 [A](#a) \$1 [C](#c) \$1 [E](#e) \$1 [I](#i) \$1 [L](#l) \$1 [M](#m) \$1 [N](#n) \$1 [O](#o) \$1 [P](#p) \$1 [S](#s) \$1 [T](#t) \$1 [V](#v) \$1
## A
**動作**
在 AWS Lambda 函數中，動作是您想要在通話的腿部上執行的項目，例如傳送或接收數字、加入會議等。如需 PSTN 音訊服務所支援動作的詳細資訊，請參閱 [Amazon Chime SDK PSTN 音訊服務的支援動作](specify-actions.md)。
**AWS Lambda**
一種運算服務，可讓您為幾乎任何類型的應用程式或後端服務執行程式碼，而無需佈建或管理伺服器。
**AWS Lambda 函數**
在 PSTN 音訊服務的內容中，函數會執行以回應 SIP 媒體應用程式傳遞的資料，例如撥打外撥電話。
## C
**通話詳細資訊記錄**
來自 Amazon Chime SDK Voice Connector 呼叫的資料，例如帳戶 IDs、來源電話號碼和目的地國家/地區。記錄會以物件的形式落在您帳戶中的 Amazon Simple Storage Service (S3) 儲存貯體中。如需詳細資訊，請參閱《[Amazon Chime SDK 管理員指南》中的在 Amazon Chime SDK 中管理全域設定](https://docs.aws.amazon.com/chime-sdk/latest/ag/manage-global.html)。 **如需有關記錄結構描述的資訊，請參閱本指南[在 Amazon Chime SDK PTSN 音訊服務中使用通話詳細資訊記錄](attributes.md)中的 。
**呼叫 ID**
指派給所有傳入呼叫腿部的 ID。
**呼叫分支**
呼叫的一部分。在 Amazon Chime SDK 應用程式中，呼叫可能來自有效的電話號碼、PSTN 或 Amazon Chime SDK Voice Connector。如需詳細資訊，請參閱本指南中的 [了解如何使用 Amazon Chime SDK PSTN 音訊服務通話端](call-architecture.md)。
**Carrier**
提供行動服務的公司。**無線電信業者**的簡稱。
**Amazon Chime**
由 提供的統一通訊和協作服務 AWS。
**Amazon Chime SDK**
開發人員用來將即時媒體和通訊新增至自訂通訊應用程式的軟體開發套件。
## E
**E.164**
PSTN 音訊服務中唯一接受的電話號碼格式。ITU-T 建議，數字使用 1-3 位數的國家/地區代碼，後面接著最多 12 位數的訂閱者號碼。例如：美國：`+14155552671`、英國：`+442071838750 44`、澳洲：`+61285993444`。
**端點**
硬體裝置或軟體服務，例如電話或統一通訊應用程式。
**EventBridge**
無伺服器事件匯流排服務，可讓您將應用程式連線至來自各種來源的資料。
SIP 媒體應用程式不會將資料傳送至 EventBridge。如需詳細資訊，請參閱《[Amazon Chime SDK 管理員指南》中的使用 EventBridge 自動化](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html) Amazon Chime 開發套件。 **
## I
**IVR**
互動式語音回應。一種系統，可讓人們透過語音辨識或按鍵鍵盤與電腦操作的電話系統互動。
## L
**腿部**
請參閱 [Call leg](#call-leg)。
## M
**媒體**
可在 Amazon Chime SDK 會議期間使用的音訊、視訊或聊天訊息。自訂通訊應用程式可以包含一或多個每種媒體類型。
**媒體管道**
在 Amazon Chime SDK 會議期間串流和擷取音訊、影片、訊息和事件的機制。如需詳細資訊，請參閱本指南中的 [建立 Amazon Chime SDK 媒體管道](media-pipelines.md)。
## N
**號碼可攜性**
在電信業者或統一通訊系統之間移動電話號碼的能力。
## O
**發送**
從 PSTN 接收呼叫，以及將呼叫傳遞至 VoIP 端點的程序。
## P
**參與者標籤**
指派給每個通話參與者的識別符，`LEG-A`或 `LEG-B`。
**政策**
Amazon Chime SDK 需要下列類型的政策：
+ **IAM 使用者政策** – 定義 Identity and Access Management 使用者許可的政策。
+ **會議政策** – 一種政策，可讓一個使用者在會議期間共用螢幕時控制另一個使用者的電腦，並啟用讓會議出席者透過接聽來自 Amazon Chime SDK 的電話加入會議的選項。
**PSTN**
公有切換電話網路。提供電話功能的基礎設施和服務。
**PSTN 音訊服務**
Amazon Chime SDK 服務，可讓開發人員將音訊功能新增至其通訊解決方案。
## R
**路由**
使用 Amazon Chime SDK 建立的應用程式會使用一或多個類型的路由：
+ **網路路由** – 為網路、網路之間或跨多個網路的流量選擇路徑的程序。
+ **互動路由** – 確保呼叫進入正確收件人或端點的程序。
+ **呼叫路由** – 呼叫管理功能，可將傳入呼叫排入佇列，並分發給預先定義的收件人或端點。
## S
**SBC**
工作階段邊界控制器。部署用來保護 SIP 型語音的網路元素，透過網際網路通訊協定 (VoIP) 網路。
**Sequence (序列)**
叫用 AWS Lambda 函數的事件序列。每次在呼叫期間叫用函數時，序列都會遞增。
**服務限制/服務配額**
Amazon Chime 開發套件允許的最大資源數量，例如會議、音訊串流或內容共用。如需詳細資訊，請參閱本指南[Audio](meetings-sdk.md#audio)中的 。
**SIP**
工作階段啟動通訊協定，一種訊號通訊協定，用於啟動、維護和終止即時工作階段，其中包含語音、視訊和訊息應用程式的任何組合。如需詳細資訊，請參閱 [SIP：工作階段初始化通訊協定](https://www.rfc-editor.org/rfc/rfc3261.html)。
**SIP 標頭**
AWS Lambda 函數中的參數包含呼叫控制資料，以及其他資料，例如使用者帳戶 IDs。
**SIP 媒體應用程式**
將值從 SIP 規則傳遞至目標 AWS Lambda 函數的受管物件。開發人員可以呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplication.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplication.html) API 來建立 SIP 媒體應用程式，但他們必須具有管理許可才能執行此操作。
**SIP 規則**
受管物件，會將 Amazon Chime SDK Voice Connector URIs 的電話號碼傳遞至目標 SIP 媒體應用程式。
**SIP 中繼線**
請參閱 [Amazon Chime SDK Voice Connector](#voice-connector)。
**SMA**
請參閱 SIP 媒體應用程式。
**SMA ID**
請參閱 SIP 媒體應用程式。
## T
**電信業**
電信服務供應商。
**終止**
結束呼叫的程序。
**交易**
包含一或多個呼叫分支的呼叫。如需詳細資訊，請參閱本指南中的 [了解如何使用 Amazon Chime SDK PSTN 音訊服務通話端](call-architecture.md)。
**交易 ID**
包含多個呼叫分支的交易 ID。如需詳細資訊，請參閱本指南中的 [了解如何使用 Amazon Chime SDK PSTN 音訊服務通話端](call-architecture.md)。
## V
**Amazon Chime SDK Voice Connector**
提供電話系統工作階段啟動通訊協定 (SIP) 中繼服務的物件。管理員使用 Amazon Chime SDK 管理主控台來建立管理語音連接器。如需詳細資訊，請參閱《[Amazon Chime SDK 管理員指南》中的管理 Amazon Chime SDK Voice Connectors](https://docs.aws.amazon.com/chime-sdk/latest/ag/voice-connectors.html)。 **
**Amazon Chime SDK Voice Connector 群組**
包含來自不同 AWS 區域的多個語音連接器的包裝函式。群組允許跨區域容錯移轉傳入呼叫，這會建立容錯機制。如需詳細資訊，請參閱《[Amazon Chime SDK 管理員指南》中的管理 Amazon Chime SDK Voice Connector 群組](https://docs.aws.amazon.com/chime-sdk/latest/ag/voice-connector-groups.html)。 **