本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 为 Amazon Chime 软件开发工具包 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)
+ [了解 Amazon Chime SDK PTSN 音频服务的 VoiceFocus](voice-focus.md)
+ [Amazon Chime SDK PSTN 音频服务词汇表](chm-dg-glossary.md)
# 了解 Amazon Chime SDK PSTN 音频服务的电话事件
当呼叫期间发生某些事件时，音频服务会调用您的 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 调用的事件类型。有关更多信息，请参阅本主题后面的[事件类型](#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**
以毫秒为单位的纪元时间，从参与者加入调用时开始。
**Status**
参与者是 `Connected` 或 `Disconnected`
## 事件类型
音频服务使用以下这些事件类型调用 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**
音频服务已传入调用。除非呼叫已桥接，否则此事件会在拨出呼叫时返回。
**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 函数的电话事件
音频服务调用 AWS Lambda 函数以响应不同的事件。每次调用指定调用事件类型并提供调用详细信息，包括其参与者（如适用）。以下主题描述了调用 AWS Lambda 函数的音频服务事件。
# 使用 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_cn/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"
}
]
}
}
```
此时，您可以通过使用操作列表响应调用来返回操作。如果不希望执行任何操作，则使用空列表来响应。对于每次调用，您最多可以使用 10 个操作进行响应，并且每次 AWS Lambda 调用可以调用 Lambda 函数 1,000 次。有关使用操作集进行响应的更多信息，请参阅 [使用 Amazon Chime SDK PSTN 音频服务通过操作列表响应调用](invoke-on-call-leg.md)。
# 使用 Amazon Chime SDK PSTN 音频服务接听入站呼叫
当 `NEW_INCOMING_CALL` 事件发生时，音频服务会创建一个唯一 `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 函数。
仅当列表中的所有操作都成功时，SIP 媒体应用程序才会返回 `ACTION_SUCCESSFUL`。如果列表中的任何操作失败，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://github.com/aws-samples/amazon-chime-sma-on-demand-](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording) recording
# 更新正在对 Amazon Chime SDK PTSN 音频服务进行的调用
作为 PSTN 音频服务的一部分，SIP 媒体应用程序允许您根据调用事件（例如传入调用或 DTMF 数字）调用用户定义的 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 允许您在调用处于活动状态时随时触发 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 然后为每个呼叫创建一个与会者，当准备好开始会议时，它会通知 SIP 媒体应用程序并提供加入会议的令牌。 MyMeetingService
要处理这种情况，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 并传递调用的 an `transactionId` `JoinToken` d 作为其参数的一部分。现在，此 API 调用使用 `CALL_UPDATE_REQUESTED` 事件再次触发 Lambda 函数。作为事件的一部分，`JoinToken`将 MyMeetingService 传递给 Lambda 函数，令牌用于将`JoinChimeMeeting`操作返回给 SIP 媒体应用程序，后者会中断`PlayAudio`操作并将呼叫者连接到会议。
![\[显示 UpdateSipMediaApplicationCall API 中数据流的图表。\]](http://docs.aws.amazon.com/zh_cn/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_cn/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_cn/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"
}
]
}
}
```
# 了解 Amazon Chime SDK PSTN 音频服务的 end-to-end呼叫
此使用案例提供示例代码，用于接听 PSTN 呼叫者的电话、用音频消息向呼叫者打招呼、从呼叫者那里获取会议 PIN 码、播放音频以及让呼叫者加入会议。
**调用事件和操作**
音频服务将调用事件作为 JSON 对象传递给 AWS Lambda 函数。这些对象包括调用事件类型和任何相关的元数据。 AWS Lambda 函数还以 JSON 对象的形式返回 SIP 媒体应用程序操作，这些对象包括操作类型和任何相关的元数据。
下表列出了您收到调用事件时的调用事件以及可能的 `ActionData.Type`。
| 调用事件 | ActionData.Type |
| --- | --- |
| ACTION\$1SUCCESSFUL | CallAndBridge ReceiveDigits PlayAudio PlayAudioAndGetDigits JoinChimeMeeting ModifyChimeMeetingAttendees RecordMeeting |
| ACTION\$1FAILED | CallAndBridge PlayAudio PlayAudioAndGetDigits ModifyChimeMeetingAttendees RecordMeeting |
| 挂断 | HangUp |
| DIGITS\$1RECEIVED | ReceiveDigits |
**注意**
要实现以下使用案例，您需要在您的 Amazon Chime SDK 库存中至少有一个电话号码、一个使用带 Amazon Resource Name (ARN) 的 AWS Lambda 函数的 SIP 媒体应用程序托管对象，以及一个使用电话号码作为触发器的 SIP 规则。
当 Amazon Chime SDK 接到规则中指定的电话号码的呼叫时，PSTN 音频服务会调用具有调用事件类型的 AWS Lambda 函数。`NEW_INBOUND_CALL`
```
{
"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 账户。此外，您必须向 Amazon Chime SDK 语音连接器服务主体 `voiceconnector.chime.amazonaws.com` 授予 `s3:GetObject` 权限。您可以使用 S3 控制台或命令行界面 (CLI) 完成此操作。
+ 您必须使用大小不超过 50 MB 的 PCM WAV 文件。Amazon Chime 软件开发工具包推荐 8 个 mono 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 媒体服务的数据 () `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 媒体应用程序使用事件调用该 AWS Lambda 函数。`HANGUP`
```
{
"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` 显示 `Connected` 的 `Status`，则 SIP 媒体应用程序将忽略该操作。
# 使用 Amazon Chime SDK PSTN 音频服务通过操作列表响应调用
您可以使用要对 AWS Lambda 呼叫中的各个参与者执行的操作列表来响应调用事件。每次调用最多可以使用 10 个操作进行响应，并且每次 AWS Lambda 调用可以调用 1,000 次 AWS Lambda 函数。
默认情况下，如果 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，然后将这些数据传递给 Lambda AWS 调用。这种结构无需将数据存储至外部数据库（例如 Amazon DynamoDB）中。
`TransactionAttributes`是包含key/value pairs. The objects can contain a maximum of 100 key/value成对的 [JSON 对象](https://www.w3schools.com/js/js_json_objects.asp)，这些对象的最大有效载荷大小为 20 KB。`TransactionAttributes` 结构中的数据会在交易的生命周期内保持存在。
当 AWS Lambda 函数传递`TransactionAttributes`给 SIP 媒体应用程序时，该应用程序会更新所有存储的属性。如果您传递具有现有密钥集的 `TransactionAttributes` 对象，则会更新存储的值。如果您传递不同的密钥集，则将现有值替换为来自该密钥集的值。传递一个空的 map (`{}`) 可擦除所有存储的值。
**Topics**
+ [设置 TransactionAttributes](set-trans-attributes.md)
+ [Updating TransactionAttributes](update-trans-attributes.md)
+ [清除 TransactionAttributes](clear-trans-attributes.md)
+ [处理 ACTION\$1SUCCESSFUL events](attribute-trans-success.md)
+ [无效输入](attribute-trans-invalid.md)
# 设置 TransactionAttributes
以下示例说明如何在[PlayAudio](play-audio.md)操作`TransactionAttributes`旁边设置并将属性从 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"
}
}
```
# Updating TransactionAttributes
要修改存储的 `TransactionAttributes`，使用新值更新 JSON 对象的内容。在以下示例中，密钥 `NewKey1` 和 `NewKey2` 已添加至 `TransactionAttributes`。这些密钥分别与值 `NewValue1` 和 `NewValue2` 配对。
```
{
"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": {
}
}
```
**注意**
无法通过将值设置为 `null` 来清除 `TransactionAttributes` 结构中的数据。此外，忽略 `TransactionAttribute` 结构不能清除其数据。始终使用 `TransactionAttributes` 传递空的 JSON 对象以将对象从数据中清除。
# 处理 ACTION\$1SUCCESSFUL events
以下示例显示了成功的 [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_cn/chime-sdk/latest/dg/images/call-record-sma-one-leg.png)
该呼叫只有一条分支，`callID` 为 **call-id-1**。`INCOMING` 音频轨道是从呼叫者到 SIP 媒体应用程序的音频。`OUTGOING` 音频轨道是从 SIP 媒体应用程序到呼叫者的音频。您的 SIP 媒体应用程序指定您要录制的呼叫的 `CallId`。要录制拨打电话的参与者，则指定 `INCOMING`。要录制接听电话的参与者，则指定 `OUTGOING`。要录制两个参与者，则指定 `BOTH`。
此图显示带有两个参与者的典型桥接呼叫。
![\[仅与 SIP 媒体应用程序和第二参与者通信的来电。\]](http://docs.aws.amazon.com/zh_cn/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` 音频轨道。
如果要录制呼叫者听到的所有内容，则可以通过将 **call-id-1** 指定为 `CallId` 并将 `OUTGOING` 指定为轨道录制 `OUTGOING` 音频轨道。如果要录制 `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_cn/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_cn/chime-sdk/latest/dg/images/sma-recording-case-2.png)
## 案例 3：录制多个通话分支
您可以录制多个呼叫分支。例如，假设您将呼叫桥接到参与者。当该参与者挂断电话时，电话将桥接到另一位参与者。您可以为所有三个呼叫分支启用通话录音。
此示例显示了三个单独的录音文件。第一个呼叫分支的录音捕获呼叫者、您的应用程序以及桥接到通话中的两个参与者之间的对话。第二个呼叫分支的录音捕获呼叫者和第一个参与者之间的对话。第三个呼叫分支的录音捕获呼叫者和第二个参与者之间的对话。
此案例创建了三个呼叫分支，计费适用于每个呼叫分支的开始与结束之间。也就是说，系统会向您的 S3 存储桶传送三段录音，每段都需要付费。
![\[录制多个呼叫分支的 SIP 媒体应用程序示意图。\]](http://docs.aws.amazon.com/zh_cn/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_cn/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**
*描述*— 通话录音的音频 `Track`。
*允许的值* — `BOTH`、`INCOMING` 或 `OUTGOING`
*必填* — 是
*默认值* – 无
**Destination.Type**
*描述* — 目的地类型。只允许使用 Amazon S3。
*允许的值* — Amazon S3
*必填* — 是
*默认值* – 无
**Destination.Location**
*描述* — 有效的 Amazon S3 存储桶和可选 Amazon S3 键前缀。存储桶必须有权访问 Amazon Chime SDK 语音连接器服务主体，即 voiceconnector.chime.amazonaws.com。
*允许的值* — Amazon Chime SDK 有权访问 `s3:PutObject` 和 `s3:PutObjectAcl` 操作的有效 Amazon S3 路径。
*必填* — 是
*默认值* – 无
## 指定录制目标
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 S3 路径上附加一个默认前缀 `Amazon-Chime-SMA-Call-Recordings`。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 路径。例如，您可以将 /t myRecordingBucket echnicalSupport/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 对象元数据。
| Name | 说明 |
| --- | --- |
| transaction-id | 呼叫的事务 ID。 |
| call-id | CallId AWS Lambda 函数调 CallDetails 用的参与者 |
| recording-duration | 通话录音时长（秒） |
| recording-audio-file-format | 以互联网媒体类型表示的通话录音音频文件格式 |
## 授予 Amazon S3 存储桶权限
您的目标 Amazon S3 存储桶必须与您的应用程序属于同一个 AWS 账户。此外，您必须向 Amazon Chime SDK 语音连接器服务主体，即 `voiceconnector.chime.amazonaws.com`，授予 `s3:PutObject` 和 `s3:PutObjectAcl` 的访问权限。以下示例授予适当的权限。
------
#### [ 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 媒体应用程序对 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 函数时会显示相应的错误消息。下表列出错误消息。
| 错误 | Message | 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://github.com/aws-samples/amazon-chime-sma-on-demand-](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording) 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://github.com/aws-samples/amazon-chime-sma-on-demand-](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording) recording
# PauseCallRecording
`PauseCallRecording` 操作暂停呼叫分支的录音。每次暂停录音时，录音会捕获提示暂停的音调。当您暂停时，录制会继续，但只会捕捉静音。暂停录制不会影响录制的总时长。您可以根据需要暂停和恢复录音。
以下示例暂停录制。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "PauseCallRecording",
"Parameters": {
"CallId": "call-id-1"
}
}
]
}
```
**CallId**
*描述* — `CallId` AWS Lambda 函数调用`CallDetails`中的参与者
*允许的值* — 有效的调用 ID
*必填* — 是
*默认值* – 无
参见工作示例 GitHub：[https://github.com/aws-samples/amazon-chime-sma-on-demand-](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording) recording
# ResumeCallRecording
`ResumeCallRecording` 操作会恢复呼叫分支的录制。重新开始录制之前，会播放一段简短的音调。在呼叫分支期间，您可以多次暂停和恢复录音。
以下示例恢复录制。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "ResumeCallRecording",
"Parameters": {
"CallId": "call-id-1"
}
}
]
}
```
**CallId**
*描述* — `CallId` AWS Lambda 函数调用`CallDetails`中的参与者
*允许的值* — 有效的调用 ID
*必填* — 是
*默认值* – 无
参见工作示例 GitHub：[https://github.com/aws-samples/amazon-chime-sma-on-demand-](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording) recording
# CallAndBridge
向 PSTN 电话号码或配置为 Amazon Chime SDK 语音连接器或 Amazon Chime SDK 语音连接器组的 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 创建的出站呼叫，也可以是通过事件调用 AWS Lambda 函数的 SIP 规则创建的入站呼叫。`NewInboundCall`当您对语音连接器或语音连接器群组终端节点实施 `CallAndBridge` 操作时，必须指定语音连接器或语音连接器群组的 Amazon Resource Number (ARN)。
您还可以为出站呼叫和 AWS Lambda 功能添加自定义 SIP 标头。自定义标头允许您传递楼层号和邮政编码等值。有关自定义标头的更多信息，请参阅 [在 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 分支的发件人编号
*允许的值* — E.164 格式的有效电话号码
*必填* — 是
*默认值* – 无
**Endpoints**
*描述* — 调用的终端节点
*允许的值*：
+ `BridgeEndpointType` — 适用于语音连接器和语音连接器群组 的 `AWS`，否则为 `PSTN`。
+ `Arn` — 语音连接器或语音连接器群组的 ARN。仅在 `AWS` 用作 `BridgeEndpointType` 时需要。
+ `Uri` — URI 值取决于终端节点的类型。
对于 `PSTN` 终端节点，URI 必须是有效的 E.164 电话号码。
对于 `AWS` 终端节点，URI 值设置 `Request-URI` 的 `user` 部分。您必须使用[增强的 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 语音连接器设置](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_cn/chime-sdk/latest/dg/images/call-bridge-ans-2.png)
下图显示了未应答呼叫的调用流。
![\[未应答呼叫通过 CallAndBridge 操作的流。\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/images/SMA_Bridging_NotAns.png)
**其他详细信息**
记住有关 `CallAndBridge` 操作的这些事实。
+ `CallTimeoutSeconds` — 此计时器在 B-Leg 上发送 SIP 邀请时启动。您可以设置所需的目标值，但上游运营商可以忽略该值。
+ `CallerIdNumber` — 此电话号码必须属于客户，或者是 A-Leg 的发件人号码。
+ **挂断行为和边缘情况** — 如果一个调用分支挂断，则另一个调用分支不会自动挂断调用。当向 AWS Lambda 函数发送`Hangup`事件时，必须独立断开剩余段的连接。如果调用分支仍未挂断，则将对该调用进行计费，直到该调用挂断为止。例如，以下情况可能会导致意外收费：
+ 您尝试桥接到目标电话号码。目的地占线，直接将呼叫发送到语音信箱。从音频服务的角度来看，进入语音信箱就是应答呼叫。A-Leg 挂断了，但是 B-Leg 继续收听语音信箱消息。当 B-Leg 收听时，您会被收费。
+ 作为最佳实践，使用 AWS Lambda 函数或呼叫另一端的一方独立挂断每个呼叫段。
+ **账单** — 使用 `CallAndBridge` 时，您需要为以下内容付费：
+ 为 PSTN 创建的每个调用分支（A-Leg、B-Leg 等）的活动呼叫分钟数。
+ 音频服务使用分钟数。
参见以下方面的工作示例 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-转发](https://github.com/aws-samples/amazon-chime-sma-call-forwarding)
+ [https://github.com/aws-samples/amazon-chime-sma-on-需求录音](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# Hangup
向调用的一个分支发送带有 `SipStatusCode` 的 `Hangup` 值。
当音频服务运行调用分支上的 `Hangup` 操作时：
+ 对于只有一个呼叫段的呼叫，SIP 媒体应用程序使用`HANGUP`事件调用该 AWS Lambda 函数并忽略响应。然后，调用将断开。
+ 对于桥接到另一个调用分支（分支 B）的调用分支（分支 A），如果 `Hangup` 操作与桥接调用分支（分支 B）相关联，则 PSTN 音频服务会断开桥接调用分支，然后使用分支 B 的 `HANGUP` 的事件调用 Lambda 函数。然后，PSTN 音频服务会运行从该 Lambda 调用返回的所有操作。
+ 对于桥接到另一个调用分支（分支 B）的调用分支（分支 A），如果 `Hangup` 操作与初始调用分支（分支 A）相关联，则 PSTN 音频服务会断开初始调用分支，然后使用分支 A 的 `HANGUP` 事件调用 Lambda 函数。然后，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**
*描述* — `CallDetails` 中一个已连接参与者的 `ParticipantTag`
*允许的值* — `LEG-A` 或 `LEG-B`
*必填* — 否
*默认值* — 已调用 `callLeg` 的 `ParticipantTag`，如指定 `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-转发](https://github.com/aws-samples/amazon-chime-sma-call-forwarding)
+ [https://github.com/aws-samples/amazon-chime-sma-outbound-来电通知](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-需求录音](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# JoinChimeMeeting
提供与会者加入令牌即可加入 Amazon Chime SDK 会议。为此，您可以向 AWS SDK 调用 [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**
*描述* — `CallDetails` 中一个已连接参与者的 `ParticipantTag`
*允许的值* — `LEG-A`
*必填* — 否
*默认值* — 已调用 `callLeg` 的 `ParticipantTag`，如指定 `CallId`，则忽略该值
**MeetingId**
*描述* — 与 `JoinToken` 关联的有效 Amazon Chime SDK 会议 ID。如果使用 [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空间中的 API 创建会议，则无需提供会议 ID。如果使用 [Amazon Chime SDK 会议](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 函数。
| 错误 | 消息 | Reason |
| --- | --- | --- |
| `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://github.com/aws-samples/amazon-chime-sma-update-](https://github.com/aws-samples/amazon-chime-sma-update-call) call 上的工作示例
# ModifyChimeMeetingAttendee（将音频静音和取消静音）
允许 SIP 媒体应用程序通过提供 Amazon Chime SDK 会议 ID 和与会者列表修改电话与会者的状态。
**注意**
此操作目前支持对电话与会者进行静音和取消静音操作。此外，用户必须使用 `JoinChimeMeeting` 操作加入会议。可以在 `participantTag=“LEG-B”` 上或对应的 `CallId` 上执行此操作。
此操作仅适用于从 SIP 媒体应用程序加入会议的 CallLeg `"+` *13605550122* `"`、LEG-B 或从 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
执行此操作后，音频服务始终调用 `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 媒体应用程序会调用带有特定于失败指令或 API 的错误消息的 AWS Lambda 函数。
| 错误 | Message | Reason |
| --- | --- | --- |
| `InvalidActionParameter` | `ModifyChimeMeetingAttendees Operation` 参数值无效 | `Operation` 值必须为“静音”或“取消静音”。 |
| | 会议 ID 参数值无效。 | 会议 ID 为空。 |
| | 与会者列表参数值无效。 | 与会者 ID 列表为空，或者超过最大值 100。 |
| | 对调用的操作无效。 | 调用没有桥接。 |
| | 调用未连接到 Chime Meeting。 | 与会者未连接到 Chime Meeting。 |
| | 一位或多位与会者并不是此会议的一部分。所有与会者必须是会议的一部分。 | 与会者无权修改会议中的与会者。 |
| `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://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-打电话](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**
*描述* — `CallDetails` 中一个已连接参与者的 `ParticipantTag`
*允许的值* — `LEG-A` 或 `LEG-B`
*必填* — 否
*默认值* — 已调用 `callLeg` 的 `ParticipantTag`，如指定 `CallId`，则忽略该值
**DurationInMilliseconds**
*描述* — 暂停的持续时间（以毫秒为单位）
*允许的值* — 大于 0 的整数
*必填* — 是
*默认值* – 无
参见以下方面的工作示例 GitHub：
+ [https://github.com/aws-samples/amazon-chime-sma-outbound-来电通知](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-需求录音](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# PlayAudio
在调用的任一分支上播放音频文件。音频可以重复播放任意次数。可以使用 `PlaybackTerminators` 中设置的 DTMF 数字终止正在播放的音频。
目前，Amazon Chime SDK 仅支持从 Amazon Simple Storage Service (Amazon S3) 存储桶播放音频文件。S3 存储桶必须与 SIP 媒体应用程序属于同一个 AWS 账户。此外，您必须向 Amazon Chime SDK 语音连接器服务主体授予 `s3:GetObject` 权限。您可以使用 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"
}
}
}
]
}
```
------
音频服务代表您的 Sip 媒体应用程序对 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**
*描述* — `CallDetails` 中的参与者的 `CallId`。
*允许的值* — 有效的调用 ID。
*必填* — 否，如 `ParticipantTag` 已存在。
*默认值* — 无。
**ParticipantTag**
*描述* — `CallDetails` 中一个已连接参与者的 `ParticipantTag`。
*允许的值* — `LEG-A` 或 `LEG-B`。
*必填* — 否，如 `CallId` 已存在。
*默认值* — 被调用的 `callLeg` 的 `ParticipantTag`。如果您指定 `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 语音连接器服务主体，即 voiceconnector.chime.amazonaws.com。
*允许的值* — Amazon Chime SDK 有权访问 `s3:GetObject` 操作的有效 S3 存储桶。
*必填* — 是。
*默认值* — 无。
**AudioSource.key**
*描述* — 对于 S3 源类型，`AudioSource.BucketName` 属性中指定的 S3 存储桶中的文件名。
*允许的值* — 有效的音频文件。
*必填* — 是。
*默认值* — 无。
SIP 媒体应用程序尝试从来源 URL 播放音频。您可以使用大小不超过 50MB 未压缩的原始 PCM .wav 文件。亚马逊 Chime SDK 推荐 8 个 mono 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 函数。
| 错误 | Message | 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://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-转发](https://github.com/aws-samples/amazon-chime-sma-call-forwarding)
+ [https://github.com/aws-samples/amazon-chime-sma-outbound-来电通知](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-需求录音](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
+ [https://github.com/aws-samples/amazon-chime-sma-update-打电话](https://github.com/aws-samples/amazon-chime-sma-update-call)
# PlayAudioAndGetDigits
播放音频并收集 DTMF 数字。如果发生失败，例如用户未输入正确的 DTMF 数字，该操作将播放“失败”音频，然后重播主音频，直到 SIP 媒体应用程序耗尽 `Repeat` 参数中定义的尝试次数。
您必须播放 S3 存储桶中的音频文件。S3 存储桶必须与 SIP 媒体应用程序属于同一个 AWS 账户。此外，您必须向 [Amazon Chime SDK 语音连接器服务主体](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html)授予 `s3:GetObject` 的访问权限 (`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"
}
}
}
]
}
```
------
音频服务代表您的 Sip 媒体应用程序对 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**
*描述* — `CallDetails` 中一个已连接参与者的 `ParticipantTag`
*允许的值* — `LEG-A` 或 `LEG-B`
*必填* — 否
*默认值* — 已调用 `callLeg` 的 `ParticipantTag`，如指定 `CallId`，则忽略该值
**InputDigitsRegex**
*描述* — 正则表达式模式
*允许的值* — 有效的正则表达式模式
*必填* — 否
*默认值* – 无
**AudioSource.Type**
*描述* — 音频文件来源的类型
*允许的值* — 一个 S3 存储桶
*必填* — 是
*默认值* — `"S3"`
**AudioSource.BucketName**
*描述*-对于 S3 `AudioSource.Type` 值，S3 存储桶必须与 SIP 媒体应用程序属于同一个 AWS 账户。S3 存储桶必须有权访问 [Amazon Chime SDK 语音连接器服务主体](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 语音连接器服务主体](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`操作后调用其 AWS Lambda 功能，事件类型为`ACTION_SUCCESSFUL`或`ACTION_FAILED`调用。当应用程序成功收集数字时，它会在 `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 函数并显示相应的错误消息。下表列出可能的错误消息。
| 错误 | Message | Reason |
| --- | --- | --- |
| `InvalidAudioSource` | 音频来源参数值无效。 | 出现此错误可能基于多种原因。例如，由于权限问题或 S3 存储桶问题，SIP 媒体应用程序无法访问文件。或者，由于持续时间、大小或不受支持的格式等原因，音频文件可能无法通过验证。 |
| `InvalidActionParameter` | 操作的 `CallId` 或 `ParticipantTag` 参数无效。 | `CallId`、`ParticipantTag` 或其他参数无效。 |
| `SystemException` | 运行操作时出现系统错误。 | 运行操作时出现一个系统错误。 |
当操作由于超时或重试次数过多而无法收集指定位数时，SIP 媒体应用程序将使用调用事件类型调用该 AWS Lambda 函数。`ACTION_FAILED`
```
{
"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://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-打电话](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**
*描述* — `CallDetails` 中一个已连接参与者的 `ParticipantTag`
*允许的值* — `LEG-A` 或 `LEG-B`
*必填* — 否
*默认值* — 已调用 `callLeg` 的 `ParticipantTag`，如指定 `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-来电通知](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-需求录音](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
+ [https://github.com/aws-samples/amazon-chime-sma-update-打电话](https://github.com/aws-samples/amazon-chime-sma-update-call)
# RecordAudio
允许 SIP 媒体应用程序录制给定调用 ID 的媒体。例如，语音邮件应用程序和会议参与者通知。应用程序会进行录制，直到达到您设置的持续时间，或用户按下其中一个 `RecordingTerminators`，或应用程序检测到沉默。在这些情况下，该操作会指示您的应用程序将生成的媒体文件放入指定的 S3 存储桶中。S3 存储桶必须与 SIP 媒体应用程序属于同一个 AWS 账户。此外，该操作必须给予 `s3:PutObject` 和 `s3:PutObjectAcl` 访问 Amazon Chime SDK 语音连接器服务主体 [Amazon Chime SDK 语音连接器服务主体](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html)（`voiceconnector.chime.amazonaws.com`）的权限。
**注意**
使用此功能录制的录音可能会受有关电子通信录制的法律或法规的约束。您和您的最终用户有责任遵守与录音有关的所有适用法律，包括适当通知录制会话或通信中的所有参与者正在录制会话或通信，并获得他们的许可。
以下示例向 `s3:PutObject` 和 `s3:PutObjectAcl` 提供了访问 Amazon Chime SDK 语音连接器服务主体的权限。
------
#### [ 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**
*描述* — `CallDetails` 中一个已连接参与者的 `ParticipantTag`
*允许的值* — `LEG-A` 或 `LEG-B`
*必填* — 否
*默认值* — 已调用 `callLeg` 的 `ParticipantTag`，如指定 `CallId`，则忽略该值
**RecordingDestination.Type**
*描述* — 目的地类型。仅 S3。
*允许的值* — S3
*必填* — 是
*默认值* – 无
**RecordingDestination.BucketName**
*描述* — 有效的 S3 存储桶名称。存储桶必须有权访问 [Amazon Chime SDK 语音连接器服务主体](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-50dB，例如耳语或安静的办公室
+ 200 — 60dB，例如拥挤的办公室
+ 1000 — 75dB，例如吵闹的人或音乐
*允许的值* — [1;1000]
*必填* — 否
*默认值* — 200
**RecordingTerminators**
*描述* — 列出所有可用的录制终止符。
*允许的值* — 来自 [123456789\$10\$1] 的个位数和符号的数组
*必填* — 是
*默认值* – 无
## 处理 ACTION\$1SUCCESSFUL 事件
录制结束后，Amazon Chime SDK SIP 媒体应用程序会调用该 AWS Lambda 函数，并将 ACTION\$1SUCCESSUCCESS 事件以及调用结果传递给该函数。
```
{
"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 函数时会显示相应的错误消息。下表列出可能的错误消息。
| 错误 | Message | 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://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 action](#send-digits-action)
+ [处理 ACTION\$1SUCCESSFUL events](#send-digit-success)
+ [处理 ACTION\$1FAILED events](#send-digit-fail)
+ [调用流](#send-digits-call-flow)
## 使用 SendDigits action
以下示例显示典型的 `SendDigits` 操作：
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "SendDigits",
"Parameters": {
"CallId": "call-id-1", // required
"Digits": ",,*1234,56,7890ABCD#", // required
"ToneDurationInMilliseconds": 100 // optional
}
}
]
}
```
**CallId**
*描述* — AWS Lambda 函数调用的 `CallDetails` 中参与者的 `CallId`
*允许的值* — 有效的调用 ID
*必填* — 是
*默认值* – 无
**Digits**
*描述* — 要在调用分支上发送的数字，对应于 `CallId`
*允许的值* — 0-9、\$1、\$1、A、B、C、D、逗号 (,)
*必填* — 是
*默认值* – 无
**ToneDurationInMilliseconds**
*描述* — 传输每个数字所允许的时间（以毫秒为单位）。
*允许的值* — 介于 50 和 24000 之间的任何整数
*必填* — 否
*默认值* — 250
## 处理 ACTION\$1SUCCESSFUL events
以下示例显示 `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 events
以下示例显示 `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_cn/chime-sdk/latest/dg/images/send-digits-1.png)
# Speak
您可以通过提供文本在任何调用分支上播放语音。您可以输入纯文本或语音合成标记语言 (SSML)。SSML 可以通过添加暂停、强调某些单词或更改说话风格等，更好地控制 Amazon Chime SDK 生成语音的方式。
亚马逊 Chime 软件开发工具包使用 Amazon Polly 服务进行转换。 text-to-speechAmazon 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 机器学习和人工智能服务的特定条款。
**Topics**
+ [使用 Speak action](#speak-action)
+ [处理 ACTION\$1SUCCESSFUL events](#speak-action-success)
+ [处理 ACTION\$1FAILED events](#speak-action-fail)
+ [程序流程](#speak-flow)
## 使用 Speak action
以下示例显示典型的 `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 函数调用的 `CallDetails` 中参与者的 `CallId`
*允许的值* — 有效的调用 ID
*必填* — 是
*默认值* – 无
**Text**
*描述* — 指定要合成语音的输入文本。如果指定 `ssml` 为 `TextType`，按照 SSML 格式输入文本。
*允许的值* — 字符串
*必填* — 是
*默认值* – 无
**Engine**
*描述* — 指定在处理语音合成文本时使用的引擎：标准引擎或神经引擎。
*允许的值* — standard \$1 neural
*必填* — 否
*默认值*：标准
**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 text
*必填* — 否
*默认值* – 无
**VoiceId**
*描述* — 指定要使用的语音的 ID。
*允许的值* — [Amazon Polly 语音 IDs](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-VoiceId)
*必填* — 否
*默认值* — Joanna
## 处理 ACTION\$1SUCCESSFUL events
以下示例显示了使用 Amazon Polly 的 `Joanna` 声音将文本“Hello World”合成英语语音操作的典型 `ACTION_SUCCESSFUL` 事件。
```
{
"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 events
以下示例显示了与上一个示例中使用相同事件的典型 `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` 操作引发的错误消息。
| 错误 | 消息 | Reason |
| --- | --- | --- |
| `AccessDenied` | `AWSServiceRoleForAmazonChimeVoiceConnector` 服务相关角色配置不正确。 | 用于向 Amazon Polly 发出请求的服务关联角色不存在或缺少权限。要解决这一问题，请参阅 [使用 Amazon Chime SDK 语音连接器服务相关角色](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://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_cn/chime-sdk/latest/dg/images/Speak1.png)
**在图中**
调用者使用软件电话输入注册到 SIP 媒体应用程序的号码。应用程序使用 SIP `INVITE` 法并向调用者发送 `Trying (100)` 响应。这表明下一跳服务器收到了调用请求。然后，SIP 应用程序使用 `INVITE` 联系终端节点。建立连接后，应用程序会向调用者发送 `Ringing (180)` 响应，并开始发出警报。
然后，SIP 媒体应用程序向 Lambda 函数发送 `NEW_INBOUND_CALL` 事件，Lambda 函数以包含调用者 ID 和要转换为语音的文本的 `Speak` 操作进行响应。然后，SIP 应用程序发送 `200 (OK)` 响应，表示调用已应答。该协议还启用媒体。
如果 `Speak` 操作成功并将文本转换为语音，则它会向 SIP 媒体应用程序返回一个 `ACTION_SUCCESSFUL` 事件，而该应用程序会返回下一组操作。如果操作失败，SIP 媒体应用程序会向 Lambda 函数发送 `ACTION_FAILED` 事件，而 Lambda 函数会以一组 `Hangup` 操作进行响应。应用程序挂断调用者并向 Lambda 函数返回 `HANGUP` 事件，而该函数不会执行任何进一步操作。
下图显示了为被调用者启用 `Speak` 操作的程序流程。
![\[显示为被调用者启用 Speak 操作的程序流程的图表。您可以在任何桥接调用中执行此操作。\]](http://docs.aws.amazon.com/zh_cn/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 应用程序会向 Lambda 函数发送 [CallAndBridge](call-and-bridge.md) 操作的 `ACTION_SUCCESSFUL` 事件。然后，该函数将 Speak 操作和数据返回给 SIP 应用程序，后者会转换
# SpeakAndGetDigits
通过提供文本播放语音，并从客户那里收集双音多频 (DTMF) 数字。文本可以是纯文本或者语音合成标记语言 (SSML) 增强型文本，以通过添加暂停、强调某些单词或更改说话风格以及其他支持的 SSML 功能更好地控制 Amazon Chime SDK 生成语音的方式。如果发生失败，例如用户未输入正确的 DTMF 数字，该操作将播放“失败”语音，然后重播主语音，直到 SIP 媒体应用程序耗尽 `Repeat` 参数中定义的尝试次数。
Amazon Chime SDK 使用 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/)，包括特定于 Machine Learn AWS ing 和人工智能服务的条款。
**Topics**
+ [使用 SpeakAndGetDigits action](#speak-digits-action)
+ [处理 ACTION\$1SUCCESSFUL events](#speak-digits-success)
+ [处理 ACTION\$1FAILED events](#speak-digits-fail)
+ [使用 Amazon Chime SDK 语音连接器服务相关角色](#speak-digits-policy)
## 使用 SpeakAndGetDigits action
以下示例显示典型的 `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**
*描述* — 用于朗读 `SpeechParameters.Text` 中文本的 Amazon Polly 语音的 ID。
*允许的值* — [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**
*描述* — 用于朗读 `FailureSpeechParameters.Text` 中字符串的语音的 ID。
*允许的值* — [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 events
以下示例显示典型的 `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 events
以下示例显示典型的 `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` 操作引发的错误消息。
| 错误 | 消息 | Reason |
| --- | --- | --- |
| `AccessDenied` | `AWSServiceRoleForAmazonChimeVoiceConnector` 角色配置不正确。 | 用于向 Amazon Polly 发出请求的角色不存在或缺少权限。要解决这一问题，请参阅 [使用 Amazon Chime SDK 语音连接器服务相关角色](#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 语音连接器服务相关角色
无需手动为 `Speak` 或 `SpeakAndGetDigits` 操作创建该服务相关角色。当你在 Amazon Chime 软件开发工具包控制台、或 AWS API 中创建或更新 SIP 媒体应用程序时 AWS Command Line Interface，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 Audio Lambda 函数可以执行的任务。对话在用户和机器人之间来回进行，直到机器人收集到所需的信息。对话结束后，Amazon Chime SDK 会通过操作成功事件调用您的 PSTN Audio Lambda 函数，该事件包含机器人收集的信息。您的 PSTN Audio Lambda 函数会处理信息并执行请求的任务。
音频服务为您的用户提供逼真的对话互动。例如，用户可以在音频提示结束之前打断机器人并回答问题。此外，用户还可以使用语音和 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 机器学习和人工智能服务的特定条款。
**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 函数调用中`CallDetails`参与者的描述。`CallID``StartBotConversation` 操作使用此 ID 作为机器人的 `SessionId`。呼叫中发生的所有机器人对话共享相同的对话会话。您可以使用 [Amazon Lex PutSession](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_PutSession.html) API 修改用户和机器人之间的会话状态。有关更多信息，请参阅 *Amazon Lex 开发人员指南*中的[使用 Amazon Lex v2 API 管理会话](https://docs.aws.amazon.com/lexv2/latest/dg/using-sessions.html)。
*允许的值* — 有效的调用 ID。
*必填* — 否，如 `ParticipantTag` 已存在。
*默认值* — 无。
**ParticipantTag**
*描述* — `CallDetails` 中一个已连接参与者的 `ParticipantTag`。
*允许的值* — `LEG-A`
*必填* — 否，如 `CallId` 已存在。
*默认值* — 被调用的 `callLeg` 的 `ParticipantTag`。如果您指定 `CallDetails`，则忽略该值。
**BotAliasArn**
*描述* — 您的 Lex 机器人的机器人别名 ARN。您必须在与您的 PSTN Audio 应用程序相同的 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 字符串表示形式总大小限制为 10KB。
*允许的值* —`Configuration` 对象。
*必填* — 否。
*默认值* — 无。
**Configuration.SessionState**
*描述* — 用户与 Amazon Lex V2 的会话状态。
*允许的值* —`SessionState` 对象。
*必填* — 否。
*默认值* — 无。
**Configuration.SessionState.SessionAttributes**
*描述*-表示会话特定上下文信息的 key/value 配对映射。该映射包含在 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)。
**SessionState**
用户的 Amazon Lex V2 会话的状态。
**SessionState.SessionAttributes**
表示会话特定上下文信息的 key/value 配对映射。该映射包含在您的机器人所附的 Lambda 函数和 PSTN Audio Lambda 函数之间传递的机器人对话信息。
**解释**
由 Amazon Lex 得出的可能满足客户言论的意图清单。`NluConfidence` 得分最高的意图变为意图 `SessionState`。
**解释。 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` — 存在意图信息，且您的 Lambda 函数已可以实现意图。
**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` 事件中可能返回的错误消息。
| 错误 | 说明 |
| --- | --- |
| `InvalidActionParameter` | 一个或多个操作参数无效。错误消息描述无效参数。 |
| `SystemException` | 运行操作时出现系统错误。 |
| `ResourceNotFound` | 未找到指定机器人。 |
| `ResourceAccessDenied` | 对存储桶的访问被拒绝。 |
| `ActionExecutionThrottled` | 已超出机器人对话服务限制。错误消息描述特定服务限制已超出。 |
## 授予使用机器人的权限
以下示例授予亚马逊 Chime 软件开发工具包调用 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您必须明确授予音频服务使用您的机器人的权限。服务主体必须使用条件数据块。条件数据块必须使用全局上下文键 `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 超时。您还可以在开始与机器人对话时通过会话属性配置超时，并在必要时在 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) 取消会话。如果您未提示客户使用井号键结束输入，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/)。
此外，您还需要了解以下服务限额：
+ 对于您可以通过 PSTN 音频 [StartBotConversation](#start-bot-conversation) 操作来使用的 Amazon Lex 机器人的最大数量，Amazon Chime SDK 设有服务限额。有关更多信息，请参阅《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 Chime SDK PTSN 音频服务中使用 SIP 标头
现在，当您想要与 SIP 基础设施交换呼叫上下文信息时，可以在 AWS Lambda 函数中发送和接收标头、Diversion 标头和自定义 SIP 标头。 User-To-User
+ User-to-User(UUI) 标头可用于发送呼叫控制数据。该数据由发起会话的应用程序插入，并由接收会话的应用程序使用。它不用于任何基本的 SIP 功能。例如，您可以使用调用中心中的 UUI 标头在座席之间传递有关调用的信息。
+ 转移标头用于显示调用从何处转移以及转移原因。您可以使用此标头查看来自其他 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"
}
]
}
}
```
以下示例显示了由于 `SipHeaders` 参数的输入无效而导致的成功 [CallAndBridge](call-and-bridge.md) 操作。
```
{
"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 个字符。
以下示例显示了一个典型的示例 [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)命令行界面中带有可选`SipHeaders`参数的 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呼叫控制信息和在 SIP 中传输[转移指示的](https://datatracker.ietf.org/doc/html/rfc5806)机制](https://datatracker.ietf.org/doc/html/rfc7433)。
# 在 Amazon Chime SDK PTSN 音频服务中使用呼叫详细信息记录
Amazon Chime 软件开发工具包管理员可以将 Amazon Chime SDK 语音连接器配置为*存储通话详细*记录 ()。CDRs*有关配置要存储的 Amazon Chime SDK 语音连接器的更多信息 CDRs，请参阅《亚马逊 Ch [ime 软件开发工具包管理指南》中的 “管理亚马逊 Chime SDK 中的全局设置”](https://docs.aws.amazon.com/chime-sdk/latest/ag/manage-global.html)。*
启用后，每次调用后 CDRs，SIP 媒体应用程序都会将记录发送到 S3 存储桶SMADRs中名为 **Amazon-Chime-** 的文件夹。
下表列出了 CDR 的属性并显示它们的正确格式。记录包含此处列出的所有呼叫的所有字段。
| 值 | 说明 |
| --- | --- |
| `"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 语音连接器 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" ` | 价目表 API 中的服务代码 |
| `"Direction":"direction"` | 呼叫方向，`Outbound` 或 `Inbound`。 |
| `"TimeStampEpochSeconds":"start-time-epochseconds"` | 时间戳格式的记录 epoch/Unix 的时间戳 |
| `"Region":"AWS-region"` | AWS Amazon Chime SDK 语音连接器所在区域 |
| `"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 音频服务将发出[挂断](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 政策是否向 [voiceconnector.chime.amazon](http://voiceconnector.chime.amazonaws.com/) aws.com 服务主体授予了`lambda:InvokeFunction`权限。
+ 检查您的 AWS Lambda 函数的日志，确保它已成功调用。
+ 如果日志显示传入事件和返回的操作，请确认在调用 AWS Lambda 函数时没有返回挂断操作。
+ 检查您的 SIP 媒体应用程序的 CloudWatch 日志。下表列出可能显示的一些消息。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/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_cn/chime-sdk/latest/dg/unexpected-action-fail.html)
# 了解 Amazon Chime SDK PTSN 音频服务的 VoiceFocus
能够将 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 时，会根据每个通话段的活跃通话分钟数和 SIP 媒体应用程序的每分钟使用量向您 AWS 收费。
此示例显示了一个典型的 `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**
*描述* — CallId AWS Lambda 函数调用`CallDetails`中的参与者
*允许的值* — 有效的调用 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",
.....
}
]
}
}
```
**错误处理**
出于安全考虑，PSTN 音频操作的每个客户账户（CPS）的限制为每秒 5 个调用请求。当调用请求超过 5 个 CPS 限制时，操作会返回错误消息。此表列出了 `VoiceFocus` 操作返回的错误消息。
| 错误 | Message | Reason |
| --- | --- | --- |
| `ActionExecutionThrottled` | 运行操作失败。已达到每秒最大操作数。 | 每秒的 Voice Focus 操作请求数超过系统限制。 |
| `MissingRequiredActionParameter` | 缺少必需操作参数。 | 运行操作时缺少一个或多个必需参数。 |
| `SystemException` | 运行操作时出现系统错误。 | 运行操作时出现一个系统错误。 |
**调用流**
此图表显示了针对两个 PSTN 调用之间的 `CallAndBridge` 操作启用和禁用 Amazon Voice Focus 的调用流。
![\[当您为两个桥接的 PSTN 调用启用或禁用 Amazon Voice Focus 时的调用流。\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/images/voice_focus-pstn1.png)
对于出站呼叫段，该 AWS Lambda 函数为呼叫者启用 Amazon Voice 焦点，并返回一组操作，包括`CallAndBridge`。桥接调用后，`VoiceFocus` 操作会返回一个 `ACTION_SUCCESSFUL` 事件，而 Lambda 函数会返回另一组事件，以为被呼叫者启用 Amazon Voice Focus。这组操作包括 `VoiceFocus`、`Enable`、`True` 以及调用者 ID。呼叫者挂断之前，不会进行任何操作。然后，Lambda 函数向 SIP 媒体应用程序发送 `Hangup` 操作。应用程序挂断被呼叫者，并将挂断函数发送回 Lambda 函数，Lambda 函数无需执行任何操作。
# Amazon Chime SDK PSTN 音频服务词汇表
\$1 [A](#a) \$1 [C](#c) \$1 [E](#e) \$1 [我](#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 语音连接器。有关更多信息，请参阅本指南中的[了解如何使用 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。有关更多信息，请参阅[《亚马逊 Chime 软件开发工具包管理员指南》中的 “ EventBridge使用自动化 Amaz *on Chime* 软件开发工具包](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html)”。
## 我
**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 用户策略** — 定义身份和访问管理用户权限的策略。
+ **会议策略** — 一种策略，允许一个用户在会议期间共享屏幕时控制另一个用户的计算机，并允许会议参与者选择通过接听 Amazon Chime SDK 的电话呼叫加入会议。
**PSTN**
公用交换电话网路。提供电话呼叫功能的基础设施和服务。
**PSTN 音频服务**
一种 Amazon Chime SDK 服务，使开发人员能够添加音频功能至自己的通信解决方案。
## R
**路由**
使用 Amazon Chime SDK 来创建的应用程序使用一种或多种路由类型：
+ **网络路由** — 为网络中或多个网络之间或跨多个网络的流量选择路径的过程。
+ **交互路由** — 确保呼叫转到正确的接收者或终端节点的过程。
+ **呼叫路由** — 一种呼叫管理功能，可将入站呼叫排队并分配给预定义的接收者或终端节点。
## S
**SBC**
会话边界控制器。为保护基于 SIP 的互联网协议语音 (VoIP) 网络而部署的网络元素。
**Sequence (序列)**
调用 AWS Lambda 函数的事件序列。每次在呼叫期间调用函数时，序列都会递增。
**服务限制/服务限额**
Amazon Chime SDK 允许的最大资源数量，例如会议、音频流或内容共享。有关更多信息，请参阅本指南中的 [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)用于创建 SIP 媒体应用程序的 API，但它们必须具有管理权限才能这样做。
**SIP 规则**
一种托管对象，用于将 Amazon Chime SDK 语音连接器的电话号码传递 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 语音连接器**
为电话系统提供会话启动协议 (SIP) 中继服务的对象。管理员使用 Amazon Chime SDK 管理控制台来创建和管理语音连接器。有关更多信息，请参阅 *Amazon Chime SDK 管理员指南*中的[管理 Amazon Chime SDK 语音连接器](https://docs.aws.amazon.com/chime-sdk/latest/ag/voice-connectors.html)。
**Amazon Chime SDK 语音连接器组**
包含来自不同 AWS 区域的多个语音连接器的封装器。组允许入站呼叫跨区域故障转移，从而创建容错机制。有关更多信息，请参阅 *Amazon Chime SDK 管理员指南*中的[管理 Amazon Chime SDK 语音连接器组](https://docs.aws.amazon.com/chime-sdk/latest/ag/voice-connector-groups.html)。