Open in
通話ごとの変数とコンテキスト
エージェントを変更せずに、各通話に固有の詳細を、プロンプト用の名前付き変数または自由形式の概要として渡します。
各通話には、通話ごとに2種類の入力を渡せます。どちらか一方、または両方を組み合わせて使用します。
variables: プロンプト内の{{placeholders}}を埋める名前付きの値です。発信者の名前、口座番号、予約枠など、プロンプトで名前を指定して参照するフィールドに使用します。context: プロンプトの後に追加される自由形式のテキストです。この通話のタスクの説明や、事前に収集したメモなど、テンプレートに収まらない概要に使用します。
どちらも、保存済みエージェントとインライン設定で使用でき、以下で説明するすべての通話開始方法に対応します。保存済みエージェント、そのバージョン履歴、その他の設定は変更されません。
{
"agent_id": 12,
"variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
"context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}変数
保存済みエージェントのプロンプトにプレースホルダーを配置し、通話開始時に variables
オブジェクトを指定します。ThunderPhone は、通話設定を音声ランタイムに送信する前にテキストをレンダリングします。
値が不要な場合は variables を省略し、null は送信しないでください(400 で拒否されます)。
プレースホルダーとデフォルト値
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.名前では大文字と小文字が区別され、[A-Za-z_][A-Za-z0-9_]* に従います。名前の前後の空白は
許可されます。| の後の空白はデフォルト値の一部として保持されます。{{name|Friend}} は、name が存在しないか
null の場合に Friend を使用します。空文字列は明示的に指定された値として扱われます。デフォルト値のない
欠落値は空文字列になり、その名前は unresolved_variables に表示されます。
有効なプレースホルダーではない二重波括弧内のテキストは削除されます。指定した各値に含まれる二重波括弧内の
テキストも個別に削除されます。値によって周囲のプロンプトテキストや別の値を削除することはできません。不一致の
二重波括弧区切り文字も削除されます。プロンプト内の JSON 例では {{ を使用しないでください。
値はプレーンテキストであり、コードとして評価されたり、テンプレートとして再帰的に展開されたりすることはありません。
変数は、確認プロンプト、発信ボイスメールメッセージ、および電話の通話時にそのフィールドが送信される場合の
同意告知テキストにも使用できます。エージェントには個別の first_message フィールドはありません。開始時の
指示はプロンプトに記述してください。既存のボイスメール用 {agent_name} および {org_name}
プレースホルダーは引き続き利用できます。
値と制限
値には文字列、数値、ブール値、または null を使用できます。ブール値は true
と false としてレンダリングされます。改行(\n)、タブ(\t)、
キャリッジリターン(\r)を除く Unicode 制御(Cc)文字、ゼロ幅非接合子と接合子
(インド系言語およびアラビア文字の言語で単語を綴る U+200C、U+200D)を除く書式
(Cf)文字、ならびにサロゲート(Cs)コードポイントは削除されます。\r\n
は \n に正規化されます。各値はレンダリング時に
2,000 文字までに制限されます。指定された文字列も、保存前にクリーンアップおよび
切り詰めが行われます。元のオブジェクトは UTF-8 JSON 32 KB以内 に収める必要があります。
これより大きいオブジェクトでは、通話またはセッションのリクエストで 400 が返され、
キャンペーンのインポートでは無効な行が個別に報告されます。配列およびネストされたオブジェクトは
値として受け付けられません。一致しないメタデータキー(たとえば空白を含む CSV ヘッダー)は
保持およびエコーされますが、プレースホルダーから参照することはできません。
コンテキスト
context は最大 20,000 文字 の文字列です。ThunderPhone は、
プロンプトの変数を埋めた後に、区切られたブロックとしてプロンプトの末尾へ追加します。
<your prompt, with its variables filled in>
Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>エージェントは指示とともにこれを読み取るため、通話前に同僚へ伝える内容として
記述してください。コンテキストはテンプレートではありません。
その中の {{name}} は記述どおりに維持されます。テキストに値が必要な場合は、
送信前に値を埋め込んでください。
null、空の文字列、または空白文字のみの場合、コンテキストはありません。- 文字列でない値、または20,000文字を超える値は、通話およびセッションのリクエストで
400により拒否されます。設定Webhookからの場合は、無効なvariablesと同様に交換に失敗します(下記参照)。 - 先頭と末尾の空白文字はトリミングされ、変数値と同じ制御文字および書式文字が削除されます。
- コンテキストは通話のプロンプトの一部であるため、通話のプロンプトサイズにカウントされます。
ステップを使用するエージェントでは、コンテキストは 各ステップの指示ではなく、通話内のすべてのエージェントのプロンプトの後に続きます。
値の取得元
発信 API
POST /v1/call で variables と context を送信します。
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"variables": {
"name": "Ada",
"account_id": "A-17",
"appointment_slot": "Tuesday at 10 AM"
},
"context": "Ada asked to be called back about the late fee on her March invoice."
}どちらも電話番号のデフォルト送信エージェント、またはインラインの
config.prompt で使用できます。インライン設定では、設定Webhookが返すフィールドと同じく、context を config 内に含めることもできます。両方を送信する場合は、同じテキストである必要があります。異なる変数または異なるコンテキストで、べき等性キーを再利用することはできません。
キャンペーン CSV
電話番号以外の CSV 列は、すでに連絡先変数として保存されています。各発信で自動的に使用されます。プレースホルダーに対応させるには、name、account_id、appointment_slot などのヘッダーを使用します。既存の名前マッピングでは、名と姓の列を変数 name に結合できます。キャンペーンの連絡先には、連絡先ごとのコンテキストはありません。
動的設定Webhook
ブロッキング構成Webhookパスでは、組織に保存されているエージェントと通話ごとの値を返します。フルデュプレックスエージェントでは、別のサポート対象言語で通話が開始された場合でも、通話はエージェントの音声を維持します。この通話には、言語ごとの音声マッピングおよびネイティブ音声切り替えは適用されません。
{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "[REDACTED_LITERAL]"
}{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}レスポンスの変数はリクエストレベルの変数を上書きしますが、その他のリクエストキーは保持されます。レスポンス値が null の場合、プレースホルダーのデフォルト値が選択されます。
マージされたオブジェクトも 32 KB 以内に収める必要があります。保存済みエージェントのレスポンスで受け付けられるのは
agent_id、variables、context、language、および通話ごとの
timezone のみです。プロンプトやその他の設定を
置き換える必要がある場合は、インライン設定を返してください。保存済みエージェントの webhook
レスポンスでは、電話通話とウィジェット通話の両方でエージェントにデプロイされた A/B 分割が使用されます。
変数はバリアント選択後にレンダリングされます。非 Full duplex エージェントに対してレスポンスで language を設定した場合、
エージェントにその言語用の音声が設定されていれば、通話でもその言語固有の音声が使用されます。prompt を含むレスポンスは
常にインライン設定を使用します。そのレスポンス内の agent_id は、null または
整数以外のメタデータを含めて無視されます。インラインプロンプトも通常の検証に合格する必要があります。
インライン webhook レスポンスには、variables と context も含められます。文字列ではない、または長すぎる context
は交換に失敗します。電話通話は拒否され、ウィジェットセッションリクエストは 400 で失敗します。保存済みエージェントの webhook
レスポンスでは、電話通話とウィジェット通話の両方でエージェントにデプロイされた A/B 分割が使用されます。
変数はバリアント選択後にレンダリングされます。着信電話では、着信エージェントが割り当てられていない番号を使用し、
その電話番号または組織の webhook を設定してください。ウィジェットキーでは mode="webhook" を使用します。エンドポイントシステムの着信通知では、ブロッキング設定レスポンスは提供されません。
エージェント通話設定Webhook
番号をそのエージェントに割り当てたまま、通話固有の値のみを入力するには、エージェントに通話設定Webhookを設定します。
エージェントが番号で受信通話に応答する前に、Webhook は通話とエージェントの ID、名前、バージョンを受け取り、agent_id を指定せずに、上記と同じ variables、context、language、通話ごとの timezone を返します。デフォルト値のないプレースホルダーを設定で使用するエージェントが電話番号に応答するには、このWebhookが必要です。Webhook が失敗すると通話は開始されません。{{name|there}} のようにデフォルト値があるプレースホルダーでは、Webhook なしでエージェントが応答できます。
SIP ヘッダー
SIP 経由でエージェントに到達する通話(SIP アドレス、または手動 SIP 接続上の番号)では、X-* および User-to-User ヘッダーでコンテキストを渡せます。各ヘッダーは {{sip_x_amzn_connectcontactid}} や {{sip_uui}} などの sip_ 変数になり、優先順位は最も低くなります。同名の値が API または webhook から渡された場合は、そちらが優先されます。SIP ヘッダーで通話コンテキストを渡すを参照してください。ヘッダー値は送信者が設定するため、ブラウザから渡される値と同様に信頼しない値として扱ってください。
ウィジェットセッション API
POST /v1/widget/session は、トップレベルの variables と language を受け取ります。公開可能キーによって、保存済みのエージェントが選択されます。Webhook モードのキーは、これらの値を設定用 Webhook に転送し、上記の説明どおりにレスポンスをマージします。
ブラウザから指定されたウィジェットの variables はクライアント側で制御され、上記の検証と文字列クリーンアップの後、web.incoming にそのまま転送されます。また、完了 Webhook と通話履歴にも反映されます。信頼できる本人確認データや認可データとして扱わないでください。
ウィジェット独自のブラウザー context フィールドは異なります。これは訪問者が表示している
ページのテキストを保持し、エージェントはこれをウェブサイトコンテンツとして扱います
(ウェブウィジェットを埋め込むを参照)。ウィジェット通話の
通話ごとのコンテキストは、上記のとおりウェブフックモードのキーの設定ウェブフックから取得されます。
通話に両方がある場合は、通話ごとのコンテキストが先に、その後にページコンテンツが続きます。
リアルタイムセッション API
POST /v1/realtime/sessions は、agent_id またはインラインの config とともに、トップレベルの variables、context、language を受け取ります。
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context は最上位にのみ指定できます。インライン config では不明なフィールドとして
拒否されます。
リアルタイム WebSocket
保存済みエージェントでは、保存済みエージェントのデプロイ済みプロンプトがそのプロンプトとして維持されます。
session.instructions は通話のコンテキストになり、session.prompt.variables
(または session.config.variables)はその変数になり、session.language
は通話ごとの言語になります。最初の session.update で session.prompt.id
を使用してエージェントを選択します。この更新が到着するとセッションが開始されます。
{
"type": "session.update",
"session": {
"type": "realtime",
"prompt": {"id": "12", "variables": {"name": "Ada"}},
"instructions": "Ada asked for a callback about her delivery window."
}
}接続 URL の ?agent_id=12 は、session.update より前にソケットの接続直後にエージェントを開始するため、通話ごとの入力は渡されません。最初の session.update を待機し、その
instructions と変数を使用するには、&wait_for_session_update=1 を追加します。
インラインセッション(保存済みエージェントなし)では、これまでどおり session.instructions がプロンプト自体になります。ブラウザでのテスト通話とシミュレーションでは、デフォルト値と未設定のプレースホルダーが解決されます。値を指定してテストするには、エージェントに通話設定サンプルを保存し、テスト開始時に選択します。通話設定Webhookがそのサンプルを返した場合と同様に通話が実行されます。
通話後
GET /v1/calls、GET /v1/calls/{call_id}、telephony.complete、および web.complete には、最終的にマージされた variables と unresolved_variables が含まれます。data.history を含むレガシー完了ペイロードにも、これらが含まれます。
{
"variables": {"name": "Ada", "account_id": "A-17"},
"unresolved_variables": ["appointment_slot"]
}通話の prompt_snapshot(GET /v1/calls/{call_id})には、変数が入力されコンテキストブロックが追加されたエージェントの
プロンプトが表示されます。
完了した通話を元のレコードに関連付けるには、CRM またはタスクの識別子を variables オブジェクトに保存します。変数とコンテキストは通話レコードとともに保持されます。通話履歴と Webhook に保持してよい情報のみを送信してください。
検証セット、リプレイ実行、 調査での通話のリプレイでは、テスト対象のプロンプトとともにその通話の変数と コンテキストが使用されます。そのため、リプレイではその通話でエージェントに伝えられた内容がテストされます。
既存プロンプトとの互換性
レンダリングは、既存の保存済みエージェントおよびA/Bバリアントのプロンプト、インラインの発信・リアルタイム設定、設定Webhookから返されるプロンプトにも適用されます。variables が指定されていない場合でも、不明な {{name}} プレースホルダーは空白テキストになります。ThunderPhone が一覧化できない外部提供のインライン/Webhookプロンプトを含め、展開前に既存のプロンプトを確認してください。ブラウザでのテスト通話とシミュレーションにも、保存済みの通話設定サンプルを選択しない限り、同じデフォルト値/空白の動作が適用されます。