【ワークショップ1日目】Amazon Chime SDK PSTNで音声ファイルを再生する

Amazon Chime SDK

📅 2022-03-23

Amazon Chime SDK PSTN Audioを触ってみるの1日目です。

今回からは、3月19日に公開されたAmazon Chime SDK PSTN Audio Workshopを何回かにわけてやっていきたいと思います。

今回は、「Amazon Chime SDKで着信通話に応答し、アナウンスの音声ファイルを再生する」というのをやっていきます。

事前にインストールが必要なもの

AWS CLI

AWS CDKを利用して環境構築、Lambdaのデプロイを行うので必須になります。
こちらのドキュメントを参照してインストールを行ってください。

jqコマンド

JSONを処理するためのCLIツールです。

Node Version Manager（nvm）

ワークショップのAWS CDKもLambdaもTypeScriptで書かれており必須です。
最新LTS版を入れました。

macOSやLinuxの場合必要なもの

Windows環境では不要ですが、macOSとLinux環境の場合は下記が追加で必要になります。

AWS CDKのインストール

CDKのbootstrapについては注意があります。
このワークショップのリソースは東京リージョンでは作成できないものが含まれるため、bootstrapをする際にはリージョンの指定をus-east-1（バージニア北部）で行いましょう。

私はCDKを利用するのが初めてで、プロファイルとリージョンを指定してのbootstrapはできましたが、その後のcdk deployでエラーが解消できなかったため、defaultプロファイルのリージョンを変更して対応しました。

[default]
# defaultプロファイルのリージョンをus-east-1にする
region = us-east-1
output = json

$ npm install -g aws-cdk
$ cdk bootstrap

TypeScriptのインストール

$ npm install -g typescript

環境の用意

まずはワークショップのリソースをAWSへデプロイするところから開始します。

以下のコマンドを実行します。
※ここでエラーになる場合、事前準備で不足や間違いがあるので確認します。

$ git clone https://github.com/aws-samples/amazon-chime-sdk-pstn-audio-workshop
$ cd amazon-chime-sdk-pstn-audio-workshop

$ yarn deploy

デプロイが環境すると、以下のような実行結果が表示されます。

chime-sdk-play-message-firstdeploy

マスクしている部分はChimeで発行された電話番号になります。+1なのでアメリカの、505はニューメキシコ州の番号が発行されました。

日本の法律上難しいかもしれませんが、プログラムで電話番号がプロビジョニングできるのは激アツですね！

発行された番号に電話をかけてみる

動作確認として、Amazon Connectから発行された電話番号に発信をしてみました。

Hello! You are calling from "電話番号読み上げ". Thanks for calling! Goodbye!

とAmazon Pollyのアナウンスが再生されて通話切断となりました。

ここまで確認できれば環境の用意は完了です。

今回のワークショップでの期待する動作

今回やるレッスンはこちら

アプリケーションが電話に応答し、音声ファイルのメッセージを再生し、通話を切断します。

アプリケーションの動き

プロビジョニングされた電話番号に着信すると、NEW_INBOUND_CALLイベントでLambda関数が呼び出されます。イベントは以下のようなオブジェクトです。

{
    "SchemaVersion": "1.0",
    "Sequence": 1,
    "InvocationEventType": "NEW_INBOUND_CALL",
    "CallDetails": {
        "TransactionId": "87111142-c672-4d09-aba2-6f55920ab76c",
        "AwsAccountId": "<accountnum>",
        "AwsRegion": "us-west-2",
        "SipRuleId": "cce5c298-4e61-4f6b-bf87-39cacfb5a15f",
        "SipMediaApplicationId": "9324457f-ad47-407d-bf45-5d409e714808",
        "Participants": [
            {
                "CallId": "409911e5-bfe6-40a5-8bdf-983f5ed5e0a1",
                "ParticipantTag": "LEG-A",
                "To": "+15053172485",
                "From": "+14155551212",
                "Direction": "Inbound",
                "StartTimeInMilliseconds": "1645498023381"
            }
        ]
    }
}

InvokecationEventTypeがNEW_INBOUND_CALLにマッチした場合、メディアファイルを再生する関数を呼び出すだけです。

関数はplayAudioActionのAudioSourceオブジェクトにファイル名をセットし、PSTNサービスへ3つのアクションをレスポンスとして送信します。"pauseAction"、"playAudioAction"、"hangupAction"の3つです。

function newCall(event: any) {
  console.log("wavFileBucket: ", wavFileBucket);
  playAudioAction.Parameters.AudioSource.Key = "hello-goodbye.wav";
  return [pauseAction, playAudioAction, hangupAction];
}

レスポンスオブジェクト

{
    "SchemaVersion": "1.0",
    "Actions": [
        {
            "Type": "Pause",
            "Parameters": {
                "DurationInMilliseconds": "1000"
            }
        },
        {
            "Type": "PlayAudio",
            "Parameters": {
                "Repeat": "1",
                "AudioSource": {
                    "Type": "S3",
                    "BucketName": "callplayrecordingstack-wavfiles98e3397d-19qbcdkjeu4bq",
                    "Key": "hello-goodbye.wav"
                }
            }
        },
        {
            "Type": "Hangup",
            "Parameters": {
                "SipResponseCode": "0",
                "ParticipantTag": ""
            }
        }
    ],
    "TransactionAttributes": {
        "key1": "val1*",
        "key2": "val2*",
        "key3": "val3*"
    }
}

シーケンス図

シーケンス図を見ると、上記と同様の流れになります。

PSTNサービスからNEW_INBOUND_CALLイベントでLambdaを実行し、レスポンスとして3つのアクションを返します。
すべてのアクションが正常に終了するとACTION_SUCCESSFULLイベントでLambdaが実行されます。ここでは何もせず終了します。
最後にHANGUPイベントでLambdaが実行されます。ここでも何もせず終了すると一連の処理が終了します。

chime-sdk-play-message-sequence

TransactionAttributesについて

TransactionAttributesを使用すると、アプリケーション固有の情報（例：通話状態、会議ID、参加者IDなど）を保存することができます。

TransactionAttributesはSMA（SIP Media Application）に格納され、そのセッション内のイベントオブジェクトに透過的に（継続的に）渡されます。セッションの単位は1通話なので、特定の通話内の各イベントからのLambda呼び出しで属性を使い回すことができます。属性を利用することで、各通話固有のデータをDynamoDBのような外部データベースに保存する必要がなくなります。

これはAmazon Connectにおける問い合わせ属性と同じように考えれば大丈夫そうですね。

TransactionAttributesの詳細はこちらのドキュメントを参照ください。