コンセプトとトラブルシューティング

このページでは、統合に必要な特定の構成と、一般的な問題のトラブルシューティングについて詳しく説明します。

電話ネットワークの要件

ネットワークでアウトバウンド トラフィックをフィルタリングする場合は、SIP シグナリングとメディア ストリーミングのアウトバウンド トラフィックを許可する必要があります。

SIP シグナリングでは、ポート 5672 経由の IP 範囲 74.125.88.128/25（TCP）全体を許可する必要があります。より制限の厳しいファイアウォール ルールセットでは、SIP シグナリングを 1 つ以上のリージョン化された GTP SIP サーバーに制限できます。

  • 米国リージョン: us.telephony.goog（74.125.88.132）
  • EU リージョン: eu.telephony.goog（74.125.88.133）
  • アジア太平洋地域: ap.telephony.goog（74.125.88.134）
  • 南米リージョン: sa.telephony.goog（74.125.88.135）

RTP メディアの場合は、CIDR IP 範囲 74.125.39.0/24 宛てのトラフィックを許可するようにファイアウォール ルールを構成する必要があります。通常、メディアに必要なポートは 16384 ～ 32767（TCP+UDP）のみですが、このポート範囲は将来拡張される可能性があります。

サポートされている SBC ベンダーまたはモデル

次の表に、サポートされている SBC ベンダーまたはモデルとファームウェア バージョンを示します。各ベンダーの詳しい統合手順は、ファームウェア バージョンにリンクされています。

ベンダーとモデル ファームウェア バージョン
AudioCodes VE SBC v7.40A.500.786
Avaya Session Border Controller for Enterprise v8.1.3.2-38-22279、v10.2.0.0-86-24077
Oracle E-SBC Acme Packet 3900 SCZ9.3.0 GA（ビルド 46）
Ribbon Swe Core SBC v11.01.01R005
Cisco Unified Border Element（CUBE） v17.15.03a

サポートされている SBC シグナリングとメディア プロトコル
シグナリング プロトコル SIP over TLS
メディア SRTP
メディア暗号化 SDES
サポートされているメディア暗号スイート AES_CM_128_HMAC_SHA1_80、AEAD_AES_256_GCM
サポートされているメディア コーデック G.711 µ-law（PCMU）、G.711 A-law（PCMA）、Opus

SIP ヘッダー

会話プロファイルと電話番号を設定したときに、sipConfig.createConversationOnTheFly が true に設定された CCAI 会話プロファイルを作成しました。会話 ID は、Call-Info または UUI の SIP ヘッダー値を使用して、SIP INVITE 中に動的に生成する必要があります。

SIP ヘッダー値は、Google Cloud プロジェクト ID と会話 ID を定義することで、Dialogflow エンドポイントを指します。

  1. Google Cloud プロジェクト ID は、 Google Cloud プロジェクトを設定したときに使用したプロジェクトです。
  2. 会話 ID は、SBC によって動的に生成される必要があります。会話 ID は、正規表現の式 [a-zA-Z][a-zA-Z0-9_-]* に準拠し、文字の長さが [3,64] の範囲内である必要があります。会話 ID を動的に生成する一般的なパターンは、SIP INVITE の Call-ID 値を使用し、前に文字を付けて、前述の正規表現に準拠させることです。たとえば、Call-ID 値が 297363723_79131759_799783510 の場合、Call-ID 値の前に "CID-" を付加すると、正規表現 [a-zA-Z][a-zA-Z0-9_-]* に準拠します。

Call-Info SIP ヘッダー

SIP INVITE に Call-Info というカスタム SIP ヘッダーを挿入して、会話 ID を一意に設定します。

Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

例:

Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510>;purpose=Goog-ContactCenter-Conversation

UUI SIP ヘッダー

カスタム SIP ヘッダー Call-Info の設定がサポートされていない場合は、SIP INVITE で UUI（User-to-User）SIP ヘッダーを構成して会話 ID を渡すことができます。

Call-Info でリクエストされたデータと同じデータを使用します。URL は 16 進数でエンコードされ、目的は Goog-ContactCenter-Conversation に設定されます。次の例は、デコードすると http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510 になる 16 進文字列を含むヘッダーです。

User-to-User: 687474703a2f2f6469616c6f67666c6f772e676f6f676c65617069732e636f6d2f763262657461312f70726f6a656374732f6763702d70726f6a6563742d69642d31323334352f636f6e766572736174696f6e732f4349442d3239373336333732335f37393133313735395f373939373833353130;encoding=hex;purpose=Goog-ContactCenter-Conversation

追加のデータを会話エージェントに渡してセッション パラメータとして設定する必要がある場合は、16 進数でエンコードされたキーと値のペアのセミコロン区切りリストを渡してから、;encoding=hex;purpose=Goog-Session-Param を追加します。これにより、デコードされたペイロード文字列のリストを含む uui-headers という名前のセッション パラメータが作成されます。

