翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Amazon Chime SDK PSTN オーディオサービスの使用
**注記**
このセクションでは、Chime SDK PSTN オーディオサービスについて説明します。このサービスは、以前のバージョンのドキュメントや一部のブログ記事では「SIP メディアアプリケーション (SMA)」と呼ばれていました。今後、「SIP Media Applications」と言うと、Amazon Chime SDK コンソールと PSTN オーディオサービスに関連付けられている AWS SDK の設定項目を指します。
このセクションでは、Amazon Chime SDK 公衆交換電話網 (PSTN) Audio サービスの使用方法について説明します。PSTN オーディオサービスを使用すると、デベロッパーはサーバーレス AWS Lambda 関数の俊敏性と運用上のシンプルさを使用してカスタムテレフォニーアプリケーションを構築できます。
AWS Lambda 関数は、Amazon Chime SDK Voice Connector を使用した音声プロンプトの再生、ディジットの収集、通話の記録、PSTN およびセッション開始プロトコル (SIP) デバイスへの通話のルーティングなど、通話の動作を制御します。以下のトピックでは、呼び出しを制御する AWS Lambda 関数を構築する方法など、PSTN オーディオサービスの概要とアーキテクチャ情報について説明します。
**注記**
このセクションのトピックでは、 AWS Lambda サービスを理解していることを前提としています。詳細については AWS Lambda、[「 の開始方法 AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html)」を参照してください。また、Amazon Chime SDK のこのセクションを正しく使用するには、Amazon Chime SDK 管理者が少なくとも 1 つの SIP ルールと 1 つの SIP メディアアプリケーションを作成する必要があります。これらのタスクを完了する方法の詳細については、「Amazon Chime SDK 管理者ガイド」の「[Managing SIP media applications](https://docs.aws.amazon.com/chime-sdk/latest/ag/manage-sip-applications.html)」を参照してください。
**Topics**
+ [Amazon Chime SDK 音声名前空間への移行](voice-namespace-migration.md)
+ [Amazon Chime SDK PSTN オーディオの電話番号、SIP ルール、SIP メディアアプリケーション、および AWS Lambda 機能について](using-lambda.md)
+ [Amazon Chime SDK PSTN オーディオサービスのプログラミングモデルについて](pstn-model.md)
+ [Amazon Chime SDK PSTN オーディオの AWS Lambda 関数への呼び出しとイベントのルーティング](route-calls-events.md)
+ [Amazon Chime SDK PSTN オーディオの AWS Lambda 関数への呼び出しのルーティング (AWS CLI)](route-calls-events-cli.md)
+ [Amazon Chime SDK PSTN オーディオサービスの通話レッグの使用について](call-architecture.md)
+ [Amazon Chime SDK PSTN オーディオの通話フローについて](call-flow.md)
+ [Amazon Chime SDK PSTN オーディオサービスの AWS Lambda 関数の構築](writing-lambdas.md)
# Amazon Chime SDK 音声名前空間への移行
[Amazon Chime SDK Voice](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 名前空間は、Amazon Chime SDK 音声リソースを作成および管理する API のための専用の場所です。名前空間を使用して、Amazon Chime SDK 音声 API エンドポイントを使用可能にする任意の AWS リージョンのエンドポイントに対処します。Amazon Chime SDK を使い始めたばかりの場合は、この名前空間を使用してください。リージョンの詳細については、このガイドの「[Amazon Chime SDK で利用可能な AWS リージョン](sdk-available-regions.md)」を参照してください。
[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 名前空間を使用する既存のアプリケーションでは、更新された API と新機能を使用するために、専用の名前空間への移行を計画する必要があります。
**Topics**
+ [移行すべき理由](#first-concept-chapter)
+ [移行する前に](#voice-before-migrate)
+ [名前空間の相違点](#voice-namespace-diffs)
## 移行すべき理由
[Amazon Chime SDK Voice](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 名前空間への移行をお勧めするのは、以下の理由からです。
**API エンドポイントの選択**
Amazon Chime SDK Voice 名前空間により、[API エンドポイントを利用可能にする任意のリージョン](https://docs.aws.amazon.com/chime-sdk/latest/dg/sdk-available-regions.html)で API エンドポイントを使用できるようになります。`us-east-1` 以外の API エンドポイントを使用する場合は、Amazon Chime SDK Voice 名前空間を使用する必要があります。現在のエンドポイントの詳細については、このガイドの「[API マッピング](migrate-from-chm-namespace.md#name-end-map)」を参照してください。
**音声 API の更新および新規追加**
Amazon Chime SDK Voice 名前空間の音声 API のみ追加または更新されます。
## 移行する前に
移行する前に、名前空間の相違点に注意してください｡ 以下の表では、名前空間の一覧と説明を示しています。
| | Amazon Chime SDK Voice 名前空間 | Amazon Chime 名前空間 |
| --- | --- | --- |
| **AWS 名前空間** | `ChimeSDKVoice` | `Chime` |
| **リージョン** | 複数 | `us-east-1` のみ |
| **エンドポイント** | `https://voice-chime.region.amazonaws.com` | `service.chime.aws.amazon.com` |
| **サービスプリンシパル** | `chime.amazonaws.com` | `chime.amazonaws.com` |
| **API** | PSTN オーディオサービス用の API のみ | PSTN オーディオおよび Amazon Chime のその他の部分用の API |
| 音声コネクタ管理 | 複数のリージョン | us-east-1 |
| 音声コネクタグループ管理 | 複数のリージョン | us-east-1 |
| SIP メディアアプリケーションおよび SIP ルール管理 | 複数のリージョン | us-east-1 |
| 電話番号管理 | 複数のリージョン | us-east-1 |
| 通話分析 | 利用可能 | 利用不可 |
| 音声プロファイルドメイン | 利用可能 | 利用不可 |
| 緊急通報管理 | 複数のリージョン | us-east-1 |
| プロキシ電話セッション管理 | 複数のリージョン | us-east-1 |
| ストリーミング管理 | 複数のリージョン | us-east-1 |
| ログ記録およびメトリクス管理 | 複数のリージョン | us-east-1 |
使用可能なリージョンの詳細については、「[音声リージョン](sdk-available-regions.md#voice-regions)」を参照してください。
## 名前空間の相違点
以下のセクションでは、`Amazon Chime SDK Voice` 名前空間と `Amazon Chime` 名前空間の相違点について説明します。
**AWS 名前空間**
Amazon Chime SDK 名前空間では `Chime` という正式名を使用します。Amazon Chime SDK Voice 名前空間では `ChimeSDKVoice` という正式名を使用します。名前の正確な形式はプラットフォームによって異なります。
例えば、Node.js で AWS SDK を使用して会議を作成する場合、次のコード行を使用して名前空間に対処します。
```
const chimeVoice = AWS.Chime();
```
Amazon Chime SDK Voice 名前空間に移行するには、このコード行を新しい名前空間とエンドポイントリージョンで更新します。
```
const chimeVoice = AWS.ChimeSDKVoice({ region: "eu-central-1" });
```
**Regions**
[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 名前空間は、`us-east-1` リージョンの API エンドポイントのみをアドレス指定します。[Amazon Chime SDK Voice](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) 名前空間は、利用可能な任意のリージョンで Amazon Chime SDK 音声 API エンドポイントをアドレス指定できます。現在の音声リージョンのリストについては、本ガイドの「[Amazon Chime SDK で利用可能な AWS リージョン](sdk-available-regions.md)」を参照してください。
**エンドポイント**
[Amazon Chime SDK Voice](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 名前空間は、[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 名前空間とは異なる API エンドポイントを使用します。
音声アクションを変更するのに使用できるのは、その作成に使用したエンドポイントだけです。つまり、`eu-central-1` のエンドポイントを介して作成された音声アクションは、`eu-central-1` 経由でしか変更できないということです。また、`Chime` 名前空間を介して作成された音声アクションは、`us-east-1` の `ChimeSDKVoice` 名前空間ではアドレス指定できません。現在のエンドポイントの詳細については、このガイドの「[API マッピング](migrate-from-chm-namespace.md#name-end-map)」を参照してください。
**サービスプリンシパル**
どちらの名前空間も `chime.amazonaws.com` サービスプリンシパルを使用します。サービスへのアクセスを許可するアクセスポリシーがある場合、それらのポリシーを更新する必要はありません。
**API**
[Amazon Chime SDK Voice](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 名前空間には、音声アクションを作成および管理するための API のみが含まれています。[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 名前空間には、音声や Amazon Chime サービスのその他の部分 (会議など) のための API が含まれています。
**Tagging**
[Amazon Chime SDK Voice](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 名前空間のみがタグをサポートしています。タグの詳細については、「[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_TagResource.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_TagResource.html)」と「[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UntagResource.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UntagResource.html)」を参照してください。
**メディアリージョン**
`Chime` 名前空間を使用して、音声コネクタや SIP メディアアプリケーションなどのリソースを作成する場合、これを実行できるのは `us-east-1` と `us-west-2` だけであり、`us-east-1` エンドポイントを使用する必要があります。
これに対して、`ChimeSDKVoice` 名前空間では、`us-east-1` と `us-west-2` だけでなく、サポートされているすべてのリージョンでリソースを作成できます。リージョンカバレッジの詳細については、「[Amazon Chime SDK で利用可能な AWS リージョン](sdk-available-regions.md)」を参照してください。
# Amazon Chime SDK PSTN オーディオの電話番号、SIP ルール、SIP メディアアプリケーション、および AWS Lambda 機能について
PSTN オーディオサービスを使用する前に、Amazon Chime SDK 管理者は、電話番号をプロビジョニングし、SIP ルールおよび SIP メディアアプリケーションと呼ばれるマネージドオブジェクトを作成する必要があります。Amazon Chime SDK コンソールまたは AWS SDK を使用して、電話番号をプロビジョニングし、SIP ルールと SIP メディアアプリケーションマネージドオブジェクトをプロビジョニングできます。
以下の画像は、PSTN オーディオサービスを構成するマネージドオブジェクト間の関係を示しています。画像の数字は、画像の下のテキスト内の数字に対応しています。
![\[Amazon Chime SDK PSTN オーディオサービスのマネージドオブジェクト。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/pstn-diagram2.png)
SIP ルール (2) には電話番号と Amazon Chime SDK Voice Connector (1) のみ割り当てることができます。また、PSTN オーディオサービスで電話番号または Voice Connector をプロビジョニングする必要もあります。電話番号への着信通話、または Voice Connector からの発信通話リクエストを受信すると、SIP ルールは SIP メディアアプリケーションと関連する AWS Lambda 関数 (4) を呼び出します。 AWS Lambda 関数は、保留音楽の再生や会議への参加など、事前定義された一連のアクションを実行します。マルチリージョンの回復性を提供するために、SIP ルールは、フェイルオーバーの優先順位に従って、異なる AWS リージョン (3) の代替ターゲット SIP メディアアプリケーションを指定できます。あるターゲットで障害が発生すると、PSTN オーディオサービスは次のターゲットを試行し、またさらに次へと試行していきます。各代替ターゲットは、異なる AWS リージョンに存在する必要があることに注意してください。
さらに、複数の SIP メディアアプリケーションが特定の AWS Lambda 関数を呼び出すことができます。別の言い方をすると、 AWS Lambda 関数を作成するときに、SIP メディアアプリケーションでその関数を使用できます。
SIP メディアアプリケーションおよびルールのプロビジョニングの詳細については、「Amazon Chime SDK 管理者ガイド」の「[SIP メディアアプリケーションおよびルールの管理](https://docs.aws.amazon.com/chime-sdk/latest/ag/manage-sip-applications.html)」を参照してください。
# Amazon Chime SDK PSTN オーディオサービスのプログラミングモデルについて
PSTN オーディオサービスは、順々に AWS Lambda 関数を使用する、リクエスト/レスポンスプログラミングモデルを使用します。 AWS Lambda 関数は、着信通話と発信通話に自動的に呼び出されます。たとえば、新しい着信通話が到着すると、PSTN オーディオサービスは`NEW_INCOMING_CALL`イベントで AWS Lambda 関数を呼び出し、*Actions* と呼ばれるコマンドを待機します。例えば、アプリケーションは、音声プロンプトの再生、ディジットの収集、音声の録音、次への通話のルーティングなどのアクションを選択できます。これらの JSON 形式のアクションは、 AWS Lambda 関数からのコールバックを使用して PSTN オーディオサービスに送り返されます。
以下の例は、`PlayAudio` アクションを示しています。
```
{
"Type": "PlayAudio",
"Parameters": {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"PlaybackTerminators": ["1", "8", "#"],
"Repeat": "5",
"AudioSource": {
"Type": "S3",
"BucketName": "valid-S3-bucket-name",
"Key": "wave-file.wav"
}
}
}
```
以下の例は、`RecordAudio` アクションを示しています。
```
{
"Type": "RecordAudio",
"Parameters": {
"CallId": "call-id-1",
"DurationInSeconds": "10",
"SilenceDurationInSeconds": 3,
"SilenceThreshold": 100,
"RecordingTerminators": [
"#"
],
"RecordingDestination": {
"Type": "S3",
"BucketName": "valid-bucket-name",
"Prefix": "valid-prefix-name"
}
}
}
```
PSTN オーディオサービスがアクションを実行すると、成功または失敗のいずれかの表示で AWS Lambda 関数を再度呼び出します。
アプリケーションは、発信通話を行い、 AWS Lambda 関数を使用して通話フロー、発信者エクスペリエンス、通話コンテキストを制御することもできます。この場合、 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html) API を呼び出し、 AWS Lambda が`NEW_OUTBOUND_CALL`イベントで呼び出されます。通話が応答されたら、音声プロンプトの再生やユーザーが入力したディジットの収集などのアクションを返すことができます。[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API を使用して AWS Lambda 関数をトリガーし、タイマー、参加者のミュート、待合室を実装することもできます。
# Amazon Chime SDK PSTN オーディオの AWS Lambda 関数への呼び出しとイベントのルーティング
PSTN オーディオサービスは、着信通話を処理のために AWS Lambda 関数にルーティングするための以下の方法を提供します。
+ 着信番号に基づいて通話をルーティングできます。これを行うには、Amazon Chime SDK 管理者が、**[トリガータイプ]** が **[電話番号へ]** に設定された SIP ルールを作成します。この電話番号は、SIP ルールと同じ AWS アカウントの Amazon Chime SDK 電話番号インベントリに存在する必要があります。
+ 着信 Voice Connector SIP コールのリクエスト URI に基づいて、 AWS Lambda 関数にコールをルーティングできます。これを行うには、Amazon Chime SDK 管理者が、**[トリガータイプ]** が **[リクエスト URI ホスト名]** に設定された SIP ルールを作成します。このフィールドには、SIP ルールと同じ AWS アカウントでプロビジョニングされる Voice Connector の「アウトバウンドホスト名」フィールドで指定された完全修飾ドメイン名が含まれている必要があります。
**注記**
Request **URI ホスト名**トリガータイプを使用する場合、PSTN オーディオサービスは受信`user`部分 `Request-URI` (`@`署名の前の部分) を検証します。[拡張バッカスナウア記法を使用する必要があります](https://datatracker.ietf.org/doc/html/rfc2234)。必須の長さ: 1～36。(`,`)、 `a-z, A-Z, 0-9, &, =, +, $, /, %, -, _, !, ~, *, `() の値を使用します`.`。SIP プロバイダーが長い値を渡す必要がある場合は、代わりにカスタム SIP ヘッダーを使用します。詳細については、「[Amazon Chime SDK PTSN オーディオサービスでの SIP ヘッダーの使用](sip-headers.md)」を参照してください。
次に、管理者は、ターゲット SIP メディアアプリケーションを少なくとも 1 つプロビジョニングします。オプションで、冗長性とフェイルオーバーをサポートするために、複数の SIP メディアアプリケーションを優先順位に従ってプロビジョニングすることもできます。たとえば、2 つの異なる AWS リージョンに 2 つの SIP メディアアプリケーションをプロビジョニングし、優先順位を指定できます。SIP ルールに複数のターゲット SIP メディアアプリケーションがある場合、SIP メディアアプリケーションの Lambda 関数は、優先順位に従って呼び出されます。優先順位が最も高い SIP メディアアプリケーションの AWS Lambda 関数 (1 などの最小数) が最初に実行されます。PSTN オーディオサービスがその AWS Lambda 関数を呼び出すことができない場合、優先順位が次に高い SIP メディアアプリケーションの AWS Lambda 関数 (2 など、次に小さい番号) が呼び出されます。SIP ルールで指定されている SIP メディアアプリケーションを実行しようとしてすべて失敗すると、PSTN オーディオサービスはハングアップします。
必要な SIP ルールと SIP メディアアプリケーションがプロビジョニングされると、PSTN オーディオサービスは着信通話を AWS Lambda 関数にルーティングします。次の図は、**[電話番号へ]** トリガータイプを使用した一般的なシーケンスを示しています。
![\[[電話番号へ] トリガータイプを使用する、SIP ルールと SIP メディアアプリケーションのワークフロールールの図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/SMA Images-CS-2021-05-05-SIP Rules-PSTN-W-Lambda.png)
図中の手順を説明します。
1. PSTN オーディオサービスは、同じ AWS アカウントの SIP ルールでプロビジョニングされた電話番号への着信通話を受信します。
1. PSTN オーディオサービスが SIP ルールを評価し、優先順位が最も高い (この場合は優先度 1 の) SIP メディアアプリケーションをフェッチします。
1. その後、サービスは SIP メディアアプリケーションに関連付けられた AWS Lambda 関数を呼び出します。
1. オプション。サービスが最も高い優先順位 AWS Lambda に関連付けられた を呼び出すことができない場合、優先順位が次に高い SIP メディアアプリケーション (この場合は優先度 2) が存在する場合は実行を試みます。
1. オプション。ターゲット SIP メディアアプリケーションがすべて失敗すると、PSTN オーディオサービスは通話をハングアップします。
次の図は、**[リクエスト URI ホスト名]** トリガータイプを使用する一般的なルールを示しています。
![\[[リクエスト URI ホスト名] トリガータイプを使用するルールの図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/SMA Images-CS-2021-05-05-SIP Rules-VC-W-Lambda.png)
図中の手順を説明します。
1. PSTN オーディオサービスは、同じ AWS アカウントのプロビジョニングされた SIP ルールに一致する**リクエスト URI ホスト名**を持つ Amazon Chime SDK Voice Connector で着信通話を受信します。
1. サービスが SIP ルールを評価し、優先順位が最も低い SIP メディアアプリケーション (この場合は優先度 1 の唯一のターゲット SIP メディアアプリケーション) をフェッチします。
1. その後、サービスは SIP メディアアプリケーションに関連付けられた AWS Lambda 関数を呼び出します。
1. オプション。サービスが最低優先度 AWS Lambda に関連付けられた を呼び出すことができない場合、SIP メディアアプリケーションが存在する場合は、次に低い優先度で SIP メディアアプリケーションを実行しようとします。ここではターゲット SIP メディアアプリケーションは 1 つだけです。
1. オプション。ターゲット SIP メディアアプリケーションがすべて失敗すると、PSTN オーディオサービスは通話をハングアップします。
さらに、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html) API を使用して、発信通話を作成し、続いて AWS Lambda 関数を呼び出して追加の処理を行うこともできます。この API を使用するには、プロビジョニングされた **[SIP メディアアプリケーション ID]** をパラメータとして指定します。
最後に、 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API を使用して呼び出しがアクティブになっている間は、いつでも AWS Lambda 関数をトリガーできます。この API を使用するには、プロビジョニングされた **[SIP メディアアプリケーション ID]** をパラメータとして指定します。
# Amazon Chime SDK PSTN オーディオの AWS Lambda 関数への呼び出しのルーティング (AWS CLI)
このチュートリアルでは、Amazon Chime SDK PSTN オーディオサービスを使用して Lambda 関数へのコールルーティングを設定するプロセスについて説明します。Lambda 関数の作成、SIP メディアアプリケーションの設定、着信を処理する SIP ルールの設定方法について説明します。
## 前提条件
このチュートリアルを開始する前に、以下を実行してください。
+ をインストールします AWS CLI。詳細については、「*AWS CLI ユーザーガイド*」の「[AWS CLI の最新バージョンをインストールまたは更新](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)」を参照してください。
+ 適切な認証情報 AWS CLI を使用して を設定します。認証情報をまだ設定していない場合は、`aws configure` を実行します。
+ AWS Lambda および Amazon Chime SDK の概念について基本的な知識を持っている。
+ AWS アカウントで Amazon Chime SDK と Lambda リソースを作成および管理するための十分なアクセス許可を設定します。
+ 電話番号ベースのルーティングでは、Amazon Chime SDK 電話番号インベントリに電話番号が必要です。
+ Voice Connector ベースのルーティングでは、アカウントに Voice Connector を設定する必要があります。
## コストに関する考慮事項
このチュートリアルには、完了後に継続的な料金が発生しないようにするためのクリーンアップ手順が含まれています。詳細については、[「Amazon Chime SDK の料金](https://aws.amazon.com/chime/chime-sdk/pricing/)」を参照してください。
Amazon Chime SDK PSTN オーディオの通話ルーティングの設定を開始しましょう。
## 電話番号を検索してプロビジョニングする
電話番号トリガーを使用して SIP ルールを作成する前に、Amazon Chime SDK インベントリに電話番号が必要です。ここでは、使用可能な電話番号を検索してプロビジョニングする方法を示します。
**Example : 利用可能な電話番号を検索する**
```
# Search for available toll-free phone numbers
aws chime-sdk-voice search-available-phone-numbers \
--phone-number-type TollFree \
--country US \
--toll-free-prefix 844 \
--max-results 5 \
--region us-east-1
```
このコマンドは、米国のプレフィックス 844 の通話料無料電話番号を検索します。パラメータを変更して、さまざまなタイプの数値を検索できます。
**Example : 電話番号をプロビジョニングする**
使用可能な電話番号を見つけたら、次のコマンドを使用してプロビジョニングできます。
```
# Order a phone number
aws chime-sdk-voice create-phone-number-order \
--product-type SipMediaApplicationDialIn \
--e164-phone-numbers "+18445550100" \
--region us-east-1
```
を検索結果から実際に利用可能な電話番号`+18445550100`に置き換えます。このコマンドは、電話番号をアカウントにプロビジョニングします。
**Example : 電話番号のステータスを確認する**
電話番号を注文したら、そのステータスを確認できます。
```
# Get the phone number order status
aws chime-sdk-voice get-phone-number-order \
--phone-number-order-id abcd1234-5678-90ab-cdef-EXAMPLE55555 \
--region us-east-1
```
注文 ID を `create-phone-number-order` コマンドから返された ID に置き換えます。
**Example : インベントリ内の電話番号を一覧表示する**
インベントリ内のすべての電話番号を表示するには:
```
# List all phone numbers
aws chime-sdk-voice list-phone-numbers \
--region us-east-1
```
SIP ルールに使用できる未割り当ての電話番号を見つけるには:
```
# List unassigned phone numbers
aws chime-sdk-voice list-phone-numbers \
--region us-east-1 \
--query "PhoneNumbers[?Status=='Unassigned'].E164PhoneNumber"
```
## 通話処理用の Lambda 関数を作成する
次に、着信を処理する Lambda 関数を作成します。関数は PSTN オーディオサービスからイベントを受信し、呼び出しの処理方法に関する指示で応答します。
**Example : Lambda の IAM ロールを作成する**
Lambda 関数を作成する前に、必要なアクセス許可を付与する IAM ロールを作成する必要があります。
```
cat > lambda-trust-policy.json << EOF
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
EOF
```
```
aws iam create-role --role-name ChimeSDKLambdaRole \
--assume-role-policy-document file://lambda-trust-policy.json
```
```
aws iam attach-role-policy --role-name ChimeSDKLambdaRole \
--policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
```
これらのコマンドは、Lambda が引き受けることを許可する IAM ロールを作成し、Lambda が CloudWatch にログを書き込むためのアクセス許可を提供する基本的な実行ポリシーをアタッチします。
**Example Lambda 関数を作成します。**
次に、着信を処理するシンプルな Lambda 関数を作成します。
```
mkdir -p lambda
cat > lambda/index.js << EOF
exports.handler = async (event) => {
console.log('Received event:', JSON.stringify(event, null, 2));
// Simple call handling logic
const response = {
SchemaVersion: '1.0',
Actions: [
{
Type: 'Speak',
Parameters: {
Engine: 'neural',
Text: 'Hello! This is a test call from Amazon Chime SDK PSTN Audio.',
VoiceId: 'Joanna'
}
},
{
Type: 'Hangup',
Parameters: {
SipResponseCode: '200'
}
}
]
};
return response;
};
EOF
```
```
cd lambda
zip -r function.zip index.js
cd ..
```
```
# Get your AWS account ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
aws lambda create-function \
--function-name ChimeSDKCallHandler \
--runtime nodejs18.x \
--role arn:aws:iam::${ACCOUNT_ID}:role/ChimeSDKLambdaRole \
--handler index.handler \
--zip-file fileb://lambda/function.zip
```
この Lambda 関数は、着信通話に音声メッセージで応答し、その後ハングアップします。
**Example : Amazon Chime SDK に Lambda アクセス許可を追加する**
Lambda 関数を呼び出すアクセス許可を Amazon Chime SDK サービスに付与します。
```
# Get your AWS account ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
aws lambda add-permission \
--function-name ChimeSDKCallHandler \
--statement-id ChimeSDK \
--action lambda:InvokeFunction \
--principal voiceconnector.chime.amazonaws.com \
--source-account ${ACCOUNT_ID}
```
このコマンドにより、Amazon Chime SDK Voice Connector サービスは Lambda 関数を呼び出すことができます。
## SIP メディアアプリケーションを作成する
SIP メディアアプリケーションは、Lambda 関数を PSTN オーディオサービスに接続します。このセクションでは、Lambda 関数を使用する SIP メディアアプリケーションを作成します。
**Example : SIP メディアアプリケーションを作成する**
```
# Get your Lambda function ARN
LAMBDA_ARN=$(aws lambda get-function --function-name ChimeSDKCallHandler --query Configuration.FunctionArn --output text)
aws chime-sdk-voice create-sip-media-application \
--aws-region us-east-1 \
--name "MyCallHandlerApp" \
--endpoints "[{\"LambdaArn\":\"${LAMBDA_ARN}\"}]"
```
SIP メディアアプリケーションは、PSTN オーディオサービスと Lambda 関数間のブリッジとして機能します。
**Example : SIP メディアアプリケーション ID を取得する**
SIP メディアアプリケーションを作成したら、チュートリアルの後半で使用するために ID を取得する必要があります。
```
SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
--query "SipMediaApplications[?Name=='MyCallHandlerApp'].SipMediaApplicationId" \
--output text)
echo "SIP Media Application ID: ${SIP_MEDIA_APP_ID}"
```
SIP ルールを作成するときに必要になるため、このコマンドによって返される SIP メディアアプリケーション ID を書き留めます。
## SIP ルールを使用して通話ルーティングを設定する
SIP ルールは、着信通話を SIP メディアアプリケーションにルーティングする方法を決定します。電話番号または Voice Connector ホスト名に基づいてルールを作成できます。
**Example : 電話番号トリガーを使用して SIP ルールを作成する**
電話番号に基づいて通話をルーティングするには、次のコマンドを使用します。
```
# Get an unassigned phone number from your inventory
PHONE_NUMBER=$(aws chime-sdk-voice list-phone-numbers \
--query "PhoneNumbers[?Status=='Unassigned'].E164PhoneNumber | [0]" \
--output text)
# If no unassigned phone number is found, you'll need to provision one
if [ -z "$PHONE_NUMBER" ] || [ "$PHONE_NUMBER" == "None" ]; then
echo "No unassigned phone numbers found. Please provision a phone number first."
exit 1
fi
echo "Using phone number: ${PHONE_NUMBER}"
aws chime-sdk-voice create-sip-rule \
--name "IncomingCallRule" \
--trigger-type ToPhoneNumber \
--trigger-value "${PHONE_NUMBER}" \
--target-applications "[{\"SipMediaApplicationId\":\"${SIP_MEDIA_APP_ID}\",\"Priority\":1}]"
```
このコマンドは、電話番号への通話を SIP メディアアプリケーションにルーティングする SIP ルールを作成します。
**Example : リクエスト URI ホスト名トリガーを使用して SIP ルールを作成する**
または、着信 Voice Connector SIP コールのリクエスト URI に基づいてコールをルーティングすることもできます。
```
# Replace with your Voice Connector hostname
VOICE_CONNECTOR_HOST="example.voiceconnector.chime.aws"
aws chime-sdk-voice create-sip-rule \
--name "VoiceConnectorRule" \
--trigger-type RequestUriHostname \
--trigger-value "${VOICE_CONNECTOR_HOST}" \
--target-applications "[{\"SipMediaApplicationId\":\"${SIP_MEDIA_APP_ID}\",\"Priority\":1}]"
```
ホスト名を Voice Connector のアウトバウンドホスト名に置き換えます。
## 複数の SIP メディアアプリケーションで冗長性を設定する
冗長性とフェイルオーバーのために、同じ AWS リージョンに複数の SIP メディアアプリケーションを作成し、優先順位を指定できます。
**Example : バックアップ Lambda 関数を作成する**
まず、同じリージョンにバックアップ Lambda 関数を作成します。
```
cat > lambda/backup-index.js >< EOF
exports.handler = async (event) => {
console.log('Received event in backup handler:', JSON.stringify(event, null, 2));
// Simple call handling logic for backup
const response = {
SchemaVersion: '1.0',
Actions: [
{
Type: 'Speak',
Parameters: {
Engine: 'neural',
Text: 'Hello! This is the backup handler for Amazon Chime SDK PSTN Audio.',
VoiceId: 'Matthew'
}
},
{
Type: 'Hangup',
Parameters: {
SipResponseCode: '200'
}
}
]
};
return response;
};
EOF
```
```
cd lambda
zip -r backup-function.zip backup-index.js
cd ..
```
```
# Get your AWS account ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
aws lambda create-function \
--function-name ChimeSDKBackupHandler \
--runtime nodejs18.x \
--role arn:aws:iam::${ACCOUNT_ID}:role/ChimeSDKLambdaRole \
--handler backup-index.handler \
--zip-file fileb://lambda/backup-function.zip
```
**Example : Amazon Chime SDK の Lambda アクセス許可をバックアップ関数に追加する**
```
# Get your AWS account ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
aws lambda add-permission \
--function-name ChimeSDKBackupHandler \
--statement-id ChimeSDK \
--action lambda:InvokeFunction \
--principal voiceconnector.chime.amazonaws.com \
--source-account ${ACCOUNT_ID}
```
**Example : バックアップ SIP メディアアプリケーションを作成する**
```
# Get your backup Lambda function ARN
BACKUP_LAMBDA_ARN=$(aws lambda get-function --function-name ChimeSDKBackupHandler --query Configuration.FunctionArn --output text)
aws chime-sdk-voice create-sip-media-application \
--aws-region us-east-1 \
--name "BackupCallHandlerApp" \
--endpoints "[{\"LambdaArn\":\"${BACKUP_LAMBDA_ARN}\"}]"
# Get the backup SIP media application ID
BACKUP_SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
--query "SipMediaApplications[?Name=='BackupCallHandlerApp'].SipMediaApplicationId" \
--output text)
```
**Example : SIP ルール ID を取得する**
```
SIP_RULE_ID=$(aws chime-sdk-voice list-sip-rules \
--query "SipRules[?Name=='IncomingCallRule'].SipRuleId" \
--output text)
```
**Example : SIP ルールを更新して、優先順位を持つ両方のアプリケーションを含める**
```
aws chime-sdk-voice update-sip-rule \
--sip-rule-id ${SIP_RULE_ID} \
--target-applications "[{\"SipMediaApplicationId\":\"${SIP_MEDIA_APP_ID}\",\"Priority\":1},{\"SipMediaApplicationId\":\"${BACKUP_SIP_MEDIA_APP_ID}\",\"Priority\":2}]"
```
このコマンドは、プライマリ SIP メディアアプリケーションとバックアップ SIP メディアアプリケーションの両方をそれぞれの優先順位に含めるように SIP ルールを更新します。
## 発信通話を作成する
`CreateSIPMediaApplicationCall` API を使用して Lambda 関数を呼び出すアウトバウンド呼び出しを作成することもできます。
```
# Use a phone number from your inventory for outbound calling
FROM_PHONE_NUMBER=${PHONE_NUMBER}
TO_PHONE_NUMBER="+12065550102" # Replace with a valid destination number
aws chime-sdk-voice create-sip-media-application-call \
--from-phone-number "${FROM_PHONE_NUMBER}" \
--to-phone-number "${TO_PHONE_NUMBER}" \
--sip-media-application-id ${SIP_MEDIA_APP_ID}
```
送信先の電話番号を有効な番号に置き換えます。実際の通話を行うには、インベントリに電話番号が必要です。
## アクティブな通話中に Lambda をトリガーする
`UpdateSIPMediaApplicationCall` API を使用して、アクティブな呼び出し中に Lambda 関数をトリガーできます。
```
# Replace with an actual transaction ID from an active call
TRANSACTION_ID="txn-3ac9de3f-6b5a-4be9-9e7e-EXAMPLE33333"
aws chime-sdk-voice update-sip-media-application-call \
--sip-media-application-id ${SIP_MEDIA_APP_ID} \
--transaction-id ${TRANSACTION_ID} \
--arguments '{"action":"custom-action"}'
```
トランザクション ID は、呼び出しがアクティブなときに Lambda 関数に送信されるイベントデータで提供されます。
## リソースをクリーンアップする
このチュートリアルが終了したら、追加料金が発生しないように、作成したリソースを削除する必要があります。
**Example : SIP ルールを削除する**
```
# Get the SIP rule ID if you don't have it
SIP_RULE_ID=$(aws chime-sdk-voice list-sip-rules \
--query "SipRules[?Name=='IncomingCallRule'].SipRuleId" \
--output text)
aws chime-sdk-voice delete-sip-rule --sip-rule-id ${SIP_RULE_ID}
```
**Example : SIP メディアアプリケーションを削除する**
```
# Get SIP media application IDs if you don't have them
SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
--query "SipMediaApplications[?Name=='MyCallHandlerApp'].SipMediaApplicationId" \
--output text)
BACKUP_SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
--query "SipMediaApplications[?Name=='BackupCallHandlerApp'].SipMediaApplicationId" \
--output text)
aws chime-sdk-voice delete-sip-media-application --sip-media-application-id ${SIP_MEDIA_APP_ID}
aws chime-sdk-voice delete-sip-media-application --sip-media-application-id ${BACKUP_SIP_MEDIA_APP_ID}
```
**Example : Lambda 関数を削除する**
```
aws lambda delete-function --function-name ChimeSDKCallHandler
aws lambda delete-function --function-name ChimeSDKBackupHandler
```
**Example : IAM ロールを削除する**
```
aws iam detach-role-policy --role-name ChimeSDKLambdaRole \
--policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
aws iam delete-role --role-name ChimeSDKLambdaRole
```
**Example : 電話番号を解放する**
電話番号が不要になった場合は、リリースできます。
```
# List phone numbers
aws chime-sdk-voice list-phone-numbers
# Delete a specific phone number
aws chime-sdk-voice delete-phone-number --phone-number-id ${PHONE_NUMBER}
```
電話番号は、完全にリリースされるまで 7 日間、ReleaseInProgress」ステータスになることに注意してください。この期間中は、必要に応じて `restore-phone-number` コマンドを使用して復元できます。
## 本番環境への移行
このチュートリアルでは、Amazon Chime SDK PSTN オーディオを使用して Lambda 関数に呼び出しをルーティングする基本的な機能を示します。ただし、本番環境では、次のベストプラクティスを考慮する必要があります。
### セキュリティに関する考慮事項
+ 最小特権のアクセス許可を実装します。Lambda 関数に必要な特定のアクセス許可のみを付与するカスタム IAM ポリシーを作成します。
+ Lambda アクセス許可にソース ARN 条件を追加します。Lambda 関数を呼び出すことができる SIP メディアアプリケーションを制限します。
+ 入力検証を実装します。Lambda 関数に検証を追加して、有効なイベントのみが処理されるようにします。
+ VPC のデプロイを検討してください。セキュリティを強化するには、適切なセキュリティグループを持つ VPC 内に Lambda 関数をデプロイします。
+ 機密データを暗号化します。を使用して AWS Key Management Service 、アプリケーションで使用される機密データを暗号化します。
### アーキテクチャに関する考慮事項
+ モニタリングとログ記録を実装します。CloudWatch アラームとログを設定して、アプリケーションのヘルスとパフォーマンスをモニタリングします。
+ エラー処理を追加します。Lambda 関数に包括的なエラー処理を実装します。
+ スケーリング制限を検討してください。サービスクォータに注意し、通話量が多い場合は引き上げをリクエストします。
+ Infrastructure as Code を実装します。 CloudFormation または AWS CDK を使用してインフラストラクチャをデプロイします。
+ CI/CD パイプラインを設定します。Lambda 関数に継続的な統合とデプロイを実装します。
本番環境に対応したアプリケーションの構築の詳細については、以下を参照してください。
+ [AWS Well-Architected フレームワーク](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html)
+ [セキュリティ、アイデンティティ、コンプライアンスのベストプラクティス](https://aws.amazon.com/architecture/security-identity-compliance/)
+ [サーバーレスアプリケーションレンズ](https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/welcome.html)
## 次の手順
Amazon Chime SDK PSTN オーディオを使用して Lambda 関数に呼び出しをルーティングする方法を学習したので、より高度な機能を調べることができます。
+ Amazon Lex と統合して、インテリジェントエージェントシナリオのダイアログインタラクションを管理します。詳細については、「[Amazon Chime SDK メッセージング用の Amazon Lex V2 ボットの作成](create-lex-bot.md)」を参照してください。
+ 音声分析を設定して、通話からインサイトを取得します。詳細については、「[Amazon Chime SDK の通話分析を使用して通話からインサイトを生成する](call-analytics.md)」を参照してください。
+ 高度な通話コントロールアクションを調べて、高度な通話フローを構築します。詳細については、「[Amazon Chime SDK で通話分析の設定を使用する](using-call-analytics-configurations.md)」を参照してください。
# Amazon Chime SDK PSTN オーディオサービスの通話レッグの使用について
PSTN オーディオサービスは 1 つ以上の通話レッグで動作できます。例えば、ボイスメールを録音または配信する場合は単一の通話レッグを使用し、Amazon Chime SDK ミーティングに参加する場合は複数の通話レッグを使用します。
次の図は、単一レッグの通話のフローを示しています。
![\[単一通話レッグのアーキテクチャの図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/single-leg-architecture.png)
次の図は、複数レッグの通話のアーキテクチャを示しています。
![\[複数レッグの通話のアーキテクチャの図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/multi-leg-architecture.png)
次の図は、複数レッグのブリッジ通話のフローを示しています。
![\[複数レッグのブリッジ通話のアーキテクチャの図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/Multi-Leg-Architecture-w-Bridge.png)
# Amazon Chime SDK PSTN オーディオの通話フローについて
この図は、Amazon Chime SDK PSTN オーディオサービスと顧客の AWS Lambda 関数を介した通話の流れを示しています。この例では、アプリケーションは発信者へのプロンプトを再生し、デュアルトーンマルチ周波数 (DTMF) ディジットを収集して、それを Amazon Chime SDK ミーティングに接続しています。
図中の数字は、図の下にある説明の番号に対応しています。
![\[PSTN オーディオサービスと AWS Lambda 関数を介した基本的な通話フローの図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/pstn-call-flow-diagram.png)
図中の手順を説明します。
1. Amazon Chime SDK PSTN Audio サービスは、SIP ルールでプロビジョニングされている電話番号への通話を受信します。
1. PSTN オーディオサービスは、関連付けられた SIP メディアアプリケーションを取得し、関連付けられた AWS Lambda 関数を`NEW_INBOUND_CALL`イベント (LEG-A) で呼び出します。
1. AWS Lambda 関数は、PSTN オーディオサービスに通話に応答し`PlayAudioAndGetDigits`、発信者にオーディオファイルを再生し、発信者が入力した DTMF ディジットを収集するように指示する を含むアクションのリストを返します。
1. PSTN オーディオサービスは、通話に応答し、音声プロンプトを再生して、発信者が入力した DTMF ディジットを収集します。
1. PSTN オーディオサービスは、DTMF ディジット入力を使用して AWS Lambda 関数を呼び出します。 AWS Lambda 関数は AWS SDK を使用して、Amazon Chime SDK 会議と会議参加者を作成します。
1. AWS SDK が `MeetingId`と を返すと`AttendeeId`、 AWS Lambda 関数は Amazon Chime SDK ミーティング (LEG-B) への呼び出しに参加するアクションを返します。
1. 公衆交換電話網 (PSTN) からの発信者と Amazon Chime SDK Media サービスの間で、リアルタイム転送プロトコル (RTP) セッションが確立されます。
1. PSTN 発信者がハングアップすると、PSTN オーディオサービスは HANGUP イベントで関数を呼び出し AWS Lambda 、 AWS Lambda 関数は参加者を削除します。
# Amazon Chime SDK PSTN オーディオサービスの AWS Lambda 関数の構築
このセクションのトピックでは、PSTN オーディオサービスで使用される AWS Lambda 関数を構築する方法について説明します。
**Topics**
+ [Amazon Chime SDK PSTN オーディオサービスのテレフォニーイベントについて](pstn-invocations.md)
+ [Amazon Chime SDK PSTN オーディオサービスアクションについて](about-actions.md)
+ [Amazon Chime SDK PSTN オーディオサービスの AWS Lambda 関数を呼び出すテレフォニーイベントについて説明します。](invoking-Lambda.md)
+ [Amazon Chime SDK PSTN オーディオサービスを使用したアクションリストによる呼び出しへの応答](invoke-on-call-leg.md)
+ [Amazon Chime SDK PSTN オーディオサービスでサポートされるアクション](specify-actions.md)
+ [Amazon Chime SDK PTSN オーディオサービスでの SIP ヘッダーの使用](sip-headers.md)
+ [Amazon Chime SDK PTSN オーディオサービスでの通話詳細レコードの使用](attributes.md)
+ [Amazon Chime SDK PTSN オーディオサービスのタイムアウトと再試行について](timeouts.md)
+ [Amazon Chime SDK PTSN オーディオサービスのデバッグとトラブルシューティング](debug-pstn.md)
+ [Amazon Chime SDK PTSN オーディオサービスの VoiceFocus について](voice-focus.md)
+ [Amazon Chime SDK PSTN オーディオサービスの用語集](chm-dg-glossary.md)
# Amazon Chime SDK PSTN オーディオサービスのテレフォニーイベントについて
Audio Service は、呼び出し中に特定のイベントが発生したときに AWS AWS Lambda 関数を呼び出します。次の例はイベントを示しています。それぞれのイベントについては、この例の後のテキストで説明しています。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "event-type",
"CallDetails": {
"TransactionId": "transaction-id-1",
"AwsAccountId": "aws-acct-id-1",
"AwsRegion": "us-east-1",
"SipMediaApplicationId": "sip-media-app-id-1",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "e164PhoneNumber",
"From": "e164PhoneNumber",
"Direction": "Inbound/Outbound",
"StartTimeInMilliseconds": "1641998241509",
"Status": "Connected/Disconnected"
}
]
}
}
```
**SchemaVersion**
このイベントオブジェクトの作成に使用されたスキーマのバージョン。
**Sequence**
AWS Lambda 関数を呼び出すイベントのシーケンス。通話中に関数が呼び出されるたびに、シーケンスがインクリメントされます。
**InvocationEventType**
AWS Lambda 呼び出しをトリガーするイベントのタイプ。詳細については、このトピックで後述する「[イベントタイプ](#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` は Audio Service への通話を表します。`Outbound` は Audio Service からの通話を表します。
**StartTimeInMilliseconds**
参加者が通話に参加したときから始まるエポック時間 (ミリ秒単位)。
**Status**
参加者が `Connected` か `Disconnected` か。
## イベントタイプ
Audio Service は、以下のイベントタイプを使用して Lambda 関数を呼び出します。
**NEW\$1INBOUND\$1CALL**
SIP メディアアプリケーションに関連付けられている電話番号から新しい通話が開始されました。
**NEW\$1OUTBOUND\$1CALL**
[CreateSipMediaApplicationCall](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html) API を介して新しい発信通話が行われました。
**ACTION\$1SUCCESSFUL**
AWS Lambda 関数から返されたアクションは成功しました。成功したアクションには、成功したアクションと一致する `ActionData` が含まれます。
```
"ActionData": {
// The previous successful action
},
```
**ACTION\$1FAILED**
AWS Lambda 関数から返されたアクションは成功しませんでした。失敗したアクションには、失敗したアクションと一致する `ActionData`、エラータイプ、失敗について説明するエラーメッセージが含まれます。
```
"ActionData": {
// The previous unsuccessful action
"ErrorType": "error-type",
"ErrorMessage": "error message"
},
```
**ACTION\$1INTERRUPTED**
[UpdateSipMediaApplicationCall](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 通話によって、実行中のアクションが中断されました。`ActionData` には中断されたアクションが含まれます。
```
"ActionData": {
// The action that was interrupted
},
```
**HANGUP**
ユーザーまたはアプリケーションが通話レッグをハングアップしました。`ActionData` にはイベントに関する以下の詳細が含まれます。
```
"ActionData": {
"Type": "Hangup",
"Parameters": {
"SipResponseCode": 486,
"CallId": "c70f341a-adde-4406-9dea-1e01d34d033d",
"ParticipantTag": "LEG-A"
}
},
```
**Type**
Hangup
**Parameters**
`HANGUP` イベントに関する情報:
+ **SipResponseCode** - イベントに関連付けられたレスポンスコード。最も一般的なコードは次のとおりです。
+ **0** - 通常のクリア
+ **480** - 応答なし
+ **486** - ユーザービジー
+ **CallId** ハングアップした参加者の ID。
+ **ParticipantTag** ハングアップした参加者のタグ。
**CALL\$1ANSWERED**
Audio Service が応答し、着信通話が応答されました。このイベントは、通話がブリッジされない限り、ダイヤルアウト通話時に返されます。
**INVALID\$1LAMBDA\$1RESPONSE**
最後の AWS Lambda 呼び出しに対して提供されたレスポンスが原因で問題が発生しました。`ActionData` には以下の追加フィールドが含まれます。
```
"ErrorType": "error-type-1",
"ErrorMessage": "error-msg-1"
```
**DIGITS\$1RECEIVED**
アプリケーションは、`ReceiveDigits` アクションの完了後に DTMF ディジットを受け取りました。`ActionData` には受け取ったディジットが含まれます。
```
"ActionData": {
"ReceivedDigits": ###
// The ReceiveDigits action data
},
```
**CALL\$1UPDATE\$1REQUESTED**
[UpdateSipMediaApplicationCall](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API が呼び出されました。`ActionData` には更新リクエストに関する情報が含まれます。
```
"ActionData": {
"Type": "CallUpdateRequest",
"Parameters": {
"Arguments": {
"leg": "LEG-A"
}
}
},
}
```
**RINGING**
通話レッグの呼び出し音が鳴っています。
# Amazon Chime SDK PSTN オーディオサービスアクションについて
PSTN オーディオサービスでは、SIP メディアアプリケーションが AWS Lambda 関数をトリガーします。次に、 AWS Lambda 関数は*アクション*と呼ばれる指示のリストを返すことができます。アクションとは、数字の送受信や会議への参加など、電話のレッグで実行する項目のことです。アクションはデータを返すこともできるので、アクションはデータフィールドを持つオブジェクトと考えることができます。PSTN オーディオサービスによって呼び出されるアクションの詳細については、「[Amazon Chime SDK PSTN オーディオサービスのテレフォニーイベントについて](pstn-invocations.md)」を参照してください。
# Amazon Chime SDK PSTN オーディオサービスの AWS Lambda 関数を呼び出すテレフォニーイベントについて説明します。
Audio Service は、さまざまなイベントに応じて AWS Lambda 関数を呼び出します。各呼び出しは、呼び出しイベントタイプを指定し、該当する場合は、参加者を含む呼び出しの詳細を提供します。以下のトピックでは、 AWS Lambda 関数を呼び出す Audio Service イベントについて説明します。
# Amazon Chime SDK PSTN オーディオサービスを使用するために発信通話を行う
発信通話を行うには、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html) API を使用します。API は、指定された `SIP media application ID` のエンドポイントを呼び出します。顧客は、エンドポイントから異なるシグナリングと [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_SipMediaApplication.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_SipMediaApplication.html) アクションを提供することで、発信のフローを制御できます。
レスポンスが成功した場合、API は 202 HTTP ステータスコードと transactionId を返します。これは、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API で使用して、進行中の発信を更新できます。
次の図は、アウトバウンドコールの AWS Lambda 関数エンドポイントに対して行われた呼び出しを示しています。
![\[AWS Lambda エンドポイントに対して行われた呼び出しのプログラミングフローを示す図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/sip-api-1.png)
SIP メディアアプリケーション用に設定されたエンドポイントは、発信通話のさまざまなステータスに対して呼び出されます。顧客が通話を開始すると、Amazon Chime SDK は、`NEW_OUTBOUND_CALL` 呼び出しイベントタイプでエンドポイントを呼び出します。
この例は、`NEW_OUTBOUND_CALL` の典型的な呼び出しイベントを示しています。
```
{
"SchemaVersion": "1.0",
"Sequence": 1,
"InvocationEventType": "NEW_OUTBOUND_CALL",
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+1xxxx",
"From": "+1xxxxxxx",
"Direction": "Outbound",
"StartTimeInMilliseconds": "159700958834234"
}
]
}
}
```
イベント関連の AWS Lambda 呼び出しに対する応答は無視されます。
受信者から `RINGING` 通知を受け取ると、Amazon Chime SDK は設定されたエンドポイントを再度呼び出します。
この例は、`RINGING` の典型的な呼び出しイベントを示しています。
```
{
"SchemaVersion": "1.0",
"Sequence": 1,
"InvocationEventType": "RINGING",
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+1xxxx",
"From": "+1xxxxxxx",
"Direction": "Outbound",
"StartTimeInMilliseconds": "159700958834234"
}
]
}
}
```
イベント関連の AWS Lambda 呼び出しに対する応答は無視されます。
受信者が発信に応答しない場合、またはエラーによって発信が失敗した場合、Chime は発信を切断し、`Hangup` イベントタイプでエンドポイントを呼び出します。`Hangup` イベントタイプの詳細については、「[Amazon Chime SDK PSTN オーディオサービスを使用した発信の終了](case-5.md)」を参照してください。
発信に応答した場合、Chime は `CALL_ANSWERED` アクションでエンドポイントを呼び出します。この例は、典型的な呼び出しイベントを示しています。
```
{
"SchemaVersion": "1.0",
"Sequence": 1,
"InvocationEventType": "CALL_ANSWERED",
"CallDetails": {
""TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+1xxxx",
"From": "+1xxxxxxx",
"Direction": "Outbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
}
]
}
}
```
この時点で、アクションリストを使用して呼び出しに応答してアクションを返すことができます。アクションを実行しない場合は、空のリストで応答します。 AWS Lambda 呼び出しごとに最大 10 個のアクションで応答でき、呼び出しごとに 1,000 回 Lambda 関数を呼び出すことができます。一連のアクションによる応答の詳細については、「[Amazon Chime SDK PSTN オーディオサービスを使用したアクションリストによる呼び出しへの応答](invoke-on-call-leg.md)」を参照してください。
# Amazon Chime SDK PSTN オーディオサービスを使用した受信通話の受け取り
`NEW_INCOMING_CALL` イベントが発生すると、Audio Service は、`HANGUP` イベントが発生するまで、一意の `TransactionID` と `CallID` を作成します。
`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 オーディオサービスのテレフォニーイベントに応答してアクションを指定する
Audio Service では、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-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-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 は通話ごとに出席者を作成します。MyMeetingService は、会議を開始する準備ができたら、SIP メディアアプリケーションに通知し、会議に参加するためのトークンを提供します。
このケースを処理するには、Lambda 関数は次のロジックを実装する必要があります。
+ 新しい着信通話が届くと、Lambda が `NEW_INBOUND_CALL` イベントで呼び出されます。Lambda は `MyMeetingService` を呼び出し、現在の通話を識別する `transactionId` を渡して、`PlayAudio` アクションを返します。
+ `MyMeetingService` は、発信者を会議に追加する準備が整うと、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API を呼び出し、引数の一部として通話の `transactionId` と `JoinToken` を渡します。この API コールにより、今度は `CALL_UPDATE_REQUESTED` イベントで Lambda 関数が再度トリガーされます。MyMeetingService は、イベントの一部として `JoinToken` を Lambda 関数に渡します。このトークンを使用して、`JoinChimeMeeting` アクションを SIP メディアアプリケーションに返します。SIP メディアアプリケーションは `PlayAudio` アクションを中断し、発信者を会議に接続します。
![\[UpdateSipMediaApplicationCall API でのデータの流れを示す図。\]](http://docs.aws.amazon.com/ja_jp/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 (Accepted) を返します。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) のレスポンスで返されます。
+ **Arguments** - `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)
+ **Sequence** - 通話でのイベントのシーケンス番号
+ **InvocationEventType** - Lambda 呼び出しイベントのタイプ。ここでは `CALL_UPDATE_REQUESTED`
+ **ActionData** - `CallUpdateRequest` アクションに関連付けられたデータ
+ **Type** - アクションのタイプ。ここでは `CallUpdateRequest`
+ **Parameters** - アクションのパラメータ
+ **Arguments** - `UpdateSipMediaApplicationCall` API リクエストの一部として渡される引数
+ **CallDetails** - 現在の通話状態に関する情報
**割り込み可能なアクションと割り込みできないアクションについて**
既存のアクションの実行中に Lambda 関数が新しいアクションのリストを返すと、進行中のアクションに続くすべてのアクションが新しいアクションに置き換えられます。場合によっては、新しいアクションをすぐに実行するために、Lambda 関数が進行中のアクションを中断することがあります。
次の図は、代表的な例を示しています。ロジックについては、図の下のテキストで説明しています。
![\[進行中の SIP メディアアプリケーション通話中にアクションを置き換える方法を示す図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/update-sip-actions.png)
Action 2 が割り込み可能な場合は、これを停止し、代わりに新しい Action 1 を実行します。
Action 2 が割り込み可能でない場合は、これを完了してから新しい Action 1 を開始します。
いずれの場合も Action 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/ja_jp/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 オーディオサービスのエンドツーエンドの通話について
このユースケースでは、PSTN 発信者からの通話の受信、音声メッセージによる発信者への挨拶、発信者からの会議 PIN の取得、音声の再生、および会議への発信者の参加の例を示します。
**呼び出しイベントと アクション**
Audio Service は、呼び出しイベントを JSON オブジェクトとして AWS Lambda 関数に渡します。オブジェクトには、呼び出しイベントタイプと関連するメタデータが含まれます。また、 AWS Lambda 関数は、SIP メディアアプリケーションのアクションを JSON オブジェクトとして返し、それらのオブジェクトにはアクションタイプと関連するメタデータが含まれます。
次の表に、呼び出しイベントと、呼び出しイベントを受け取ったときに発生する可能性のある `ActionData.Type` の一覧を示します。
| 呼び出しイベント | ActionData.Type |
| --- | --- |
| ACTION\$1SUCCESSFUL | CallAndBridge ReceiveDigits PlayAudio PlayAudioAndGetDigits JoinChimeMeeting ModifyChimeMeetingAttendees RecordMeeting |
| ACTION\$1FAILED | CallAndBridge PlayAudio PlayAudioAndGetDigits ModifyChimeMeetingAttendees RecordMeeting |
| HANGUP | HangUp |
| DIGITS\$1RECEIVED | ReceiveDigits |
**注記**
次のユースケースを実装するには、Amazon Chime SDK インベントリ、Amazon リソースネーム (ARN) と共に AWS Lambda 関数を使用する SIP メディアアプリケーションのマネージドオブジェクト、および電話番号をトリガーとして使用する SIP ルールに、1 つ以上の電話番号が必要です。
Amazon Chime SDK がルールで指定された電話番号への呼び出しを受信すると、PSTN オーディオサービスは`NEW_INBOUND_CALL`呼び出しイベントタイプで AWS Lambda 関数を呼び出します。
```
{
"SchemaVersion": "1.0",
"Sequence": 1,
"InvocationEventType": "NEW_INBOUND_CALL",
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+11234567890",
"From": "+19876543210",
"Direction": "Inbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
}
]
}
}
```
AWS Lambda 関数をプログラムして、通話の詳細を検証し、後で使用するために保存できます。`NEW_INBOUND_CALL` イベントの場合、 AWS Lambda 関数はウェルカムプロンプトを再生し、会議 PIN を要求する一連のアクションで応答します。
オーディオファイルには、次の要件があります。
+ Amazon Simple Storage Service (S3) バケットから音声ファイルを再生する必要があります。S3 バケットは、SIP メディアアプリケーションと同じ AWS アカウントに属している必要があります。さらに、Amazon Chime SDK Voice Connector サービスプリンシパル (`voiceconnector.chime.amazonaws.com`) に `s3:GetObject` 許可を付与する必要があります。このためには、S3 コンソールまたはコマンドラインインターフェイス (CLI) を使用できます。
+ 50 MB 以下のサイズの PCM WAV ファイルを使用する必要があります。Amazon Chime SDK では、モノラル 8 kHz が推奨されます。
+ 各 WAV ファイルの S3 メタデータには、`{'ContentType': 'audio/wav'}` が含まれている必要があります。
```
{
"SchemaVersion": "1.0",
"Actions": [
{
"Type" : "PlayAudio",
"Parameters" : {
"CallId": "call-id-1",
"AudioSource": {
"Type": "S3",
"BucketName": "chime-meetings-audio-files-bucket-name",
"Key": "welcome-to-meetings.wav"
}
}
},
{
"Type": "PlayAudioAndGetDigits",
"Parameters" : {
"ParticipantTag": "LEG-A",
"AudioSource": {
"Type": "S3",
"BucketName": "chime-meetings-audio-files-bucket-name",
"Key": "enter-meeting-pin.wav"
},
"FailureAudioSource": {
"Type": "S3",
"BucketName": "chime-meetings-audio-files-bucket-name",
"Key": "invalid-meeting-pin.wav"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
}
}
]
}
```
SIP メディアアプリケーションは、通話レッグ A でこれらのアクションを実行します。`PlayAudioAndGetDigits`アクションが数字を受信すると、SIP メディアアプリケーションは`ACTION_SUCCESSFUL`イベントタイプで AWS Lambda 関数を呼び出します。
```
{
"SchemaVersion": "1.0",
"Sequence": 2,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "PlayAudioAndGetDigits",
"Parameters" : {
"ParticipantTag": "LEG-A",
"AudioSource": {
"Type": "S3",
"BucketName": "chime-meetings-audio-files-bucket-name",
"Key": "enter-meeting-pin.wav"
},
"FailureAudioSource": {
"Type": "S3",
"BucketName": "chime-meetings-audio-files-bucket-name",
"Key": "invalid-meeting-pin.wav"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
},
"ReceivedDigits": "12345" // meeting PIN
},
"CallDetails": {
... // same as in previous event
}
}
}
```
データに基づいて発信者を識別するように AWS Lambda 関数をプログラムできます`CallDetails`。以前に受信した会議 PIN を検証することもできます。PIN が正しいと想定し、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html) および [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateAttendee.html) API を使用して Amazon Chime SDK ミーティングを作成し、会議出席者が使用する参加トークンを生成します。 AWS Lambda 関数は、Amazon Chime SDK 会議に参加するアクションで応答します。
```
{
"SchemaVersion": "1.0",
"Actions": [
{
"Type": "JoinChimeMeeting",
"Parameters": {
"JoinToken": "meeting-attendee-join-token"
}
}
]
}
```
が有効であるとすると、SIP メディアアプリケーション`JoinToken`は Amazon Chime SDK 会議に参加し、 `ACTION_SUCCESSFUL` イベントで AWS Lambda 関数を呼び出します。 には、SIP メディアアプリケーションと Chime Media サービス (`LEG-B`) からのデータ`CallDetails`が含まれます。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type" : "JoinChimeMeeting",
"Parameters" : {
"JoinToken": "meeting-attendee-join-token"
}
},
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+11234567890",
"From": "+19876543210",
"Direction": "Inbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
},
{
"CallId": "call-id-2",
"ParticipantTag": "LEG-B",
"To": "SMA",
"From": "+17035550122",
"Direction": "Outbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Connected"
}
]
}
}
```
この時点で発信または通話レッグでのアクションの実行を停止する場合は、空のアクションセットで応答できます。
```
{
"SchemaVersion": "1.0"
"Actions": []
}
```
発信者がハングアップすると、SIP メディアアプリケーションは `HANGUP` イベントで AWS Lambda 関数を呼び出します。
```
{
"SchemaVersion": "1.0",
"Sequence": 4,
"InvocationEventType": "HANGUP",
"ActionData": {
"Type": "Hangup",
"Parameters": {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A"
}
},
"CallDetails": {
"TransactionId": "transaction-id",
"AwsAccountId": "aws-account-id",
"AwsRegion": "us-east-1",
"SipRuleId": "sip-rule-id",
"SipApplicationId": "sip-application-id",
"Participants": [
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"To": "+11234567890",
"From": "+19876543210",
"Direction": "Inbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Disconnected"
},
{
"CallId": "call-id-2",
"ParticipantTag": "LEG-B",
"To": "SMA",
"From": "+17035550122",
"Direction": "Outbound",
"StartTimeInMilliseconds": "159700958834234",
"Status": "Disconnected"
}
]
}
}
```
アクションで `Hangup` イベントに応答すると、SIP メディアアプリケーションは、他の `Participants` が `Status` として `Connected` を示した場合、そのアクションを無視します。
# Amazon Chime SDK PSTN オーディオサービスを使用したアクションリストによる呼び出しへの応答
AWS Lambda 呼び出しイベントには、呼び出しの個々の参加者に対して実行するアクションのリストで応答できます。 AWS Lambda 呼び出しごとに最大 10 個のアクションで応答でき、呼び出しごとに 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 などのアプリケーション固有の情報を保存し、そのデータを AWS Lambda 呼び出しに渡します。この構造により、Amazon DynamoDB などの外部データベースにデータを保存する必要がなくなります。
`TransactionAttributes` は、キーと値のペアが含まれる [JSON オブジェクト](https://www.w3schools.com/js/js_json_objects.asp)です。オブジェクトには最大 100 個のキーと値のペアを含めることができます。オブジェクトの最大ペイロードサイズは 20 KB です。`TransactionAttributes` 構造内のデータは、トランザクションの存続期間中、維持されます。
AWS Lambda 関数が SIP メディアアプリケーション`TransactionAttributes`に渡すと、アプリケーションは保存された属性を更新します。既存のキーセットが含まれる `TransactionAttributes` オブジェクトを渡す場合は、保存されている値を更新します。別のキーセットを渡す場合は、既存の値を、その別のキーセットの値に置き換えます。空のマップ (`{}`) を渡すと、保存されている値はすべて消去されます。
**Topics**
+ [TransactionAttributes の設定](set-trans-attributes.md)
+ [TransactionAttributes の更新](update-trans-attributes.md)
+ [TransactionAttributes のクリア](clear-trans-attributes.md)
+ [ACTION\$1SUCCESSFUL イベントの処理](attribute-trans-success.md)
+ [無効な入力](attribute-trans-invalid.md)
# TransactionAttributes の設定
次の例は、 [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"
}
}
```
# 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 イベントの処理
次の例は、成功した [PlayAudio](play-audio.md) が、`CallDetails ` の一部として、保存された `TransactionAttributes` をどのように送信するかを示しています。
```
{
"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` アクションを返す必要はありません。録音を開始および停止できるのは、1 つの通話レッグにつき 1 回だけです。
Amazon Chime SDK は、ユーザーが選択した Amazon S3 バケットに通話録音を配信します。バケットは AWS アカウントに属している必要があります。通話が停止すると、SIP メディアアプリケーションは [StartCallRecording](start-call-recording.md) アクションの `Destination` パラメータで指定されたフォルダに録音を配信します。Amazon Chime SDK は、オープンな WAV フォーマットで通話を録音します。着信トラックと発信トラックを録音する通話ではステレオモードを使用します。着信トラックは左チャネル、発信トラックは右チャネルです。着信トラックまたは発信トラックだけを録音する場合、システムはモノモードを使用します。
**注記**
この機能を使用して作成された録音は、電子通信記録に関する法律または規制の対象となる場合があります。録音に関するすべての適用法を遵守することは、お客様とそのエンドユーザーの責任です。これには、録音セッションまたは通信のすべての参加者にセッションまたは通信が録音されていることを適切に通知し、同意を得ることを含みます。
## 通話録音の請求
Amazon Chime SDK では、通話レッグの通話録音が有効になっている時間、およびすべての一時停止を含む時間について、1 分単位で請求されます。通話録音が Amazon S3 バケットに配信されると、通話録音の使用料金が請求されます。
# オーディオトラックの録音
通話の着信トラックまたは発信トラックのみ、または通話の両方のトラックを録音できます。
この画像は、1 レッグ (ブリッジを使わない) 一般的な着信を示しています。
![\[SIP メディアアプリケーションとのみ通信する着信。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/call-record-sma-one-leg.png)
この通話には `callID` が **call-id-1** である 1 レッグしかありません。`INCOMING` オーディオトラックは、発信者から SIP メディアアプリケーションへのオーディオです。`OUTGOING` オーディオトラックは、SIP メディアアプリケーションから発信者へのオーディオです。SIP メディアアプリケーションは、録音したい通話の `CallId` を指定します。通話を発信した参加者を録音するには、`INCOMING` を指定します。通話に応答した参加者を録音するには、`OUTGOING` を指定します。両方の参加者を録音するには、`BOTH` を指定します。
この図は、2 人の参加者による一般的なブリッジ通話を示しています。
![\[SIP メディアアプリケーションと 2 人目の参加者と通信する着信。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/call-record-sma-bridged.png)
この例では、通話には 2 つの通話レッグ **call-id-1** と **call-id-2** があり、**call-id-1** は **call-id-2** にブリッジされます。これにより、4 つのオーディオトラック、つまり両方の通話 ID について着信音声ストリームと発信音声ストリームが作成されます。どの通話 ID とオーディオトラックを録音するかを指定できます。例えば、着信側参加者からのオーディオトラックを録音する場合は、**call-id-2** を `CallId` として、`INCOMING` をトラックとして指定して、`INCOMING` オーディオトラックを録音します。
発信者に聞こえるすべてを録音したい場合は、**call-id-1** を `CallId` として、`OUTGOING` をトラックとして指定して、`OUTGOING` オーディオトラックを録音します。`Caller` が話したり聞いたりしたオーディオをすべて録音したい場合は、`call-id-1` を `CallId` として、`BOTH` をトラックとして指定して、`BOTH` オーディオトラックを録音します。
# サンプルユースケース
SIP メディアアプリケーションは、通話録音アクションを構成要素として提供します。これにより、ビジネスユースケースに合わせた通話録音ソリューションを柔軟に構築できます。以下のケースでは、一般的なユースシナリオを取り上げます。
**Topics**
+ [ケース 1: SIP アクションを伴う 1 レッグ通話の録音](#recording-case-1)
+ [ケース 2: ブリッジ通話での音声の選択的な録音](#recording-case-2)
+ [ケース 3: 複数通話レッグの録音](#recording-case-3)
+ [ケース 4: 一時停止と再開を伴うオンデマンド録音](#on-demand-pause-resume)
## ケース 1: SIP アクションを伴う 1 レッグ通話の録音
発信者と、SIP メディアアプリケーションのアクション ([PlayAudio](play-audio.md) や [PlayAudioAndGetDigits](play-audio-get-digits.md) アクションなど) によって生成されるすべての音声を録音できます。録音中に発信者が数字を押すと、その数字のトーンが録音されます。この例では `PlayAudioAndGetDigits` アクションを使用していますが、自動音声応答 (IVR) は SIP メディアアプリケーションの複雑な一連のアクションでもかまいません。
この例では、SIP メディアアプリケーションは、発信者と SIP メディアアプリケーション自体の間の両方のオーディオトラックを録音します。通話が確立されると録音が開始され、発信者が切断すると録音が停止します。通話が確立されると請求が開始され、発信者が切断すると請求が停止します。
![\[SIP メディアアプリケーションが、この場合は発信者とアプリ自身との間で 2 つのオーディオトラックを録音している図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/sma-recording-case-1.png)
## ケース 2: ブリッジ通話での音声の選択的な録音
1 人の通話参加者のオーディオトラックを選択的に録音できます。この機能を使用して、特定の参加者に対してのみ通話の録音を選択的に有効にできます。
この例では、SIP メディアアプリケーションは、**call-id-2** を `CallId` として、`INCOMING` をトラックとして指定して、着信側と SIP メディアアプリケーション自体の間の着信オーディオトラックを録音します。通話録音は、発信者が着信側にブリッジ接続された時点で開始され、請求も開始されます。着信側が切断すると録音が停止し、請求も終了します。この録音には着信側のオーディオトラックしか含まれていません。
![\[1 つのトラックを選択的に録音する SIP メディアアプリケーションの図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/sma-recording-case-2.png)
## ケース 3: 複数通話レッグの録音
複数の通話レッグを録音できます。例えば、通話を参加者にブリッジするとします。その参加者が切断すると、通話は別の参加者にブリッジされます。3 つの通話レッグすべてで通話録音を有効にできます。
この例では、3 つの別々の録音ファイルを示しています。最初の通話レッグの録音では、発信者、アプリケーション、および通話にブリッジされた 2 人の参加者の間の会話がキャプチャされます。2 番目の通話レッグの録音では、発信者と最初の参加者との会話がキャプチャされます。3 番目の通話レッグの録音では、発信者と 2 番目の参加者との会話をキャプチャされます。
このケースでは 3 つの通話レッグが作成され、各通話レッグの開始から終了まで課金が行われます。別の言い方をすれば、システムが 3 つの録音を S3 バケットに配信し、それぞれに課金されるということです。
![\[複数の通話レッグを録音する SIP メディアアプリケーションの図。\]](http://docs.aws.amazon.com/ja_jp/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) を使用して、オンデマンドで通話録音を開始、停止、一時停止、再開できます。`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/ja_jp/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 Voice Connector サービスプリンシパル (voiceconnector.chime.amazonaws.com) へのアクセス許可を持つ必要があります。
使用できる値 – Amazon Chime SDK が `s3:PutObject` および `s3:PutObjectAcl` アクションへのアクセスk許可を持つ有効な 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 パスの一般的な形式を示しています。例えば、myRecordingBucket/technicalSupport/english を `Location` として指定できます。
```
myRecordingBucket/technicalSupport/english/2019/03/01/2019–03–01–17–10–00–010_c4640e3b1478–40fb–8e38-6f6213adf70b_7ab7748e–b47d–4620–ae2c–152617d3333c.wav
```
次の例は、Amazon S3 パス内のデータを示しています。
```
s3Bucket/yourObjectKeyPrefix/year/month/date/year-month-date-hour-minute-second-millisecond_transactionId_callId.wav
```
Amazon S3 バケットに送信される録音には、通話レッグに関する追加の [Amazon S3 オブジェクトメタデータ](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)が含まれます。次の表に、サポートされている Amazon S3 オブジェクトメタデータを示します。
| 名前 | 説明 |
| --- | --- |
| transaction-id | 通話のトランザクション ID |
| call-id | AWS Lambda 関数呼び出しの CallDetails の参加者の CallIdCallId |
| recording-duration | 通話録音時間 (秒) |
| recording-audio-file-format | インターネットメディアタイプとして表される通話録音音声オーディオファイル形式 |
## Amazon S3 バケットのアクセス許可の付与
送信先の Amazon S3 バケットは、アプリケーションと同じ AWS アカウントに属している必要があります。さらに、Amazon Chime SDK Voice Connector サービスプリンシパル `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 関数を呼び出します。次の表に、エラーメッセージを示します。
| エラー | メッセージ | 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-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# StopCallRecording
`StopCallRecording` アクションは通話レッグの録音を停止します。通話が終了すると録音が自動的に停止し、`StopCallRecording` アプリケーションはアクションを明示的に返す必要はありません。通話レッグの録音が停止すると、再開することはできず、録音は `StartCallRecording` アクションで指定された宛先に配信されます。
次の例では、`call-id-1` 通話レッグの録音を停止します。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "StopCallRecording",
"Parameters": {
"CallId": "call-id-1"
}
}
]
}
```
**CallId**
*説明* – `CallId` AWS Lambda 関数呼び出し`CallDetails`の の参加者の説明
*使用できる値* – 有効な通話 ID
*必須* – はい
*デフォルト値* – なし
GitHub の実例を参照してください: [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# PauseCallRecording
`PauseCallRecording` アクションは通話レッグの録音を一時停止します。録音を一時停止するたびに、一時停止を示すトーンが録音されます。一時停止しても録音は継続しますが、キャプチャされるのは無音だけです。録音を一時停止しても、録音の合計時間には影響しません。録音は、必要に応じて、一時停止および再開できます。
次の例では、録音を一時停止します。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "PauseCallRecording",
"Parameters": {
"CallId": "call-id-1"
}
}
]
}
```
**CallId**
*説明* – `CallId` AWS Lambda 関数呼び出し`CallDetails`の の参加者の説明
*使用できる値* – 有効な通話 ID
*必須* – はい
*デフォルト値* – なし
GitHub の実例を参照してください: [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# ResumeCallRecording
`ResumeCallRecording` アクションは通話レッグの録音を再開します。録音が再開される前に、短いトーンが再生されます。通話レッグの間は、録音を複数回一時停止および再開できます。
次の例では、録音を再開します。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "ResumeCallRecording",
"Parameters": {
"CallId": "call-id-1"
}
}
]
}
```
**CallId**
*説明* – `CallId` AWS Lambda 関数呼び出し`CallDetails`の の参加者の説明
*使用できる値* – 有効な通話 ID
*必須* – はい
*デフォルト値* – なし
GitHub の実例を参照してください: [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# CallAndBridge
PSTN 電話番号、または Amazon Chime SDK Voice Connector または Amazon Chime SDK Voice Connector グループとして設定された SIP トランクへの発信通話を作成し、それを既存の通話とブリッジします。電話番号に電話をかけるときは `PSTN` を使用し、SIP トランクに電話をかけるときは `AWS` を使用します。
既存の呼び出しは、 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html) API を使用して作成されたアウトバウンド呼び出し、または`NewInboundCall`イベントで関数を AWS Lambda 呼び出す SIP ルールによって作成されたインバウンド呼び出しです。Voice Connector または Voice Connector グループのエンドポイントに `CallAndBridge` アクションを実装する場合、Voice Connector または Voice Connector グループの Amazon リソース番号 (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
}],
}
}
]
}
```
次の例は、Voice Connector または Voice Connector グループとカスタム 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 レッグの From 番号
使用できる値 – E.164 形式の有効な電話番号
*必須* – はい
*デフォルト値* – なし
**Endpoints**
説明 - 通話のエンドポイント
*許可される値:*
+ `BridgeEndpointType` – Voice Connector および Voice Connector グループの場合は `AWS`、それ以外の場合は `PSTN`。
+ `Arn` – Voice Connector または Voice Connector グループの ARN。`AWS` を `BridgeEndpointType` として使用する場合にのみ必須です。
+ `Uri` – URI 値はエンドポイントのタイプによって異なります。
`PSTN` エンドポイントの場合、URI は有効な E.164 電話番号でなければなりません。
`AWS` エンドポイントでは、URI 値によって `Request-URI` の `user` 部分が設定されます。[拡張バッカスナウア記法を使用する必要があります](https://datatracker.ietf.org/doc/html/rfc2234)。必須の長さ: 1～36。値は `a-z, A-Z, 0-9, &, =, +, $, /, %, -, _, !, ~, *, `(`,`)、(`.`) を使用します。
`Request-URI` のホスト値は、ターゲットの Voice Connector の着信ルートから算出されます。次の例は、`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"
}
}
}
]
}
```
着信ルートと Voice Connector の詳細については、「[Editing Amazon Chime SDK Voice Connector settings](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/ja_jp/chime-sdk/latest/dg/images/call-bridge-ans-2.png)
次の図は、未応答通話の通話フローを示しています。
![\[CallAndBridge アクションを通じた未応答通話のフロー。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/SMA_Bridging_NotAns.png)
**その他の詳細**
`CallAndBridge` アクションについて、以下の点に注意してください。
+ `CallTimeoutSeconds` – このタイマーは、SIP 招待が B レッグに送信された時点で開始されます。希望するターゲット値を設定できますが、上流キャリアはこの値を無視できます。
+ `CallerIdNumber` – この電話番号は顧客に属するか、A レッグの From 番号である必要があります。
+ **切断動作とエッジケース** – 一方の通話レッグが切断しても、もう一方の通話レッグは自動的に通話を切断しません。`Hangup` イベントが AWS Lambda 関数に送信されると、残りのレッグは個別に切断する必要があります。通話レッグが保留状態のままの場合、通話は切断されるまで請求されます。例えば、次のシナリオでは予期しない料金が発生する可能性があります。
+ 宛先電話番号にブリッジしようとします。宛先が通話中であり、通話をボイスメールに直接送信します。Audio サービス側から見ると、ボイスメールへの送信は応答された通話です。A レッグは切断しますが、B レッグは引き続きボイスメールメッセージを待機します。B レッグが待機している間、請求されます。
+ ベストプラクティスとして、 AWS Lambda 関数、または通話のもう一方の側を使用して、各通話レッグを個別に切断します。
+ **請求** – `CallAndBridge` を使用すると、次の料金が請求されます。
+ PSTN に作成された各通話レッグ (A レッグ、B レッグなど) のアクティブな通話時間 (分)。
+ Audio サービスの使用時間 (分)。
GitHub での実際の例を参照してください。
+ [https://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)
+ [https://github.com/aws-samples/amazon-chime-sma-call-forwarding](https://github.com/aws-samples/amazon-chime-sma-call-forwarding)
+ [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# Hangup
`SipStatusCode` と共に `Hangup` 値を通話の任意のレッグに送信します。
Audio Service が通話レッグで `Hangup` アクションを実行すると、以下の処理が行われます。
+ 通話レッグが 1 つしかない通話の場合、SIP メディアアプリケーションは `HANGUP` イベントで AWS Lambda 関数を呼び出し、レスポンスを無視します。そして、通話が切断されます。
+ 別の通話レッグ (レッグ B) にブリッジされている通話レッグ (レッグ A) については、ブリッジされた通話レッグ (レッグ B) に `Hangup` アクションが関連付けられている場合、PSTN 音声サービスはブリッジされた通話レッグを切断し、レッグ B の `HANGUP` イベントで Lambda 関数を呼び出します。PSTN 音声サービスは、その Lambda 呼び出しから返されたアクションを実行します。
+ 別の通話レッグ (レッグ B) にブリッジされている通話レッグ (レッグ A) については、元の通話レッグ (レッグ A) に `Hangup` アクションが関連付けられている場合、PSTN 音声サービスは元の通話レッグを切断し、レッグ A の `HANGUP` イベントで Lambda 関数を呼び出します。PSTN 音声サービスは、その Lambda 呼び出しから返されたアクションを実行します。
+ `JoinMeeting` アクションを使用して会議に参加した通話レッグについては、会議レッグ (通常はレッグ B) に `Hangup` アクションが関連付けられている場合、発信者は会議から切断され、`Hangup` アクションの `ACTION_SUCCESSFUL` イベントを受信します。
一般的な `Hangup` アクションの例を次に示します。
```
{
"Type": "Hangup",
"Parameters": {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"SipResponseCode": "0"
}
}
```
**CallId**
*説明* – `CallId` AWS Lambda 関数呼び出し`CallDetails`の における参加者の説明
*使用できる値* – 有効な通話 ID
*必須* – いいえ
*デフォルト値* – なし
**ParticipantTag**
*説明* – `CallDetails` に接続されている参加者のうちの 1 人の `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-forwarding](https://github.com/aws-samples/amazon-chime-sma-call-forwarding)
+ [https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# JoinChimeMeeting
出席者参加トークンを指定して、Amazon Chime SDK ミーティングに参加します。これを行うには、 [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 を AWS SDK 呼び出してトークンを取得し、 アクションで渡します。次の例を参照してください。
**注記**
このアクションは、ブリッジ通話では実行できません。
```
{
"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` に接続されている参加者のうちの 1 人の `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 関数を呼び出します。
| エラー | メッセージ | 理由 |
| --- | --- | --- |
| `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-call](https://github.com/aws-samples/amazon-chime-sma-update-call)
# ModifyChimeMeetingAttendee (音声のミュートとミュート解除)
Amazon Chime SDK の会議 ID および出席者リストを提供することで、SIP メディアアプリケーションがテレフォニー出席者のステータスを変更できるようにします。
**注記**
このアクションは現在、テレフォニー出席者に対するミュート操作およびミュート解除操作をサポートしています。また、ユーザーは、`JoinChimeMeeting` アクションを使用して会議に参加する必要があります。このアクションは、`participantTag=“LEG-B”` に対して、または対応する `CallId` に対して実行できます。
このアクションが適用されるのは、SIP メディアアプリケーションから `"+`*13605550122*`"` に参加する callLeg、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**
説明 - 出席者リストに対して実行する操作
使用できる値 – Mute、Unmute
*必須* – はい
*デフォルト値* – なし
**MeetingId**
説明 - 出席者が属する会議の ID
使用できる値 – 有効な会議 ID ミュートまたはミュート解除するユーザーも会議に属している必要があります。
*必須* – はい
*デフォルト値* – なし
**CallId**
説明 - 出席者が属する会議の ID
*使用できる値* – 有効な通話 ID。
*必須* – いいえ
*デフォルト値* – なし
**ParticipantTag**
説明 - 出席者に割り当てられたタグ
使用できる値 - 有効なタグ
*必須* – いいえ
*デフォルト値* – なし
**AttendeeList**
説明 - ミュートまたはミュート解除する出席者 ID のリスト
使用できる値 - 有効な出席者 ID のリスト
*必須* – はい
デフォルト値 - なし、最大 100 件
このアクションを実行すると、Audio Service は常に、`ACTION_SUCCESSFUL` または `ACTION_FAILED` 呼び出しイベントタイプの AWS Lambda 関数を呼び出します。次のコード例は、一般的な `ACTION_SUCCESSFUL` 呼び出しイベントを示しています。
```
{
"SchemaVersion": "1.0",
"Sequence": INTEGER,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type" : "ModifyChimeMeetingAttendees",
"Parameters" : {
"Operation": "Mute",
"MeetingId": "meeting-id",
"CallId": "call-id",
"ParticipantTag": "LEG-B",
"AttendeeList": ["attendee-id-1", "attendee-id-2"]
}
}
"CallDetails": {
...
}
}
```
**エラー処理**
無効な命令パラメータまたは API 障害が発生した場合、SIP メディアアプリケーションは、失敗した命令または API に固有のエラーメッセージとともに AWS Lambda 関数を呼び出します。
| エラー | メッセージ | Reason |
| --- | --- | --- |
| `InvalidActionParameter` | `ModifyChimeMeetingAttendees Operation` パラメータの値が無効です。 | `Operation` 値は Mute または Unmute でなければなりません。 |
| | 会議 ID のパラメータ値が無効です。 | 会議 ID が空です。 |
| | 出席者リストのパラメータ値が無効です。 | 出席者 ID リストが空か、上限の 100 件を超えています。 |
| | 通話中のアクションが無効です。 | 通話がブリッジされていません。 |
| | 通話が Chime Meeting に接続されていません。 | 出席者が Chime Meeting に接続されていません。 |
| | One or more attendees are not part of this meeting. All attendees must be part of this 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-call](https://github.com/aws-samples/amazon-chime-sma-update-call)
# Pause
指定した時間だけ通話を一時停止します。
```
{
"Type": "Pause",
"Parameters": {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"DurationInMilliseconds": "3000"
}
}
```
**CallId**
*説明* – `CallId` AWS Lambda 関数呼び出し`CallDetails`の における参加者の説明
*使用できる値* – 有効な通話 ID
*必須* – いいえ
*デフォルト値* – なし
**ParticipantTag**
*説明* – `CallDetails` に接続されている参加者のうちの 1 人の `ParticipantTag`。
*使用できる値* – `LEG-A` または `LEG-B`
*必須* – いいえ
*デフォルト値* – 呼び出された `callLeg` の `ParticipantTag` (`CallId` を指定すると無視されます)
**DurationInMilliseconds**
説明 - 一時停止の時間 (ミリ秒単位)
使用できる値 – 整数 > 0
*必須* – はい
*デフォルト値* – なし
GitHub での実際の例を参照してください。
+ [https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
# PlayAudio
通話の任意のレッグでオーディオファイルを再生します。オーディオは何回でも繰り返すことができます。進行中のオーディオは、`PlaybackTerminators` で設定された DTMF ディジットを使用して終了できます。
現在、Amazon Chime SDK は Amazon Simple Storage Service (Amazon S3) バケットからのオーディオファイルの再生のみをサポートしています。S3 バケットは、SIP メディアアプリケーションと同じ AWS アカウントに属している必要があります。さらに、Amazon Chime SDK Voice Connector サービスプリンシパルに `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"
}
}
}
]
}
```
------
Audio Service は、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` で接続されている参加者のうちの 1 人の `ParticipantTag`。
*使用できる値* – `LEG-A` または `LEG-B`。
*必須* – `CallId` が存在する場合は、いいえ。
*デフォルト値* – 呼び出した `callLeg` の `ParticipantTag`。`CallId` を指定すると無視されます。
**PlaybackTerminator**
*説明* – ユーザーからの DTMF 入力を使用して、進行中のオーディオを終了します。
*使用できる値* –「0」、「1」、「2」、「3」、「4」、「5」、「6」、「7」、「8」、「9」、「\$1」、「\$1」の値の配列
*必須* – いいえ
*デフォルト値* – なし
**Repeat**
*説明* – 指定した回数だけオーディオを繰り返します。
*使用できる値* – 0 より大きい整数
*必須* – いいえ
*デフォルト値* – 1
**AudioSource.Type**
*説明* – オーディオファイルのソースタイプ。
*使用できる値* – S3。
*必須* – はい。
*デフォルト値* – なし。
**AudioSource.BucketName**
*説明* – S3 ソースタイプの場合、S3 バケットは SIP アプリケーションと同じ AWS アカウントに属している必要があります。バケットは、Amazon Chime SDK Voice Connector サービスプリンシパル (voiceconnector.chime.amazonaws.com) にアクセスできる必要があります。
*使用できる値* – Amazon Chime SDK が `s3:GetObject` アクションにアクセスできる有効な S3 バケット。
*必須* – はい。
*デフォルト値* – なし。
**AudioSource.key**
*説明* – S3 ソースタイプの場合は、`AudioSource.BucketName` 属性で指定された S3 バケットのファイル名。
*使用できる値* – 有効なオーディオファイル。
*必須* – はい。
*デフォルト値* – なし。
SIP メディアアプリケーションは、ソース URL からオーディオの再生を試みます。50 MB 以下の未圧縮の PCM .wav ファイルを使用できます。Amazon Chime SDK では、モノラル 8 kHz が推奨されます。
ダイヤルプランの最後の指示が `PlayAudio`で、ファイルが再生を終了するか、ユーザーがキーを押して再生を停止すると、アプリケーションは次の例に示すイベントで AWS Lambda 関数を呼び出します。
```
{
"SchemaVersion": "1.0",
"Sequence": INTEGER,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "PlayAudio",
"Parameters" : {
"CallId": "call-id-1",
"AudioSource": {
"Type": "S3",
"BucketName": "valid-S3-bucket-name",
"Key": "wave-file.wav",
}
}
}
```
有限小数によってオーディオが停止した後は、繰り返されません。
**エラー処理**
検証ファイルにエラーが含まれている場合、またはアクションの実行中にエラーが発生した場合、SIP メディアアプリケーションは適切なエラーコードを使用して AWS Lambda 関数を呼び出します。
| エラー | メッセージ | Reason |
| --- | --- | --- |
| `InvalidAudioSource` | オーディオソースパラメータが無効です。 | このエラーは、さまざまな理由で発生します。例えば、許可や URL の問題により、SIP メディアアプリケーションがファイルにアクセスできなくなります。または、形式、継続時間、サイズなどにより、オーディオファイルの検証に失敗することがあります。 |
| `SystemException` | アクションの実行中にシステムエラーが発生しました。 | アクションの実行中に、別のシステムエラーが発生しました。 |
| `InvalidActionParameter` | アクションの CallId または ParticipantTag パラメータが無効です。 | アクションに無効なパラメータが含まれています。 |
次のコード例は、一般的な呼び出し失敗を示しています。
```
{
"SchemaVersion": "1.0",
"Sequence": 2,
"InvocationEventType": "ACTION_FAILED",
"ActionData": {
"Type": "PlayAudio",
"Parameters" : {
"CallId": "call-id-1",
"AudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "audio-file.wav"
},
},
"ErrorType": "InvalidAudioSource",
"ErrorMessage": "Audio Source parameter value is invalid."
}
"CallDetails": {
...
}
}
```
GitHub での実際の例を参照してください。
+ [https://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)
+ [https://github.com/aws-samples/amazon-chime-sma-call-forwarding](https://github.com/aws-samples/amazon-chime-sma-call-forwarding)
+ [https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
+ [https://github.com/aws-samples/amazon-chime-sma-update-call](https://github.com/aws-samples/amazon-chime-sma-update-call)
# PlayAudioAndGetDigits
音声を再生して DTMF ディジットを収集します。ユーザーが正しい DTMF ディジット数を入力しなかったなどの失敗が発生した場合、このアクションは「失敗」音声を再生し、`Repeat` パラメータで定義された試行回数を SIP メディアアプリケーションが使い切るまでメイン音声を再生します。
S3 バケットから音声ファイルを再生する必要があります。S3 バケットは、SIP メディアアプリケーションと同じ AWS アカウントに属している必要があります。さらに、[Amazon Chime SDK Voice Connector サービスプリンシパル](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) (`voiceconnector.chime.amazonaws.com`) に `s3:GetObject` 許可を付与する必要があります。これを行うには、S3 コンソールまたは CLI を使用できます。
次のコード例は、一般的な S3 バケットポリシーを示しています。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SMARead",
"Effect": "Allow",
"Principal": {
"Service": "voiceconnector.chime.amazonaws.com"
},
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::bucket-name/*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
}
}
}
]
}
```
------
Audio Service は、Sip メディアアプリケーションの代わりに 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` に接続されている参加者のうちの 1 人の `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 Voice Connector サービスプリンシパル](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html)である `voiceconnector.chime.amazonaws.com` にアクセスできる必要があります。
使用できる値 – Amazon Chime SDK が `s3:GetObject` アクションにアクセスできる有効な S3 バケット。
*必須* – はい
*デフォルト値* – なし
**AudioSource.Key**
説明 - `AudioSource.BucketName` S3 バケット内の音声オブジェクトのキー名。
使用できる値 - 有効な音声ファイル
*必須* – はい
*デフォルト値* – なし
**FailureAudioSource.Type**
説明 - `FailureAudioSource.BucketName` S3 バケット内の音声オブジェクトのキー名。
*使用できる値* – S3
*必須* – はい
*デフォルト値* - なし
**FailureAudioSource.BucketName**
*説明* – S3 ソースタイプの場合、S3 バケットは SIP メディアアプリケーションと同じ AWS アカウントに属している必要があります。[Amazon Chime SDK Voice Connector サービスプリンシパル](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html)である `voiceconnector.chime.amazonaws.com` は S3 バケットにアクセスできる必要があります。
使用できる値 – Amazon Chime SDK が `s3:GetObject` アクションにアクセスできる有効な S3 バケット。
*必須* – はい
*デフォルト値* – なし
**FailureAudioSource.Key**
説明 - `FailureAudioSource.BucketName` S3 バケット内の音声オブジェクトのキー名。
使用できる値 - 有効な音声ファイル
*必須* – はい
*デフォルト値* – なし
**MinNumberOfDigits**
説明 - タイムアウトになるか「通話失敗」の音声が再生される前にキャプチャする最小ディジット数。
使用できる値 – >=0
*必須* – いいえ
デフォルト値 - 0
**MaxNumberOfDigits**
説明 - 終了ディジットなしで停止する前にキャプチャする最大ディジット数。
使用できる値 – >`MinNumberOfDigits`
*必須* – いいえ
デフォルト値 – 128
**TerminatorDigits**
説明 - ユーザーが `MaxNumberOfDigits` 未満の値を入力した場合に、入力を終了するのに使用されるディジット。
使用できる値 - 次のディジットのいずれか: 0123456789\$1\$1
*必須* – いいえ
デフォルト値 – \$1
**InBetweenDigitsDurationInMilliseconds**
説明 - `FailureAudio` を再生するまでのディジット入力間の待ち時間 (ミリ秒単位)。
*使用できる値* – 0 より大きい値
*必須* – いいえ
デフォルト値 - 指定しない場合、デフォルトは `RepeatDurationInMilliseconds` 値になります。
**Repeat**
説明 - ディジットの取得を試みた回数の合計。
*使用できる値* – 0 より大きい値
*必須* – いいえ
*デフォルト値* – 1
**RepeatDurationInMilliseconds**
説明 — `Repeat` の試行間の待ち時間 (ミリ秒単位)。
*使用できる値* – 0 より大きい値
*必須* – はい
*デフォルト値* - なし
SIP メディアアプリケーションは、 `ACTION_SUCCESSFUL`または 呼び出しイベントタイプで `PlayAudioAndGetDigits`アクションを実行した後、常に AWS Lambda 関数を`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 関数を呼び出します。次の表に、発生する可能性のあるエラーメッセージを示します。
| エラー | メッセージ | Reason |
| --- | --- | --- |
| `InvalidAudioSource` | Audio Source parameter value is invalid. | このエラーは、さまざまな理由で発生します。例えば、許可や S3 バケットの問題により、SIP メディアアプリケーションがファイルにアクセスできなくなります。または、継続時間、サイズ、サポートされていない形式により、音声ファイルの検証に失敗することがあります。 |
| `InvalidActionParameter` | アクションの `CallId` または `ParticipantTag` パラメータが無効です。 | `CallId`、`ParticipantTag`、またはそれ以外のパラメータが無効です。 |
| `SystemException` | アクションの実行中にシステムエラーが発生しました。 | アクションの実行中にシステムエラーが発生しました。 |
タイムアウトまたは再試行回数が多すぎるため、アクションが指定された桁数を収集できなかった場合、SIP メディアアプリケーションは`ACTION_FAILED`呼び出しイベントタイプを使用して AWS Lambda 関数を呼び出します。
```
{
"SchemaVersion": "1.0",
"Sequence": 4,
"InvocationEventType": "ACTION_FAILED",
"ActionData": {
"Type": "PlayAudioAndGetDigits",
"Parameters" : {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"InputDigitsRegex": "^\d{2}#$",
"AudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "audio-file-1.wav"
},
"FailureAudioSource": {
"Type": "S3",
"BucketName": "bucket-name",
"Key": "audio-file-failure.wav"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
},
"ErrorType": "InvalidAudioSource",
"ErrorMessage": "Audio Source parameter value is invalid."
}
"CallDetails": {
...
}
}
```
GitHub での実際の例を参照してください。
+ [https://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)
+ [https://github.com/aws-samples/amazon-chime-sma-update-call](https://github.com/aws-samples/amazon-chime-sma-update-call)
# ReceiveDigits
ユーザーがこのアクションで指定された正規表現パターンに一致する数字を入力すると、SIP メディアアプリケーションは AWS Lambda 関数を呼び出します。
```
{
"Type": "ReceiveDigits",
"Parameters": {
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
"InputDigitsRegex": "^\d{2}#$",
"InBetweenDigitsDurationInMilliseconds": 1000,
"FlushDigitsDurationInMilliseconds": 10000
}
}
```
**CallId**
*説明* – `CallId` AWS Lambda 関数呼び出し`CallDetails`の における参加者の説明
*使用できる値* – 有効な通話 ID
*必須* – いいえ
*デフォルト値* – なし
**ParticipantTag**
*説明* – `CallDetails` に接続されている参加者のうちの 1 人の `ParticipantTag`。
*使用できる値* – `LEG-A` または `LEG-B`
*必須* – いいえ
*デフォルト値* – 呼び出された `callLeg` の `ParticipantTag` (`CallId` を指定すると無視されます)
**InputDigitsRegex**
説明 - 正規表現パターン
使用できる値 - 有効な正規表現パターン
*必須* – はい
*デフォルト値* – なし
**InBetweenDigitsDurationInMilliseconds**
説明 - 入力が正規表現パターンと一致するかどうかを確認する前のディジットの間隔
使用できる値 - 所要時間 (ミリ秒単位)
*必須* – はい
*デフォルト値* – なし
**FlushDigitsDurationInMilliseconds**
*説明* – 受信した DTMF ディジットがフラッシュされて AWS Lambda 関数に送信される間隔。間隔が終了した後に SIP メディアアプリケーションが新しいディジットを受信すると、タイマーが再び開始されます。
使用できる値 – `InBetweenDigitsDurationInMilliseconds`
*必須* – はい
*デフォルト値* – なし
SIP メディアアプリケーションは、新しい `ReceiveDigits` アクションを受信するまで、通話中の DTMF ディジットを破棄します。`FlushDigitsDurationInMilliseconds` 間隔は、SIP メディアアプリケーションが最初の DTMF ディジットを受信したときから始まります。間隔が期限切れになる前にユーザーが正しい桁を入力すると、SIP メディアアプリケーションは で説明されている AWS Lambda 関数を呼び出します[Amazon Chime SDK PSTN オーディオサービスでの発信者の入力の受信](case-4.md)。
ユーザー入力が正規表現パターンと一致しない場合、SIP メディアアプリケーションは、アプリケーションが繰り返し回数を使い切るか、ユーザーが有効なディジットを入力するまで、「失敗」音声ファイルメッセージを繰り返します。
GitHub での実際の例を参照してください。
+ [https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
+ [https://github.com/aws-samples/amazon-chime-sma-update-call](https://github.com/aws-samples/amazon-chime-sma-update-call)
# RecordAudio
SIP メディアアプリケーションが、特定の通話 ID からメディアを録音できるよう許可します。例えば、音声メールアプリケーションや、会議参加者のお知らせなどです。アプリケーションは、設定した時間に達するまで、またはユーザーがいずれかの `RecordingTerminators` を押すか、アプリケーションが無音を検出するまで録音を実行します。このような場合、アクションは、結果のメディアファイルを指定された S3 バケットに配置するようアプリケーションに指示します。S3 バケットは、SIP メディアアプリケーションと同じ AWS アカウントに属している必要があります。さらに、アクションは、Amazon Chime SDK Voice Connector サービスプリンシパル ([Amazon Chime SDK Voice Connector サービスプリンシパル](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html)) である `voiceconnector.chime.amazonaws.com` に、`s3:PutObject` および `s3:PutObjectAcl` の許可を付与する必要があります。
**注記**
この機能を使用して作成された録音は、電子通信記録に関する法律または規制の対象となる場合があります。録音に関するすべての適用法を遵守することは、お客様とそのエンドユーザーの責任です。これには、録音セッションまたは通信のすべての参加者にセッションまたは通信が録音されていることを適切に通知し、同意を得ることを含みます。
次の例では、Amazon Chime SDK Voice Connector サービスプリンシパルに `s3:PutObject` および `s3:PutObjectAcl` 許可を付与します。
------
#### [ 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` に接続されている参加者のうちの 1 人の `ParticipantTag`。
*使用できる値* – `LEG-A` または `LEG-B`
*必須* – いいえ
*デフォルト値* – 呼び出された `callLeg` の `ParticipantTag` (`CallId` を指定すると無視されます)
**RecordingDestination.Type**
*説明* – 送信先のタイプ。S3 のみ。
*使用できる値* – S3
*必須* – はい
*デフォルト値* – なし
**RecordingDestination.BucketName**
*説明* – 有効な S3 バケット名。バケットは、[Amazon Chime SDK Voice Connector サービスプリンシパル](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html)である `voiceconnector.chime.amazonaws.com` にアクセスできる必要があります。
*使用できる値* – Amazon Chime SDK が `s3:PutObject` および `s3:PutObjectAcl` アクションにアクセスできる有効な S3 バケット。
*必須* – はい
*デフォルト値* – なし
****RecordingDestination.Prefix****
*説明* – 録音ファイルの S3 プレフィックス
*使用できる値* – 979 文字までのセーフ文字を含む有効なプレフィックス名。セーフ文字の詳細については、Amazon Simple Storage Service ユーザーガイドの「[セーフ文字](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-guidelines-safe-characters)」を参照してください。
*必須* – いいえ
*デフォルト* – なし。指定しない場合、録音は S3 バケットのルートに保存されます。
**DurationInSeconds**
*説明* – 録音の長さ (秒単位)。
*使用できる値* – 0 より大きい値
*必須* – いいえ
*デフォルト値* – なし
****SilenceDurationInSeconds****
*説明* – 録音が停止するまでの無音の継続時間 (秒単位)。指定しない場合、無音検出は無効になります。
*使用できる値* – [1;1000]
*必須* – いいえ
*デフォルト値* – 200
****SilenceThreshold****
*説明* – 「無音」と見なされるノイズのレベル。`SilenceDurationInSeconds` を指定しない場合、このパラメータは無視されます。
**基準値 (ノイズを無音として扱うためのノイズレベルとしきい値):**
+ 1 – 30 dB 以下 (静かな部屋など)
+ 100 – 40～50 dB (ささやきや静かなオフィスなど)
+ 200 – 60 dB (混雑したオフィスなど)
+ 1000 – 75 dB (大声や音楽など)
*使用できる値* – [1;1000]
*必須* – いいえ
*デフォルト値* – 200
**RecordingTerminators**
*説明* – 使用可能なすべての録音ターミネータを一覧表示します。
*使用できる値* – [123456789\$10\$1] の 1 桁の数字と記号の配列
*必須* – はい
*デフォルト値* – なし
## ACTION\$1SUCCESS イベントの処理
録音が終了すると、Amazon Chime SDK SIP メディアアプリケーションは AWS Lambda 関数を呼び出し、呼び出し結果とともに ACTION\$1SUCCESSFUL イベントを渡します。
```
{
"SchemaVersion": "1.0",
"Sequence": INTEGER,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type" : "RecordAudio",
"Parameters": {
...
},
"RecordingDestination": {
"Type": "S3",
"BucketName": "valid-bucket-name",
"Key": "valid-S3-key"
},
"RecordingTerminatorUsed":"#"
},
"CallDetails": {
...
}
}
```
`ACTION_SUCCESSFUL` イベントには、`ActionData` が含まれます (以下のフィールドがあります)。
**Type**
*説明* – アクションのタイプ (`RecordAudio`)。
**Parameters**
*説明* – アクションのパラメータ。
**RecordingDestination.Type**
*説明* – 送信先のタイプ。S3 のみ。
**RecordingDestination.BucketName**
*説明* – 録音ファイルが含まれる S3 バケット。
**RecordingDestination.Key**
*説明* – 録音ファイルの S3 キー。
**RecordingTerminatorUsed**
*説明* – 録音を停止するために使用されるターミネーター (`RecordingTerminators` パラメータに渡されるいずれかのターミネーター)。最大持続時間 (`DurationInSeconds`) に達したか、無音 (`SilenceDurationInSeconds`) により録音が停止した場合、このキーと値のペアは出力に含まれません。
**エラー処理**
検証エラーの場合、SIP メディアアプリケーションは適切なエラーメッセージを使用して AWS Lambda 関数を呼び出します。次の表に、発生する可能性のあるエラーメッセージを示します。
| エラー | メッセージ | Reason |
| --- | --- | --- |
| `InvalidActionParameter` | アクションの `CallId` または`ParticipantTag` パラメータが無効です。 `DurationInSeconds` パラメータの値が無効です。 `SilenceDurationInSeconds` パラメータの値が無効です。 `SilenceThreshold` パラメータの値が無効です。 `RecordingDestination` パラメータの値が無効です。 S3 バケットへの録音のアップロード中にエラーが発生しました。 | パラメータが無効です。 |
| `SystemException` | アクションの実行中にシステムエラーが発生しました。 | アクションの実行中に、別のタイプのシステムエラーが発生しました。 |
## ACTION\$1FAILED イベントの処理
アクションが通話レッグにメディアを記録できない場合、SIP メディアアプリケーションは `ACTION_FAILED` イベントタイプで AWS Lambda 関数を呼び出します。次の例を参照してください。
```
{
"SchemaVersion": "1.0",
"Sequence": 5,
"InvocationEventType": "ACTION_FAILED",
"ActionData": {
"Type" : "RecordAudio",
"Parameters": {
...
},
"ErrorType": "InvalidActionParameter",
"ErrorMessage": "RecordingDestination parameter value is invalid."
},
"CallDetails": {
...
}
}
```
GitHub の実際の例 ([https://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)) を参照してください。
# SendDigits
任意の通話レッグで、最大 50 のデュアルトーンマルチ周波数 (DTMF) ディジットを送信できます。シグナルには以下を含めることができます。
+ 0 から 9 までの数字
+ 特殊文字: 星 (\$1) とポンド (\$1)
+ ネットワーク制御シグナル A、B、C、D
+ カンマ文字 (,)。このシグナルにより、前のシグナルと次のシグナルの間に 0.5 秒の遅延が追加されます。
**Topics**
+ [SendDigits アクションの使用](#send-digits-action)
+ [ACTION\$1SUCCESSFUL イベントの処理](#send-digit-success)
+ [ACTION\$1FAILED イベントの処理](#send-digit-fail)
+ [通話フロー](#send-digits-call-flow)
## SendDigits アクションの使用
次の例は、一般的な `SendDigits` アクションを示しています。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "SendDigits",
"Parameters": {
"CallId": "call-id-1", // required
"Digits": ",,*1234,56,7890ABCD#", // required
"ToneDurationInMilliseconds": 100 // optional
}
}
]
}
```
**CallId**
説明 – AWS Lambda 関数呼び出しの `CallDetails` における、参加者の `CallId`
*使用できる値* – 有効な通話 ID
*必須* – はい
*デフォルト値* – なし
**Digits**
説明 - `CallId` に対応する通話レッグで送信されるディジット
使用できる値 – 0～9、\$1、\$1、A、B、C、D、カンマ (,)
*必須* – はい
*デフォルト値* – なし
**ToneDurationInMilliseconds**
説明 - 各ディジットの送信で許容される時間 (ミリ秒単位)
使用できる値 - 50～24000 の任意の整数
*必須* – いいえ
デフォルト値 – 250
## ACTION\$1SUCCESSFUL イベントの処理
`SendDigits` アクションの一般的な `ACTION_SUCCESSFUL` イベントの例を次に示します。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "SendDigits",
"Parameters": {
"Digits": "1,2A#",
"ToneDurationInMilliseconds": 100,
"CallId": "call-id-1"
},
"CallDetails": {
...
}
}
}
```
## ACTION\$1FAILED イベントの処理
`SendDigits` アクションの一般的な `ACTION_FAILED` イベントの例を次に示します。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_FAILED",
"ActionData": {
"Type": "SendDigits",
"Parameters": {
"Digits": "1,2A#",
"ToneDurationInMilliseconds": 20000000,
"CallId": "call-id-1"
},
"ErrorType": "InvalidActionParameter",
"ErrorMessage": "ToneDuration parameter value is invalid."
},
"CallDetails": {
...
}
}
}
```
## 通話フロー
次の図は、発信者から受信者にディジットを送信するプログラムフローを示しています。
![\[SendDigits アクションのプログラムフローを示す図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/send-digits-1.png)
# Speak
テキストを入力すれば、どの通話レッグでも音声を再生できます。プレーンテキストまたは音声合成マークアップ言語 (SSML) を使用できます。SSML では、一時停止を追加したり、特定の単語を強調したり、話し方を変更したりすることで、Amazon Chime SDK が音声を生成する方法をより細かく制御できます。
Amazon Chime SDK は、Amazon Polly サービスを使用してテキストを音声に変換します。Amazon Polly では、音声品質を向上させるために、標準エンジンとニューラルエンジンのどちらかを選択できます。Amazon Polly は、20 以上の言語と 60 の音声をサポートしており、アプリケーションのユーザーエクスペリエンスをカスタマイズすることができます。Amazon Chime SDK では音声機能は無料で提供されますが、Amazon Polly の使用には料金がかかります。価格情報については、Amazon Polly の[料金ページ](https://aws.amazon.com/polly/pricing/)または請求ダッシュボードを参照してください。
**重要**
Amazon Polly の使用には、AWS Machine Learning および人工知能サービスに固有の条件を含む、[AWS のサービス条件](https://aws.amazon.com/service-terms/)が適用されます。
**Topics**
+ [Speak アクションの使用](#speak-action)
+ [ACTION\$1SUCCESSFUL イベントの処理](#speak-action-success)
+ [ACTION\$1FAILED イベントの処理](#speak-action-fail)
+ [プログラムフロー](#speak-flow)
## Speak アクションの使用
次の例は、`Speak` アクションの一般的な使用方法を示しています。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "Speak",
"Parameters": {
"Text": "Hello, World!", // required
"CallId": "call-id-1", // required
"Engine": "neural", // optional. Defaults to standard
"LanguageCode": "en-US", // optional
"TextType": "text", // optional
"VoiceId": "Joanna" // optional. Defaults to Joanna
}
}
]
}
```
**CallId**
説明 – Lambda 関数呼び出しの `CallDetails` における、参加者の `CallId`
*使用できる値* – 有効な通話 ID
*必須* – はい
*デフォルト値* – なし
**Text**
説明 - 音声に合成する入力テキストを指定します。`ssml` を `TextType` として指定した場合は、入力テキストの SSML 形式に従います。
使用できる値 - 文字列
*必須* – はい
*デフォルト値* – なし
**Engine**
説明 - 音声合成用のテキストを処理するときに使用するエンジン (標準またはニューラル) を指定します。
使用できる値 – standard \$1 neural
*必須* – いいえ
デフォルト値 - standard
**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 の音声 ID](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-VoiceId)
*必須* – いいえ
デフォルト値 - Joanna
## ACTION\$1SUCCESSFUL イベントの処理
次の例は、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 イベントの処理
次の例は、前の例で使用された同じイベントの一般的な `ACTION_FAILED` イベントを示しています。
```
{
"SchemaVersion": "1.0",
"Sequence":2,
"InvocationEventType": "ACTION_FAILED",
"ActionData":{
"Type": "Speak",
"Parameters": {
"CallId": "call-id-1",
"Engine": "neural",
"LanguageCode": "en-US",
"Text": "Hello World",
"TextType": "text",
"VoiceId": "Joanna"
},
"ErrorType": "SystemException",
"ErrorMessage": "System error while running action"
},
"CallDetails":{
...
}
}
```
**エラー処理**
以下の表では、`Speak` アクションによってスローされるエラーメッセージを列挙し、説明しています。
| エラー | メッセージ | 理由 |
| --- | --- | --- |
| `AccessDenied` | `AWSServiceRoleForAmazonChimeVoiceConnector` サービスにリンクされたロールが正しく設定されていません。 | Amazon Polly へのリクエストに使用された、サービスにリンクされたロールが、存在しないかアクセス許可がありません。これを解決するには、「[Amazon Chime SDK 音声コネクタサービスにリンクされたロールの使用](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/ja_jp/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 メディアアプリケーションは次のアクションセットを返します。アクションが失敗した場合、SIP メディアアプリケーションは Lambda 関数に `ACTION_FAILED` イベントを送信します。Lambda 関数は `Hangup` アクションセットで応答します。アプリケーションは発信者をハングアップし、Lambda 関数に `HANGUP` イベントを返します。Lambda 関数は、それ以上アクションを実行しません。
次の図は、受信者の `Speak` アクションを可能にするプログラムフローを示しています。
![\[受信者の Speak アクションを可能にするプログラムフローを示す図。これは、どのブリッジ通話でも実行できます。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/Speak2.png)
**図の説明**
発信者が、SIP メディアアプリケーションに登録されている番号を入力すると、アプリケーションは、前の図で説明したように応答します。Lambda 関数は、`NEW_INBOUND_CALL` イベントを受信すると、SIP アプリケーションに [CallAndBridge](call-and-bridge.md) アクションを返します。アプリケーションは、SIP `INVITE` メソッドを使用して、受信者に `Trying (100)` 応答と `Ringing (180)` 応答を送信します。
受信者が応答すると、SIP メディアアプリケーションは `200 (OK)` 応答を受信し、その同じ応答を発信者に送信します。これによりメディアが確立され、SIP アプリケーションは [CallAndBridge](call-and-bridge.md) アクションの `ACTION_SUCCESSFUL` イベントを Lambda 関数に送信します。この関数は、Speak アクションとデータを SIP アプリケーションに返します。SIP アプリケーションはこれを変換します。
# SpeakAndGetDigits
テキストを提供して音声を再生し、ユーザーからデュアルトーンマルチ周波数 (DTMF) ディジットを収集します。テキストには、プレーンテキスト、または音声合成マークアップ言語 (SSML) で強化されたテキストを使用できます。サポートされている SSML 機能の中でも特に一時停止の追加、特定の単語の強調、話し方の変更によって、Amazon Chime SDK が音声を生成する方法をより細かく制御できます。ユーザーが正しい DTMF ディジット数を入力しなかったなどの失敗が発生した場合、このアクションは「失敗」音声を再生し、`Repeat` パラメータで定義された試行回数を SIP メディアアプリケーションが使い切るまでメイン音声を再生します。
Amazon Chime SDK は、テキストを肉声に近い音声に変換するクラウドサービスである Amazon Polly を使用しています。Amazon Polly は、標準エンジンと、音声品質が改善されているニューラルエンジンを提供しています。サポートする言語は 20 を超え、60 の音声に対応しています。Amazon Polly では音声機能は無料で提供されますが、Amazon Polly の使用には料金がかかります。価格情報については、Amazon Polly の[料金ページ](https://aws.amazon.com/polly/pricing/)または請求ダッシュボードを参照してください。
**重要**
Amazon Polly の使用には、 AWS Machine Learning および人工知能サービスに固有の[AWS 条件](https://aws.amazon.com/service-terms/)を含むサービス条件が適用されます。
**Topics**
+ [SpeakAndGetDigits アクションの使用](#speak-digits-action)
+ [ACTION\$1SUCCESSFUL イベントの処理](#speak-digits-success)
+ [ACTION\$1FAILED イベントの処理](#speak-digits-fail)
+ [Amazon Chime SDK 音声コネクタサービスにリンクされたロールの使用](#speak-digits-policy)
## SpeakAndGetDigits アクションの使用
次の例は、`SpeakAndGetDigits` アクションの一般的な使用方法を示しています。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "SpeakAndGetDigits",
"Parameters": {
"CallId": "call-id-1", // required
"InputDigitsRegex": "^\d{2}#$", // optional
"SpeechParameters": {
"Text": "Hello World", // required
"Engine": "neural", // optional. Defaults to standard
"LanguageCode": "en-US", // optional
"TextType": "text", // optional
"VoiceId": "Joanna" // optional. Defaults to Joanna
},
"FailureSpeechParameters": {
"Text": "Hello World", // required
"Engine": "neural", // optional. Defaults to the Engine value in SpeechParameters
"LanguageCode": "en-US", // optional. Defaults to the LanguageCode value in SpeechParameters
"TextType": "text", // optional. Defaults to the TextType value in SpeechParameters
"VoiceId": "Joanna" // optional. Defaults to the VoiceId value in SpeechParameters
},
"MinNumberOfDigits": 3, // optional
"MaxNumberOfDigits": 5, // optional
"TerminatorDigits": ["#"], // optional
"InBetweenDigitsDurationInMilliseconds": 5000, // optional
"Repeat": 3, // optional
"RepeatDurationInMilliseconds": 10000 // required
}
}
]
}
```
**CallId**
説明 – Lambda 関数呼び出しの CallDetails における、参加者の `CallId`。
使用できる値 – 有効な `callID`
*必須* – はい
デフォルト値 - なし
**InputDigitsRegex**
説明 - ユーザーが正しいディジットと文字を入力できるようにするための正規表現パターン。
使用できる値 - 有効な正規表現パターン
*必須* – いいえ
*デフォルト値* – なし
**SpeechParameters.Engine**
説明 - 音声合成用のテキストを処理するときに使用するエンジン (標準またはニューラル) を指定します。
使用できる値 – `standard` \$1 `neural`
*必須* – いいえ
デフォルト値 - standard
**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 の音声 ID](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 の音声 ID](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-VoiceId)
*必須* – はい
デフォルト値 - `SpeechParameters.VoiceId` 値
**MinNumberOfDigits**
説明 - タイムアウトになるか「通話失敗」メッセージが再生される前にキャプチャする最小ディジット数。
使用できる値 - 0 以上
*必須* – いいえ
デフォルト値 - 0
**MaxNumberOfDigits**
説明 - 終了ディジットなしで停止する前にキャプチャする最大ディジット数。
使用できる値 - `MinNumberOfDigits` より大きい値
*必須* – いいえ
デフォルト値 – 128
**TerminatorDigits**
説明 - ユーザーが MaxNumberOfDigits 未満の値を入力した場合に、入力を終了するのに使用されるディジット
使用できる値 - 0 1 2 3 4 5 6 7 8 9 \$1 \$1 のいずれか
*必須* – いいえ
デフォルト値 – \$1
**InBetweenDigitsDurationInMilliseconds**
説明 - 失敗音声を再生するまでのディジット入力間の待ち時間 (ミリ秒単位)。
使用できる値 - 0 より大きい値
*必須* – いいえ
デフォルト値 - 指定しない場合、デフォルトは `RepeatDurationInMilliseconds` 値になります。
**Repeat**
説明 - ディジットの取得を試みた回数の合計。このパラメータを省略すると、デフォルトでディジットの収集が 1 回試行されます。
使用できる値 - 0 より大きい値
*必須* – いいえ
*デフォルト値* – 1
**RepeatDurationInMilliseconds**
説明 - ディジットを取得する各試行のタイムアウト (ミリ秒単位)。
使用できる値 - 0 より大きい値
*必須* – はい
*デフォルト値* – なし
## ACTION\$1SUCCESSFUL イベントの処理
次の例は、一般的な `ACTION_SUCCESSFUL` イベントを示しています。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "SpeakAndGetDigits",
"Parameters": {
"CallId": "call-id-1",
"InputDigitsRegex": "^\d{2}#$",
"SpeechParameters": {
"Engine": "neural",
"LanguageCode": "en-US",
"Text": "Hello World",
"TextType": "text",
"VoiceId": "Joanna"
},
"FailureSpeechParameters": {
"Engine": "neural",
"LanguageCode": "en-US",
"Text": "Hello World",
"TextType": "text",
"VoiceId": "Joanna"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
},
"ReceivedDigits": "1234"
},
"CallDetails":{
...
}
}
```
## ACTION\$1FAILED イベントの処理
次の例は、一般的な `ACTION_FAILED` イベントを示しています。
```
{
"SchemaVersion": "1.0",
"Sequence":2,
"InvocationEventType": "ACTION_FAILED",
"ActionData":{
"Type": "SpeakAndGetDigits",
"Parameters": {
"CallId": "call-id-1",
"InputDigitsRegex": "^\d{2}#$",
"SpeechParameters": {
"Engine": "neural",
"LanguageCode": "en-US",
"Text": "Hello World",
"TextType": "text",
"VoiceId": "Joanna"
},
"FailureSpeechParameters": {
"Engine": "neural",
"LanguageCode": "en-US",
"Text": "Hello World",
"TextType": "text",
"VoiceId": "Joanna"
},
"MinNumberOfDigits": 3,
"MaxNumberOfDigits": 5,
"TerminatorDigits": ["#"],
"InBetweenDigitsDurationInMilliseconds": 5000,
"Repeat": 3,
"RepeatDurationInMilliseconds": 10000
},
"ErrorType": "SystemException",
"ErrorMessage": "System error while running action"
},
"CallDetails":{
...
}
}
```
**エラー処理**
以下の表では、`Speak` アクションによってスローされるエラーメッセージを列挙し、説明しています。
| エラー | メッセージ | 理由 |
| --- | --- | --- |
| `AccessDenied` | `AWSServiceRoleForAmazonChimeVoiceConnector` ロールが正しく設定されていません。 | Amazon Polly へのリクエストに使用されたロールが存在しないか、アクセス許可がありません。これを解決するには、「[Amazon Chime SDK 音声コネクタサービスにリンクされたロールの使用](#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 SDK コンソール、、または AWS API で SIP メディアアプリケーションを作成 AWS Command Line Interfaceまたは更新すると、Amazon Chime SDK によってサービスにリンクされたロールが作成されます。
詳細については、「Amazon Chime SDK 管理者ガイド」の「[Using the Amazon Chime service-linked role](https://docs.aws.amazon.com/chime/latest/ag/using-service-linked-roles-stream.html)」を参照してください。
# StartBotConversation
`StartBotConversation` アクションにより、エンドユーザーと Amazon Lex v2 ボット間の音声会話が確立されます。ユーザーは必要な情報をボットに提供します。次に、ボットは情報を公衆交換電話網 (PSTN) Audio Lambda 関数に返し、関数は要求されたタスクを実行します。
例えば、ボットは会話の開始時にオプションのウェルカムメッセージを再生して、PSTN オーディオ Lambda 関数が実行できるタスクを簡単に説明できます。ボットが必要な情報を収集するまで、ユーザーとボットの間で会話が繰り返されます。会話が終了すると、Amazon Chime SDK はボットによって収集された情報を含むアクション成功イベントで PSTN オーディオ Lambda 関数を呼び出します。PSTN オーディオ Lambda 関数は情報を処理し、要求されたタスクを実行します。
Audio サービスは、ユーザーと本物そっくりの会話形式を提供します。例えば、音声プロンプトが終了する前に、ユーザーがボットに割り込み、質問に答えることができます。さらに、ユーザーは音声と 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 Machine Learningおよび人工知能サービスに固有の[AWS 条件を含むサービス](https://aws.amazon.com/service-terms/)条件 が適用されます。
**Topics**
+ [StartBotConversation の構文](#startbot-syntax)
+ [StartBotConversation アクションの使用](#using-startbot)
+ [ACTION\$1SUCCESSFUL イベントの処理](#bot-action-success)
+ [ACTION\$1FAILED イベントの処理](#bot-action-fail)
+ [ボットを使用するアクセス許可の付与](#bot-permissions)
+ [音声と DTMF のタイムアウトの設定](#bot-timeouts)
+ [会話中に DTMF 入力の使用](#bot-dtmf)
+ [請求とサービスクォータ](#bot-billing)
## StartBotConversation の構文
一般的な `StartBotConversation` 構文の例を次に示します。
```
{
"SchemaVersion": "1.0",
"Actions":[
{
"Type": "StartBotConversation",
"Parameters": {
"CallId": "string",
"ParticipantTag": "string",
"BotAliasArn": "string",
"LocaleId": "string",
"Configuration": {
"SessionState": {
"SessionAttributes": {
"string": "string"
},
"DialogAction" : {
"Type": "string"
}
},
"WelcomeMessages": [
{
"Content": "string",
"ContentType": "string"
}
]
}
}
}
]
}
```
**CallId**
*説明* – AWS Lambda 関数呼び出し`CallID`の `CallDetails` の参加者の 。`StartBotConversation` アクションはこの ID をボットの `SessionId` として使用します。通話中に行われるすべてのボットの会話は、同じ会話セッションを共有します。[Amazon Lex PutSession](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_PutSession.html) API を使用して、ユーザーとボットの間のセッション状態を変更できます。詳細については、「*Amazon Lex Developer Guide*」の「[Managing sessions with the Amazon Lex v2 API](https://docs.aws.amazon.com/lexv2/latest/dg/using-sessions.html)」を参照してください。
*使用できる値* – 有効な通話 ID。
*必須* – `ParticipantTag` が存在する場合は、いいえ。
*デフォルト値* – なし。
**ParticipantTag**
説明 – `CallDetails` で接続されている参加者のうちの 1 人の `ParticipantTag`。
使用できる値 - `LEG-A`。
*必須* – `CallId` が存在する場合は、いいえ。
*デフォルト値* – 呼び出した `callLeg` の `ParticipantTag`。`CallDetails` を指定すると無視されます。
**BotAliasArn**
説明 - Lex ボットのボットエイリアス ARN。ボットは PSTN オーディオアプリケーションと同じ AWS リージョンに作成する必要があります。有効な Amazon Lex ボットエイリアスの形式は `arn:aws:lex:region:awsAccountId:bot-alias/botId/botAliasId` です。ここで *`region`* はボットが存在する AWS リージョンです。`awsAccountId` は Amazon Lex ボットが作成された AWS アカウント ID です。`botId` 値は、その作成時にボットに割り当てた識別子です。ボット ID は、Amazon Lex コンソールの **[ボットの詳細]** ページにあります。`botAliasId` は、その作成時にボットエイリアスに割り当てた識別子です。ボットエイリアス ID は、Amazon Lex コンソールの **[エイリアス]** ページにあります。
使用できる値 - 有効なボット ARN。
必須 – はい。
*デフォルト値* – なし。
**LocaleId**
説明 - ボットに使用したロケールの識別子。ロケールおよび言語コードのリストについては、「[Languages and locales supported by Amazon Lex](https://docs.aws.amazon.com/lexv2/latest/dg/how-languages.html)」を参照してください。
使用できる値 - [Amazon Lex でサポートされている言語とロケール。](https://docs.aws.amazon.com/lexv2/latest/dg/how-languages.html)
必須 – いいえ。
デフォルト値 – `en_US`。
**Configuration**
説明 - セッション状態とウェルカムメッセージを含む会話設定。`Configuration` オブジェクトの JSON 文字列表現の合計サイズは 10 KB に制限されています。
使用できる値 - `Configuration` オブジェクト。
必須 – いいえ。
*デフォルト値* – なし。
**Configuration.SessionState**
説明 - Amazon Lex v2 とのユーザーのセッションの状態。
使用できる値 - `SessionState` オブジェクト。
必須 – いいえ。
*デフォルト値* – なし。
**Configuration.SessionState.SessionAttributes**
説明 - セッション固有のコンテキスト情報を表すキー/値のペアのマップ。このマップには、Amazon Lex v2 とクライアントアプリケーションの間で渡されるアプリケーション情報が含まれます。
使用できる値 - 文字列間のマッピング。
必須 – いいえ。
*デフォルト値* – なし。
**Configuration.SessionState.DialogAction.Type**
説明 - ユーザーとのインタラクションにおいて、ボットが取る次のアクション。使用できる値:
+ *Delegate* 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 Developer Guide*」の「[Managing sessions with the Amazon Lex V2 API](https://docs.aws.amazon.com/lexv2/latest/dg/using-sessions.html)」を参照してください。
**SessionState**
ユーザーの Amazon Lex v2 セッションの状態。
**SessionState.SessionAttributes**
セッション固有のコンテキスト情報を表すキー/値のペアのマップ。マップには、ボットにアタッチされた Lambda 関数と PSTN オーディオ Lambda 関数の間で渡されるボット会話情報が含まれています。
**Interpretations**
Amazon Lex によって導き出された、顧客の発話を満たす可能性のあるインテントのリスト。`NluConfidence` スコアの最も高いインテントが `SessionState` のインテントになります。
**Interpretations.NluConfidence.Score**
インテントがユーザーのインテントを満たしているという Amazon Lex v2 の信頼度を示すスコア。0.00～1.00 までの範囲になります。スコアが高いほど、信頼度が高くなります。
**Intent**
ユーザーが実行したいアクション。
**Intent.Name**
インテントの名前。
**Intent.Slots**
インテントのすべてのスロットのマップ。スロットの名前は、スロットの値にマップされます。スロットがいっぱいになっていない場合は、値は null です。
**Intent.Slots.Value**
スロットの値。
**Intent.Slots.Values**
スロットにユーザーが指定した 1 つ以上の値のリスト。
**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**
説明 - インテントの確認を示します。使用できる値:
+ *Confirmed* - インテントが履行されます。
+ *Denied* - ユーザーは確認プロンプトで「いいえ」と答えました。
+ *None* - ユーザーは確認を求められなかったか、または確認を求められたが肯定も否定もしませんでした。
## 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` | 1 つ以上のアクションパラメータが無効です。エラーメッセージには、無効なパラメータが示されます。 |
| `SystemException` | アクションの実行中に、システムエラーが発生しました。 |
| `ResourceNotFound` | 指定したボットは見つかりませんでした。 |
| `ResourceAccessDenied` | ボットへのアクセスは拒否されます。 |
| `ActionExecutionThrottled` | ボット会話サービスの制限を超えています。エラーメッセージには、特定のサービスの制限を超えていることが示されます。 |
## ボットを使用するアクセス許可の付与
次の例では、Amazon Chime SDK に Amazon Lex [https://docs.aws.amazon.com/lexv2/latest/dg/API_runtime_StartConversation.html](https://docs.aws.amazon.com/lexv2/latest/dg/API_runtime_StartConversation.html) API を呼び出すアクセス許可を付与しています。ユーザーにボットを使用する Audio サービスのアクセス許可を明示的に付与する必要があります。条件ブロックはサービスプリンシパルに必要です。条件ブロックはグローバルコンテキストキー `AWS:SourceAccount` と `AWS:SourceArn` を使用する必要があります。`AWS:SourceAccount` は AWS アカウント ID です。`AWS:SourceArn` は、Lex ボットを呼び出す PSTN オーディオアプリケーションのリソース ARN です。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowChimePstnAudioUseBot",
"Effect": "Allow",
"Principal": {
"Service": "voiceconnector.chime.amazonaws.com"
},
"Action": "lex:StartConversation",
"Resource": "arn:aws:lex:us-east-1:123456789012:bot-alias/botId/aliasId",
"Condition": {
"StringEquals": {
"AWS:SourceAccount": "123456789012"
},
"ArnEquals": {
"AWS:SourceArn": "arn:aws:chime:us-east-1:123456789012:sma/smaId"
}
}
}
]
}
```
------
## 音声と DTMF のタイムアウトの設定
ユーザー入力をキャプチャするときの音声と DTMF のタイムアウトを設定できます。ボットとの会話を開始するときにセッション属性を使用してタイムアウトを設定し、必要に応じて Lex ボットの Lambda 関数で上書きできます。Amazon Lex では、インテントまたはボットに複数のスロットを設定できます。セッション属性をインテントレベルとスロットレベルに適用するように指定できるため、特定のタイプの入力を収集するときにのみ属性を設定するように指定できます。例えば、アカウント番号を収集する場合は、日付を収集する場合よりも長いタイムアウトを指定できます。セッション属性キーにはワイルドカードを使用できます。
例えば、すべてのインテントのすべてのスロットの音声タイムアウトを 4000 ミリ秒に設定するには、セッション属性名として `x-amz-lex:start-timeout-ms:*:*`、セッション属性値として `4000` を使用して、セッション属性を指定できます。詳細については、「*Amazon Lex Developer Guide*」の「[Configuring timeouts for capturing user input](https://docs.aws.amazon.com/lexv2/latest/dg/session-attribs-speech.htm)」を参照してください。
## 会話中に DTMF 入力の使用
Amazon Lex ボットは、会話中の音声入力とキーパッド入力をサポートします。ボットはキーパッド入力を DTMF の数字として解釈します。入力をシャープ記号 (\$1) で終了し、星の記号 (\$1) を使用して会話をキャンセルするよう問い合わせに求めることができます。顧客にシャープ記号で入力を終了するように促さない場合、Lex は 5 秒後に追加のキー押下を待たなくなります。
## 請求とサービスクォータ
AWS は、次のコストを請求します。
+ 通話での Amazon Chime SDK の使用。詳細については、「[Amazon Chime SDK の料金](https://aws.amazon.com/chime/chime-sdk/pricing/)」を参照してください。
+ ユーザーの音声を解釈するための Amazon Lex の使用。詳細については、「[Amazon Lex 料金](https://aws.amazon.com/lex/pricing/)」を参照してください。
+ ボットからのテキスト応答を合成するための Amazon Polly の使用。詳細については、「[Amazon Polly 料金](https://aws.amazon.com/polly/pricing/)」を参照してください。
また、次のサービスクォータに注意する必要があります。
+ Amazon Chime SDK には、PSTN オーディオ [StartBotConversation](#start-bot-conversation) アクションで使用できる Amazon Lex ボットの最大数に対するサービスクォータがあります。詳細については、「*AWS 全般のリファレンス*」の「[SIP trunking and voice quotas](https://docs.aws.amazon.com/general/latest/gr/chime-sdk.html#chm-sdk-pstn-quotas)」を参照してください。
+ Amazon Lex には、Lex ボットあたりの同時音声会話の最大数に関するサービスクォータがあります。クォータの増量については、Amazon Lex サービスチームにお問い合わせください。詳細については、「*Amazon Lex Developer Guide*」の「[Guidelines and quotas](https://docs.aws.amazon.com/lexv2/latest/dg/quotas.html)」を参照してください。
+ Amazon Polly には、テキスト応答の合成に関するサービスクォータがあります。クォータの増量については、Amazon Polly サービスチームにお問い合わせください。Amazon Polly サービスのクォータの詳細については、「*Amazon Polly Developer Guide*」の「[Quotas in Amazon Polly](https://docs.aws.amazon.com/polly/latest/dg/limits.html)」を参照してください。
# Amazon Chime SDK PTSN オーディオサービスでの SIP ヘッダーの使用
通話コンテキスト情報を SIP インフラストラクチャと交換する場合に、 AWS Lambda 関数で User-To-User ヘッダー、Diversion ヘッダー、およびカスタム SIP ヘッダーを送受信できるようになりました。
+ User-to-User (UUI) ヘッダーを使用して、通話制御データを送信できます。このデータは、セッションを開始するアプリケーションによって挿入され、セッションを受け付けるアプリケーションによって使用されます。基本的な SIP 機能には使用されません。例えば、コールセンターで UUI ヘッダーを使用して、通話に関する情報をエージェント間でやり取りできます。
+ Diversion ヘッダーは、通話がどこから転送されたのか、またその理由を示すために使用されます。このヘッダーを使用して、他の SIP エージェントからの転送情報を確認する、または伝えることができます。
+ カスタム SIP ヘッダーを使用すると、必要なその他の情報を伝えることができます。例えば、アカウント ID を伝える場合は、「X-Account-Id」という X ヘッダーを作成し、この情報を追加できます。
カスタム SIP ヘッダーには `x-` というプレフィックスを付ける必要があります。ヘッダーは AWS Lambda 関数で公開され、インバウンド呼び出し中に`NEW_INBOUND_CALL`イベントの一部として受信されます。また、[CallAndBridge](call-and-bridge.md) アクションや [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplicationCall.html) API をトリガーするときに、これらのヘッダーを発信通話レッグに含めることもできます。
Lambda 関数の `Participants` セクションには `SipHeaders` フィールドが含まれています。このフィールドは、カスタムヘッダーを受け取るとき、あるいは、`User-to-User` ヘッダーまたは `Diversion` ヘッダーにデータを入力するときに使用できます。
この例では、 AWS Lambda 呼び出しに SIP ヘッダーが含まれている場合に予想されるレスポンスを示しています。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type":"actionType",
"Parameters":{
// Parameters vary by actionType
}
},
"CallDetails":{
.....
.....
"Participants":[
{
"CallId": "call-id-1",
"ParticipantTag": "LEG-A",
.....
"Status": "Connected"
"SipHeaders": {
"X-Test-Value": "String",
"User-to-User": "616d617a6f6e5f6368696d655f636f6e6e6563745f696e746567726174696f6e;encoding=hex",
"Diversion": "sip:+11234567891@public.test.com;reason=unconditional"
}
},
{
"CallId": "call-id-2",
"ParticipantTag": "LEG-B",
.....
"Status": "Connected"
}
]
}
}
```
次の例は、`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 文字です。
次の例は、オプションの `SipHeaders` パラメータを使用した、コマンドラインインターフェイスの一般的な [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplicationCall.html) API を示しています。
```
create-sip-media-application-call
--from-phone-number value // (string)
--to-phone-number value // (string)
--sip-media-application-id value // (string)
--sip-headers // (map)
```
詳細については、「[A Mechanism for Transporting User-to-User Call Control Information in SIP](https://datatracker.ietf.org/doc/html/rfc7433)」と「[Diversion Indication in SIP](https://datatracker.ietf.org/doc/html/rfc5806)」を参照してください。
# Amazon Chime SDK PTSN オーディオサービスでの通話詳細レコードの使用
Amazon Chime SDK 管理者は、通話詳細レコード (CDR) を保存するように Amazon Chime SDK Voice Connector を設定できます。CDR を保存するように Amazon Chime SDK Voice Connector を設定する方法の詳細については、「Amazon Chime SDK 管理ガイド」の「[Managing global settings in Amazon Chime SDK](https://docs.aws.amazon.com/chime-sdk/latest/ag/manage-global.html)」を参照してください。
CDR を有効にすると、各通話の後で、SIP メディアアプリケーションが S3 バケット内の **Amazon-Chime-SMADRs** という名前のフォルダにレコードを送信します。
以下の表は、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 Voice Connector ID UUID |
| `"Status":"status"` | 通話のステータス (完了、失敗) |
| `"BillableDurationSeconds":"billable-duration-in-seconds"` | 請求可能な通話時間 (秒単位) |
| `"SchemaVersion":"schema-version"` | CDR スキーマバージョン |
| `"SourcePhoneNumber":"12075550155"` | 発信元の電話番号 (E.164 形式) |
| "SourcePhoneNumberName":"North Campus Reception" | 発信元の電話番号に割り当てられた名前 |
| `"DestinationPhoneNumber":"13605551214"` | 送信先の電話番号 (E.164 形式)。 |
| "DestinationPhoneNumberName":"South Campus Reception" | 送信先の電話番号に割り当てられた名前 |
| `"UsageType":"usage-type"` | Price List API の明細項目の使用状況の詳細 |
| `"ServiceCode":"service-code" ` | Price List API のサービスのコード |
| `"Direction":"direction"` | 通話の方向 (`Outbound` または `Inbound`) |
| `"TimeStampEpochSeconds":"start-time-epochseconds"` | エポック/Unix タイムスタンプ形式のレコードのタイムスタンプ |
| `"Region":"AWS-region"` | AWS Amazon Chime SDK Voice Connector のリージョン |
| `"SipRuleId":"sip-rule-id"` | 通話が PSTN オーディオサービスに届いたときにトリガーされる SIP ルールの ID |
| `"SipApplicationId":"sip-application-id"` | 通話を処理する SIP アプリケーションの ID |
| `"CallLegTriggerType":"trigger-type"` | 通話をトリガーしたイベントのタイプ |
| `"BillableVoiceFocusSeconds":"billable-voice-focus-in-seconds"` | 請求可能な Voice Focus の使用量 (秒単位) |
# Amazon Chime SDK PTSN オーディオサービスのタイムアウトと再試行について
PSTN オーディオサービスは、 AWS Lambda 関数と同期的にやり取りします。アプリケーションは、呼び出しを再試行する前に AWS Lambda 関数が応答するまで 5 秒待ちます。20 秒後に応答が受信されない場合、PSTN Audio サービスは[ハングアップ](unexpected-hangups.md)を発行します。関数が 4*XX* ステータスコードのいずれかでエラーを返した場合、デフォルトでは、SIP メディアアプリケーションは呼び出しを 1 回だけ再試行します。再試行回数を使い切ると、通話は `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 Administrator Guide*」の「[Using SIP media applications](https://docs.aws.amazon.com/chime-sdk/latest/ag/use-sip-apps.html)」を参照してください。ログ記録を有効にすると、`/aws/ChimeSipMediaApplicationSipMessages/` ロググループで Cloudwatch のログを検索できます。
# Amazon Chime SDK PTSN オーディオサービスでの予期しない切断のデバッグ
PSTN オーディオサービスの AWS Lambda 関数で予期しないハングアップやエラーメッセージが発生した場合は、次のトラブルシューティングアクションを実行します。
+ AWS Lambda ポリシーが [voiceconnector.chime.amazonaws.com](http://voiceconnector.chime.amazonaws.com/) サービスプリンシパルにアクセス`lambda:InvokeFunction`許可を付与していることを確認します。
+ AWS Lambda 関数のログをチェックして、正常に呼び出されていることを確認します。
+ ログに受信イベントと返されたアクションが表示されている場合は、 AWS Lambda 関数が呼び出されたときに でハングアップアクションを返さないことを確認します。
+ SIP メディアアプリケーションの CloudWatch ログを確認します。返されるメッセージの一部を次の表に示します。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/unexpected-hangups.html)
# 予想しない ACTION\$1FAILED イベントのデバッグ
予想しない `ACTION_FAILED` イベントが発生した場合は、次の点を確認します。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/unexpected-action-fail.html)
# Amazon Chime SDK PTSN オーディオサービスの VoiceFocus について
Amazon Voice Focus のノイズ抑制を、公衆交換電話網 (PSTN) 通話の受信および発信通話レッグに適用できます。Amazon Voice Focus を適用すると、人間の音声に影響を与えることなくバックグラウンドノイズが低減します。これにより、現在の話者が聞き取りやすくなります。
受信通話レッグを作成するには、`NewInboundCall` イベントで AWS Lambda 関数を呼び出す [SIP ルール](https://docs.aws.amazon.com/chime/latest/ag/manage-sip-applications.html)を使用します。発信通話レッグは、[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 の詳細については、「[How the Amazon Chime SDK's noise cancellation works](https://www.amazon.science/blog/how-amazon-chimes-challenge-winning-noise-cancellation-works)」を参照してください。
Amazon Voice Focus は、次のような音声以外の不要なノイズを低減させます。
+ **環境ノイズ** — 風、換気扇、流水
+ **バックグラウンドノイズ** - 芝刈り機、犬の鳴き声
+ **フォアグラウンドノイズ** - タイピング、書類をめくる音
**注記**
Amazon Voice Focus を使用すると、 は各通話レッグのアクティブな通話分と SIP メディアアプリケーションの使用状況の 1 分ごとに 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**
*説明* – AWS Lambda 関数呼び出しの `CallDetails` の参加者の CallId
*使用できる値* – 有効な通話 ID
*必須* – はい
*デフォルト値* – なし
以下の例は、`VoiceFocus` アクションの成功した `ACTION_SUCCESSFUL` イベントを示しています。
```
{
"SchemaVersion": "1.0",
"Sequence": 3,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type": "VoiceFocus",
"Parameters": {
"Enable": True,
"CallId": "call-id-1"
}
},
"CallDetails":{
.....
.....
"Participants":[
{
"CallId": "call-id-of-caller",
.....
"Status": "Connected"
},
{
"CallId": "call-id-of-callee",
.....
"Status": "Connected"
}
]
}
}
```
以下の例は、`VoiceFocus` アクションの一般的な `ACTION_FAILED` イベントを示しています。
```
{
"SchemaVersion": "1.0",
"Sequence":2,
"InvocationEventType": "ACTION_FAILED",
"ActionData":{
"Type": "VoiceFocus",
"Parameters": {
"Enable": True,
"CallId": "call-id-1"
}
},
"ErrorType": "SystemException",
"ErrorMessage": "System error while running action"
},
"CallDetails":{
.....
.....
"Participants":[
{
"CallId": "call-id-of-caller",
.....
}
]
}
}
```
**エラー処理**
セキュリティ上の理由から、PSTN オーディオアクションでは、顧客アカウントごとに 1 秒あたり 5 件の通話リクエスト (CPS) に制限されています。通話リクエストが 5 CPS の制限を超えると、アクションはエラーメッセージを返します。`VoiceFocus` アクションから返されるエラーメッセージを以下の表に示します。
| エラー | メッセージ | Reason |
| --- | --- | --- |
| `ActionExecutionThrottled` | アクションを実行できませんでした。1 秒あたりのアクションの最大数に達しました。 | 1 秒あたりの Voice Focus アクションリクエスト数がシステム制限を超えました。 |
| `MissingRequiredActionParameter` | アクションの必須パラメータがありません。 | アクションの実行中に必須パラメータが 1 つ以上不足しています。 |
| `SystemException` | アクションの実行中にシステムエラーが発生しました。 | アクションの実行中にシステムエラーが発生しました。 |
**通話フロー**
以下の図は、2 つの PSTN 通話間の `CallAndBridge` アクションに対して Amazon Voice Focus を有効または無効にする通話フローを示しています。
![\[ブリッジされた 2 つの PSTN 通話に対して Amazon Voice Focus を有効または無効にするときの通話フロー。\]](http://docs.aws.amazon.com/ja_jp/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` アクションを送信します。アプリケーションは、通話されている人をハングアップし、Hangup 関数を Lambda 関数に返します。Lambda 関数は、それ以上アクションを実行しません。
# Amazon Chime SDK PSTN オーディオサービスの用語集
\$1 [A](#a) \$1 [C](#c) \$1 [E](#e) \$1 [I](#i) \$1 [L](#l) \$1 [M](#m) \$1 [N](#n) \$1 [O](#o) \$1 [P](#p) \$1 [S](#s) \$1 [T](#t) \$1 [V](#v) \$1
## A
**アクション**
AWS Lambda 関数では、アクションは、数字の送受信、会議への参加など、通話のレッグで実行する項目です。PSTN オーディオサービスが対応しているアクションの詳細については、「[Amazon Chime SDK PSTN オーディオサービスでサポートされるアクション](specify-actions.md)」を参照してください。
**AWS Lambda**
サーバーのプロビジョニングや管理を行わなくても、ほぼすべてのタイプのアプリケーションやバックエンドサービスのコードを実行できるようにするコンピューティングサービスです。
**AWS Lambda 関数**
PSTN オーディオサービスの文脈では、発信などによって SIP メディアアプリケーションから渡されたデータに応じて実行される関数です。
## C
**通話詳細レコード**
Amazon Chime SDK Voice Connector の通話から取得されたデータ (アカウント ID、発信元の電話番号、発信先の国など)。このレコードは、アカウントの Amazon Simple Storage Service (S3) バケットにオブジェクトとして格納されます。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[Managing global settings in Amazon Chime SDK](https://docs.aws.amazon.com/chime-sdk/latest/ag/manage-global.html)」を参照してください。レコードスキーマの詳細については、このガイドの「[Amazon Chime SDK PTSN オーディオサービスでの通話詳細レコードの使用](attributes.md)」を参照してください。
**通話 ID**
すべての着信のレッグに割り当てられる ID。
**通話レッグ**
通話の一部を意味します。Amazon Chime SDK アプリケーションでは、有効な電話番号、PSTN、Amazon Chime SDK Voice Connector から通話を受けることができます。詳細については、このガイドの「[Amazon Chime SDK PSTN オーディオサービスの通話レッグの使用について](call-architecture.md)」を参照してください。
**Carrier**
モバイルサービスを提供する会社を意味し、**ワイヤレスキャリア**の略称でもあります。
**Amazon Chime**
が提供する統合コミュニケーションおよびコラボレーションサービス AWS。
**Amazon Chime SDK**
ソフトウェア開発キット。開発者がカスタムコミュニケーションアプリケーションにリアルタイムメディアやコミュニケーション機能を追加するために使用します。
## E
**E.164**
PSTN オーディオサービスで唯一認められている電話番号の形式です。ITU-T 推奨の番号では、1～3 桁の国コードが使用され、その後に最大 12 桁のサブスクライバー番号が続きます。例: 米国: `+14155552671`、英国: `+442071838750 44`、オーストラリア: `+61285993444`
**エンドポイント**
電話機やユニファイドコミュニケーションアプリケーションなどのハードウェアデバイスまたはソフトウェアサービス。
**EventBridge**
さまざまなソースからのデータにアプリケーションを接続できるサーバーレスイベントバスサービス。
SIP メディアアプリケーションでは、EventBridge にデータが送信されません。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[Automating the Amazon Chime SDK with EventBridge](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html)」を参照してください。
## I
**IVR**
Interactive Voice Response (自動音声応答システム) の略語。音声認識またはタッチトーンキーパッドを使用して、コンピュータによって操作される電話システムと対話できるシステム。
## L
**レッグ**
「[Call leg](#call-leg)」を参照してください。
## M
**メディア**
Amazon Chime SDK ミーティングで使用できる音声、動画、チャットメッセージ。カスタムコミュニケーションアプリケーションでは、各メディアタイプを 1 つ以上使用できます。
**メディアパイプライン**
Amazon Chime SDK ミーティングで音声、動画、メッセージ、イベントをストリーミングしてキャプチャするためのメカニズム。詳細については、このガイドの「[Amazon Chime SDK メディアパイプラインを作成する](media-pipelines.md)」を参照してください。
## N
**電話番号ポータビリティ**
電話会社間やユニファイドコミュニケーションシステム間で電話番号を移転する機能。
## O
**発信**
PSTN から通話を受信し、その通話を VoIP エンドポイントに渡すプロセス。
## P
**参加者タグ**
各通話参加者に割り当てられる識別子 (`LEG-A` または `LEG-B`)。
**ポリシー**
Amazon Chime SDK には、次のタイプのポリシーが必要です。
+ **IAM ユーザーポリシー** — Identity and Access Management ユーザーの権限を定義するポリシー。
+ **会議ポリシー** — 会議中に画面を共有しているときに、ユーザーが別のユーザーのコンピュータを制御できるポリシー。このポリシーにより、Amazon Chime SDK から通話を受けたユーザーが会議に参加するオプションも有効にできます。
**PSTN**
公衆交換電話網。通話機能を提供するインフラストラクチャとサービス。
**PSTN オーディオサービス**
コミュニケーションソリューションに音声機能を追加できるようにする Amazon Chime SDK サービス。
## R
**ルーティング**
Amazon Chime SDK で作成したアプリケーションでは、1 つ以上のルーティングタイプが使用されます。
+ **ネットワークルーティング** — ネットワーク内、複数のネットワーク間、複数のネットワークをまたぐトラフィックのパスを選択するプロセス。
+ **インタラクションルーティング** — 通話を正しい受信者またはエンドポイントに正確に転送するためのプロセス。
+ **通話ルーティング** — 着信をキューに入れ、あらかじめ定義された受信者またはエンドポイントに配信する通話管理機能。
## S
**SBC**
セッションボーダーコントローラー。SIP ベースの Voice over Internet Protocol (VoIP) ネットワークを保護するために導入するネットワーク機器。
**[Sequence] (シーケンス)**
AWS Lambda 関数を呼び出すイベントのシーケンス。シーケンスは、通話中に関数が呼び出されるたびに増加します。
**サービス制限/サービスクォータ**
Amazon Chime SDK で許可される、会議、音声ストリーム、コンテンツ共有といったリソースの最大数。詳細については、このガイドの「[Audio](meetings-sdk.md#audio)」を参照してください。
**SIP**
シグナリングプロトコルである Session Initiation Protocol の略語。リアルタイムセッションの開始、維持、終了に使用されます。音声、動画、メッセージングのアプリケーションを組み合わせた場合にも使用できます。詳細については、「[SIP: Session Initiation Protocol](https://www.rfc-editor.org/rfc/rfc3261.html)」を参照してください。
**SIP ヘッダー**
通話制御データ、およびユーザーアカウント IDs などのその他のデータを含む AWS Lambda 関数のパラメータ。
**SIP メディアアプリケーション**
SIP ルールからターゲット AWS Lambda 関数に値を渡すマネージドオブジェクト。[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplication.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateSipMediaApplication.html) API を呼び出して SIP メディアアプリケーションを開発できますが、そのためには管理者権限が必要です。
**SIP ルール**
Amazon Chime SDK Voice Connector URI の電話番号を対象の SIP メディアアプリケーションに渡す管理対象オブジェクト。
**SIP トランク**
「[Amazon Chime SDK Voice Connector](#voice-connector)」を参照してください。
**SMA**
SIP メディアアプリケーションを参照してください。
**SMA ID**
SIP メディアアプリケーションを参照してください。
## T
**Telco**
通信サービスプロバイダー。
**終了**
通話を終了するプロセス。
**トランザクション**
1 つ以上の通話レッグで構成される通話。詳細については、このガイドの「[Amazon Chime SDK PSTN オーディオサービスの通話レッグの使用について](call-architecture.md)」を参照してください。
**トランザクション ID**
複数の通話レッグで構成されるトランザクションの ID。詳細については、このガイドの「[Amazon Chime SDK PSTN オーディオサービスの通話レッグの使用について](call-architecture.md)」を参照してください。
## V
**Amazon Chime SDK Voice Connector**
電話システム用の Session Initiation Protocol (SIP) トランキングサービスを提供するオブジェクト。Voice Connector を作成し管理するには、Amazon Chime SDK 管理コンソールを使用します。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[Managing Amazon Chime SDK Voice Connectors](https://docs.aws.amazon.com/chime-sdk/latest/ag/voice-connectors.html)」を参照してください。
**Amazon Chime SDK Voice Connector グループ**
異なる AWS リージョンの複数の Voice Connector を含むラッパー。このグループによって、リージョン全体で着信をフェイルオーバーすることで、耐障害性のメカニズムを実現できます。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[Managing Amazon Chime SDK Voice Connector groups](https://docs.aws.amazon.com/chime-sdk/latest/ag/voice-connector-groups.html)」を参照してください。