本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 了解调用 Amazon Chime SDK PSTN 音频服务 AWS Lambda 函数的电话事件
<a name="invoking-Lambda"></a>

音频服务调用 AWS Lambda 函数以响应不同的事件。每次调用指定调用事件类型并提供调用详细信息，包括其参与者（如适用）。以下主题描述了调用 AWS Lambda 函数的音频服务事件。

# 使用 Amazon Chime SDK PSTN 音频服务进行出站呼叫
<a name="use-create-call-api"></a>

要创建出站呼叫，您可以使用 [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 音频服务接听入站呼叫
<a name="case-1"></a>

当 `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 音频服务响应电话事件的操作
<a name="use-case-2"></a>

在音频服务中，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 音频服务接收来电者输入
<a name="case-4"></a>

您可以使用 `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 音频服务进行的调用
<a name="update-sip-call"></a>

作为 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 音频服务结束呼叫
<a name="case-5"></a>

要结束出站呼叫，您可以使用 [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呼叫
<a name="use-cases"></a>

此使用案例提供示例代码，用于接听 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 媒体应用程序将忽略该操作。