たとえば、文字列 key1=value1;key2=value2 を渡す必要がある場合、次の UUI ヘッダーが送信されます。ここで、ペイロードは key1=value1;key2=value2 の 16 進数エンコード値です。

User-to-User: 6B6579313D76616C7565313B6B6579323D76616C756532;encoding=hex;purpose=Goog-Session-Param

これにより、次のセッション パラメータが作成されます。

{
    "uui-headers": ["key1=value1;key2=value2"]
}

SBC が複数の UUI ヘッダーの送信をサポートしている場合は、UUI ヘッダーごとに個別のキー値文字列を送信できます。これらの文字列は、uui-headers セッション パラメータで個別の値として使用できます。

次のスニペットは、パラメータ値を取得し、パラメータを複数回分割して、文字列内の key2 変数の適切な値にアクセスします。

$sys.func.GET($sys.func.SPLIT($sys.func.GET($sys.func.SPLIT($session.params.uui-headers,";"),1),"="),1)

次の例は、Playbook のコードブロックのトリガーから呼び出される関数を示しています。@PlaybookStartHandler: ハンドブックに入るときに呼び出されます。他の関数は、この関数を呼び出して uui-headers パラメータから値を取得します。

def _get_fromuui(attribute):
    try:
        uui_headers_src = history.playbook_input.action_parameters['uui-headers']
        # If uui_headers_src is a string, split by ';'
        if isinstance(uui_headers_src, str):
            headers = uui_headers_src.split(';')
        else:
            # If it's a list, join and split
            headers = ';'.join(uui_headers_src).split(';')
        for header in headers:
            header = header.strip()
            if header.lower().startswith(f"{attribute.lower()}="):
                return header[len(attribute) + 1:]
        return ""
    except Exception:
        return ""

追加のデータは、異なる「目的」の値を持つ個別の UUI ヘッダーを使用して送信できます。これらの値は Conversation.telephonyConnectionInfo オブジェクトに追加されます。このデータは、実行時に会話エージェント（Dialogflow CX）エージェントで使用できません。

人間のエージェントの情報を渡す

人間のエージェントに固有の情報を渡す必要がある場合は、人間のエージェントのリアルタイム転送プロトコル（RTP）ストリームのセッション記述プロトコル（SDP）メディアラベル属性を必要なデータ値に設定できます。例: none a=label:7382373482 このデータは sip_recording_media_label フィールドに入力され、文字起こしを含む New message notification Pub/Sub トピックで使用できます。pubsub Message.attributes メッセージで sip_recording_media_label フィールドを探します。

参加者のロールとメディア ストリームの順序を構成する

デフォルトでは、最初のメディア ストリームは END_USER 参加者ロールに関連付けられ、後続のメディア ストリームは HUMAN_AGENT 参加者ロールに関連付けられます。

異なる動作が必要な場合（アウトバウンド通話システムなど）、ヘッダーで渡される URL に roles パラメータを追加する必要があります。

例: none http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510?roles=HUMAN_AGENT,END_USER

この URL は、最初のメディア ストリームが HUMAN_AGENT ロールを持ち、2 番目のメディア ストリームが END_USER ロールを持つことを指定しています。roles パラメータは、Call-Info または UUI SIP ヘッダーで適用できます。

特定の会話に追加のパラメータを設定する

特定の会話に追加のパラメータを設定するには、MatchIntentRequest RPC 呼び出しを使用します。query_params.parameters を必要なキーと値のペアに設定し、query_input.text を「パラメータの設定」などの値に設定できます。

最初の SIP INVITE の 200 OK レスポンスの後に API 呼び出しを行います。この時点で会話が作成されています。MatchIntentRequest のセッション ID は、INVITE の Call-Info ヘッダーで提供される会話 ID と同じです。

SIP REFER を使用して SIP エンドポイントに通話を転送する

仮想エージェントから SIP エンドポイントに電話を転送するには、SIP REFER メソッドを使用します。Live agent handoff フィールドにペイロードを含め、Telephony transfer call フィールドをアウトバウンド SIP REFER Refer-To フィールドに設定されている数値に設定します。ペイロードは次のコード例のようになります。

{
    "sip-refer": true
}

会話エージェント（Dialogflow CX）からデータを渡す必要がある場合は、UUI ヘッダーを使用してデータ文字列を渡すことができます。SIP REFER を実行して 2 つの Key-Value ペアを渡す場合は、次のコードサンプルのようなペイロードを使用できます。

{
    "sip-refer": true,
    "uui-headers": [
        "key1=value1;key2=value2"
    ]
}

これにより、次の UUI ヘッダーを含む SIP REFER が生成されます。

User-to-User: <hex encoded "key1=value1;key2=value2">;encoding=hex;purpose=Goog-Session-Param

SIP BYE でデータを渡す

