この記事では、Dynamics 365 Contact Centerで使用するために、Copilot Studio 音声対応エージェントの着信および発信呼び出し用にセッション開始プロトコル (SIP) X ヘッダーを構成する方法について説明します。
SIP Xヘッダーは、電話システムと音声対応エージェント間でカスタムメタデータを渡すことを可能にします。 Dynamics 365 Contact Center音声対応エージェントは、受信 X ヘッダーと発信 X ヘッダーの両方をサポートします。 この構成により、通話転送やルーティング中のシームレスなデータ交換が可能になります。
[前提条件]
音声対応エージェントが有効になっている Dynamics 365 Contact Center
アクセス許可を持ってCopilot Studioにアクセスする
電話構成のためのダイレクトルーティング
Copilot Studio トピックの作成と可変管理の基本的な理解
受信するXヘッダーを設定する
受信するXヘッダーには、外部電話システムから音声対応エージェントへ渡されるメタデータが含まれています。 このデータを受信・利用するためには、システム変数からXヘッダー情報を抽出するConversation.SipXHeaderノードを設定する必要があります。
受信Xヘッダーの要求事項
最大数:着信1回あたり5つのXヘッダー。
命名要件:すべてのXヘッダー名は
x-で始まらなければなりません。注
Copilot Studio では、X ヘッダーを送信する外部システムが大文字
x-を使用している場合でも、すべての受信 X ヘッダーは小文字のX-で始まる必要があります。 Copilot Studio で定義されている送信 X ヘッダーは、外部システムが想定しているケースに応じて、小文字または大文字にすることができます。名前の長さ:最大64文字。
数値の長さ:最大256文字。
すべての期待されるXヘッダーにはJSONスキーマが必要です。
Xヘッダー名が変わったらJSONスキーマを更新してください。
チャネルデータ依存性:Xヘッダーは
Conversation.SipXHeaderに存在しなければなりません。
値解析ノードを含む変数管理の追加
音声対応のエージェントのトピックに移動しましょう。
新しいトピックノードを追加してください。
変数管理を選択し、解析値を選択します。
解析値ノードの設定
システムメニューからParse値フィールドを
Conversation.SipXHeaderに設定します。データ型を「From sample data」に設定してください。
期待されるXヘッダー構造を定義するには、「 サンプルJSONからスキーマを取得する」を選択します。
Xヘッダー用のJSONスキーマを定義してください
「 サンプルJSONからスキーマを取得する 」ダイアログで、受け取る予定のXヘッダー名を含むJSON構造を提供します。 例えば、着信時に X-CallID や X-AAI-Incoming のようなヘッダーが期待されている場合は、それらをJSONスキーマに追加してください。
スキーマを適用するために 「確認 」を選択してください。
Important
Dynamics 365 Contact Center プラットフォームは、外部システムから送信される方法に関係なく、常に小文字の x- プレフィックスを使用するように X ヘッダー名を正規化します。 これは、以下のようなことを意味します。
外部システムが
X-CallIDを送信した場合、スキーマ内でそれをx-CallIDとして定義しなければなりません。外部システムが
X-AAI-Incomingを送信した場合、スキーマ内でそれをx-AAI-Incomingとして定義しなければなりません。
外部システムが大文字の X-を使う場合でも、スキーマは常に小文字の x- を使わなければならず、プラットフォームが正しくヘッドをマッピング・処理できるようにします。
Xヘッダー用の例としてのJSON
{
"x-CallID": "",
"x-AAI-Incoming": ""
}
解析済みデータを保存してください
「 名前を添えて保存 」フィールドで変数を作成または選択してください(例:
IncomingSipXHeader)。
変数のスコープを グローバル に設定し、エージェント内の複数のトピック間でアクセスできるようにします。
トピック内のXヘッダー値にアクセスする
設定が完了すると、以下の例のようにドット表記を使って個々のXヘッダー値にアクセスできます。
Global.IncomingSipXHeader.'x-AAI-Incoming'IncomingSIPXHeaders.sipXHeader.'X-CallID'
ランタイムの動作
Copilot Studio は、外部システムによって送信された最初の 5 つの X ヘッダーのみを受信します。
Copilot Studio では、名前がスキーマと一致すると、レコードに X ヘッダー値が自動的に設定されます。
欠損したXヘッダーは空の文字列値を持ちます。
スキーマの更新は、Xヘッダー名が変更されたり、追加のヘッダーを受け取りたい場合に必要です。
送信Xヘッダーの設定
発信Xヘッダーを使って通話を外部電話番号に転送する際にカスタムデータを渡すことができます。 これらのヘッダーは 転送会話 ノードで設定します。
送信 X ヘッダーの要件
最大数: 1送信あたり5つのXヘッダー。
命名要件:すべてのX-ヘッダー名は、外部システムが期待するケースに応じて
X-またはx-で始まることができます。注
Copilot Studio では、X ヘッダーを送信する外部システムが大文字
x-を使用している場合でも、すべての受信 X ヘッダーは小文字のX-で始まる必要があります。 Copilot Studio で定義されている送信 X ヘッダーは、外部システムが想定しているケースに応じて、小文字または大文字にすることができます。名前の長さ:最大64文字。
数値の長さ:最大256文字。
転送タイプ: 外部電話番号移行のみ利用可能です。
転送会話ノードの設定
トピックフローに Transfer 会話ノードを追加してください。
転送タイプで 外部電話番号転送 を選択し、転送番号を入力します。 例えば、+18005551212。
Transfer ConversationノードプロパティでXヘッダーを設定する
質問 ノードのその他アイコン (…) を選択し、プロパティ を選択します。
+ Add を選択して X ヘッダーのキー・値ペアを追加します。
Xヘッダーのエントリを定義します。 送信されるXヘッダー名は、 転送 会話ノードで定義した通りに正確に送信されます。 受信システムが何を期待するかに基づいて適切なケースを選びます。
-
キーネーム:
X-またはx-で始まる必要があります(例:X-AAI-OutgoingまたはX-CallID) - 値:静的値を入力するか変数を割り当てます
-
キーネーム:
ベスト プラクティス
スキーマの設計
目的を明確に示す説明的なXヘッダー名を使いましょう。
Xヘッダーの要件が変わったら、JSONスキーマを常に更新しておく。
チームの参照やトラブルシューティングのためにXヘッダースキーマをドキュメント化してください。
変数管理
トピック間でアクセスが必要なXヘッダーデータにはグローバル変数を使いましょう。
意味のある変数名(例:
IncomingSIPXHeadersやCustomerXHeaders)を選びます。会話の早い段階で変数を初期化しましょう。
エラー処理
ロジックで値を使う前に、必ずXヘッダーの存在をチェックしてください。
欠損または無効なXヘッダーデータに対してフォールバック動作を実装します。
さまざまなXヘッダーシナリオで徹底的にテストしてください。
パフォーマンスに関する考慮事項
会話の流れの早い段階でXヘッダーを解析しましょう。
必要に応じて、頻繁に使われる値を別変数にキャッシュします。
同じチャネルデータを繰り返し解析するのは避けてください。
入力されるXヘッダーに関する一般的な問題
Xヘッダーの値が受信されない
JSONスキーマが期待されるXヘッダー名と正確に一致しているか確認してください。
Parse Valueノードが
Conversation.SipXHeaderで設定されているか確認してください。複数のトピックからアクセスする場合は、変数をグローバルスコープに設定してください。
Xヘッダーは最大5つ以下に制限し、Xヘッダーは外部システムから送信される上位5つのXヘッダーです。
空またはnullのXヘッダー値
外部システムが期待される名前のXヘッダーを送信しているか確認してください。
JSONスキーマに、必要なXヘッダー名と小文字の
x-プレフィックスが含まれているか確認してください。
送信 X ヘッダーの一般的な問題
転送時に送信されなかったXヘッダー
すべてのXヘッダー名が
X-またはx-で始まることを確認してください。転送タイプが外部電話番号転送に設定されていることを確認してください。
転送会話ノードの前にXヘッダーの値が正しく割り当てられていることを確認してください。
Xヘッダーでの転送失敗
Xヘッダーの名前や値が長さ制限を超えていないか確認してください。
受信システムが送信中のXヘッダーを処理できるか確認してください。
解析の問題を引き起こす可能性のある特殊文字がないか確認してください。
スキーマ管理
Xヘッダースキーマの更新
新しいXヘッダーを受け取るには、「 XヘッダーのDEFINE JSON schema」のJSONサンプルを更新してください。
更新されたスキーマを確認して保存してください。
新しいXヘッダー構成でスキーマをテストしてください。