End Session に移動すると、SIP BYE がトリガーされます。会話エージェント（Dialogflow CX）からデータを渡す場合は、UUI ヘッダーを使用してデータ文字列を渡すことができます。End Session に移行する前に、次のコードサンプルと同様に Live agent handoff ペイロードを定義したページに呼び出しをルーティングします。

{
    "uui-headers": [
        "key1=value1;key2=value2"
    ]
}

これにより、次の UUI ヘッダーを含む SIP BYE が生成されます。

User-to-User: <hex encoded "key1=value1;key2=value2">;encoding=hex;purpose=Goog-Session-Param

リモートの通話相手が電話を切ったときにアクションをトリガーする

新しい BiDi API（ConversationProfile の use_bidi_streaming=True）は、リモートの呼び出し元が電話を切ったときに、プレイブック内のツール呼び出しまたはフロー内の Webhook 呼び出しをトリガーすることをサポートしています。

リモートの呼び出し元が電話を切ると、会話エージェント（Dialogflow CX）は SIP BYE メッセージを受信し、カスタム イベント sys.remote-call-disconnected がトリガーされます。この特定のイベント名でハンドラを作成すると、フロー内のプレイブックまたは Webhook 呼び出しでツール呼び出しをトリガーするために使用できます。

トラブルシューティング

Google チームから、SIP OPTIONS ping と実施されたテスト通話のトラブルシューティングを支援するために、次のアーティファクトの提供を求められることがあります。

  1. ネットワーク パケット キャプチャ
  2. 完全なヘッダーと SIP SDP を示す SIP デバッグ トレース:
    • Call-ID 値
    • Call-Info 値（存在する場合）

ネットワーク パケット キャプチャ

ネットワーク パケット キャプチャには、次の内容が表示されます。

  1. SBC と GTP SIP サーバー間の完全な 3 ウェイ TCP ハンドシェイク（SYN、SYN-ACK、ACK）が TCP ポート 5672 で通信されます。TCP 接続を確立できなかった場合、考えられる問題は次のとおりです。

    • ネットワークがアウトバウンド トラフィックをブロックしている。
    • 通信が地域化された GTP SIP サーバーのいずれかに送信されていません。電話接続のネットワーク要件をご覧ください。
    • 通信が TCP ポート 5672 経由で送信されていません。

  2. 次の情報を含む完全な TLS 接続 handshake:

    • SBC によって開始された TLS v1.2 以降。
    • SBC が「Client Hello」を開始し、GTP が「Server Hello」で応答します。
    • 相互 TLS 認証プロセス。
      • GTP は、SBC によって認証された独自のサーバー TLS 証明書で応答します。
      • SBC は、GTP によって認証される独自のクライアント TLS 証明書を送信します。
    • 「Encrypted Handshake Message」から、暗号化されたチャンネルが確立されたことがわかります。
    • TLS チャネル経由で「アプリケーション データ」が送信された証拠。

    TLS 接続を確立できなかった場合、次の問題が考えられます。

    • GTP 側で SIP トランクが作成されていません。
    • 構成された SIP トランクの FQDN が、SBC からの TLS 証明書（CN または SAN 属性）で提示された FQDN と一致していません。
    • TLS バージョンがサポートされていません。TLS バージョン 1.2 以降のみがサポートされています。
    • リクエストされた暗号スイートはサポートされていません。SBC の TLS 構成をご覧ください。
    • 信頼できない TLS 証明書プロバイダについては、SBC の TLS 構成をご覧ください。

  3. SIP デバッグ トレースには、次の内容が表示されます。

    • お客様の Call-Info SIP ヘッダーが次の形式で挿入されます。 none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

      例: none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510>;purpose=Goog-ContactCenter-Conversation

    • SIP ヘッダーに E.164 形式（+16501234567）で電話番号が表示されます。

    • SIP ヘッダーには、リクエスト URI や他の SIP ヘッダー フィールド（To、From、Via など）で使用されているパブリック IP アドレスが表示されます。プライベート IP アドレスは拒否されます。

    • SIP SDP 接続情報（c= ... ）はパブリック IP アドレスで指定されます。プライベート IP アドレスは拒否されます。

    • GTP は最初のメディア ストリームをデフォルトでエンドユーザーとして扱うため、メディアの優先順位付けで、エンドユーザーのストリームが最初に送信され、次に人間のエージェントのメディア ストリームが送信されるようにします。

    SIP エラー レスポンス コードを受け取った場合:

    • SIP 400 のエラー（488 Not Acceptable Here など）のレスポンス コードは、GTP が SIP ヘッダーまたは SIP メディア SDP 構成を拒否したことを示している可能性があります。
    • SIP 600 エラー（SIP 603 Declined Error）レスポンス コードは、クォータ関連の問題を示している可能性があります。引き上げをリクエストする方法については、割り当てと上限のページをご覧ください。