AIエージェントのためにZendesk Sunshine Conversationsでユーザーデータにアクセスして使用する方法

パーソナライズされた顧客体験は、誰と話しているかを知ることから始まります。顧客がAIエージェントに連絡するとき、彼らは一般的な応答以上のものを期待します。彼らはあなたのエージェントが自分の名前を知り、自分の履歴を理解し、自分の問題に関する背景情報を持っていることを望んでいます。Zendesk Sunshine Conversationsのユーザーデータは、これを可能にします。

Sunshine Conversationsは、ZendeskのAIエージェントの下にあるメッセージングレイヤーとして機能し、WhatsAppメッセージからWebチャットまで、すべてを処理します。しかし、その中に保存されているユーザーデータにアクセスするには、APIアーキテクチャを理解し、どのエンドポイントを呼び出すかを知る必要があります。このガイドでは、顧客データを取得して使用し、よりパーソナライズされたAIエージェント体験を作成する方法を正確に説明します。

カスタムAPI連携を構築する必要がない、よりシンプルなアプローチをお探しの場合は、別の方法があります。当社のプラットフォームはZendeskに直接接続し、ユーザーデータへのアクセスを自動的に処理します。ただし、カスタムソリューションを構築している場合、またはデータフローを完全に制御する必要がある場合は、この技術ガイドで知っておくべきことを正確に説明します。

Sunshine Conversationsのデータアーキテクチャを理解する

Sunshine Conversations（旧Smooch.io）は、Zendeskのすべてのメッセージングインタラクションの基盤となるデータレイヤーとして機能します。元々はスタンドアロン製品でしたが、現在はZendesk Suiteに完全に統合されており、顧客、AIエージェント、および人間のエージェント間のメッセージのルーティングという大変な作業を処理します。このプラットフォームは、複数のチャネルを単一の会話インターフェースに接続する統合メッセージングAPIを提供します。

データの流れは次のとおりです。顧客がWhatsApp、Webウィジェット、またはその他のチャネルを介してメッセージを送信すると、Sunshine Conversationsはそのメッセージを受信し、ユーザーを識別し、適切なハンドラーにルーティングします。次に、AIエージェントはSunshine Conversationsとやり取りして、ユーザープロファイル、会話履歴、およびメタデータにアクセスします。

このプラットフォームは、ユーザーデータをいくつかの異なる場所に保存します。

Userオブジェクト：これには、ユーザーのID、名前（profile.surnameおよびprofile.givenName）、メールアドレス、ロケール設定、認証ステータス、および最初にサインアップした日時（signedUpAt）を含むコアプロフィール情報が含まれています。User APIエンドポイントを使用すると、これらすべてにアクセスできます。

Clientsオブジェクト：各ユーザーは、使用するさまざまなチャネルを表す複数の「クライアント」を持つことができます。顧客は、WhatsAppクライアント、SMSクライアント、およびWebチャットクライアントを持っている場合があります。各クライアントは、WhatsAppおよびSMSユーザーの電話番号を含む、チャネル固有のデータを保存します。

会話メタデータ：これは、Webサイトまたはアプリケーションから渡すコンテキストデータです。たとえば、ページURL、注文ID、またはカスタムフィールドなどです。これは会話レベルで保存され、チャット中にアクセスまたは更新できます。

Participants：すべての会話には参加者がおり、このリンクは会話IDを特定のユーザーIDに接続する方法です。

このデータを操作するには、いくつかの前提条件が必要です。Sunshine Conversationsライセンス（Zendesk Suite Professional以上に含まれています）、管理センターで作成されたAPIキー、およびIntegration Builder機能用のAIエージェントAdvancedアドオンです。

ユーザーデータへのAPIアクセスを設定する

ユーザー情報を取得する前に、認証を設定する必要があります。Sunshine Conversationsは、APIアクセスに2つの認証情報システムを使用します。これを一度設定し、すべてのAPI呼び出しで参照する必要があります。

管理センターに移動し、アプリと連携、APIを選択し、Conversations APIをクリックします。このオプションが表示されない場合は、Suite Professional以上であり、エージェントワークスペースが有効になっていることを確認してください。Conversations APIドキュメントに詳細な設定手順が記載されています。

「APIキーを作成」をクリックし、「AIエージェントユーザーデータアクセス」などのわかりやすい名前を付けます。システムは、次の3つの情報を生成します。

• App ID：これはZendeskアカウントを識別し、ほとんどのAPI URLに表示されます
• Key ID：これは基本認証のユーザー名として機能します
• Secret Key：これはパスワードとして機能します。すぐにコピーしてください。一度しか表示されません

Integration BuilderのAPI連携では、Key IDをユーザー名として、Secret Keyをパスワードとして、基本認証を使用します。App IDはAPIエンドポイントURLに埋め込まれます。すべてのAPI呼び出しに3つの認証情報すべてが必要です。

ヒント：開発環境と本番環境で別々のAPIキーを作成します。Integration Builderは複数の環境をサポートしているため、テスト用とライブ使用で異なる認証情報を設定できます。最大10個のキーを保存できるため、ユースケースごとに整理する余地があります。テスト中にライブデータを誤って変更しないように、これを早めに設定することをお勧めします。

ユーザープロファイルデータを取得する

ユーザーデータを取得するには、Sunshine Conversationsがデータモデルを構造化する方法により、2段階のAPIプロセスが必要です。まず、現在の会話に関連付けられているユーザーIDを見つける必要があります。次に、そのユーザーIDを使用して、完全なプロファイルを取得します。

ステップ1：参加者を一覧表示してユーザーIDを取得する

すべての会話には、チャットの開始時に自動的に生成される一意のIDがあります。AIエージェントAdvancedでは、これはplatformConversationIdというシステムパラメータとして利用できます。これを使用して、参加者の一覧表示エンドポイントを呼び出します。

次の設定でIntegration BuilderでAPI連携を作成します。

• メソッドタイプ：GET
• URL：https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/conversations/{{platformConversationId}}/participants

応答には、参加者の配列が含まれています。一般的な顧客の会話の場合、必要なuserIdを含む1つの参加者オブジェクトを取得します。このJSONataクエリを使用して抽出します：data.participants.userId

ステップ2：User APIからユーザーの詳細を取得する

userIdを取得したので、2番目のAPI連携を作成して、完全なユーザープロファイルを取得します。

• メソッドタイプ：GET
• URL：https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/users/{{userId}}

応答には、包括的なユーザーオブジェクトが含まれています。JSONataクエリで抽出できる主要なフィールドを次に示します。

ステップ3：ボットフローでデータを使用する

これらの値をIntegration Builderのセッションパラメータとして保存し、{{givenName}}のように二重中括弧を使用してダイアログで参照します。また、条件付きロジックで使用することもできます。たとえば、{{authenticated}}をチェックして、認証済みユーザーとゲストユーザーで異なるフローを表示します。

うまく機能する1つのパターン：会話が開始されるたびに両方のAPI呼び出しを自動的に実行する「チャット開始」イベントアクションを作成します。これにより、顧客が最初のメッセージを送信する前にユーザーデータが利用可能になり、最初からパーソナライズされたあいさつが可能になります。

チャネル固有のデータにアクセスする（WhatsApp、SMSなど）

ユーザーオブジェクトはプロファイル情報を提供しますが、電話番号などのチャネル固有の詳細についてはどうでしょうか？そこでClients APIが登場します。このエンドポイントは、ユーザーがどのチャネルを介して接続されているかを明らかにし、チャネル固有の識別子を提供します。

Clients APIが重要な理由

顧客がWhatsApp経由で連絡してきた場合、その電話番号はメインのユーザーオブジェクトに保存されません。代わりに、クライアント配列にWhatsAppクライアントレコードの一部として存在します。これは、次のようなユースケースにとって非常に重要です。

• CRMで電話番号で顧客の注文を検索する
• フォローアップSMSメッセージを送信する
• 異なる電話番号でリピーターを識別する
• 電話マッチングを通じてユーザーIDを確認する

クライアントデータを取得する

次のAPIを呼び出すAPI連携を作成します。

• メソッドタイプ：GET
• URL：https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/users/{{userId}}/clients

応答には、クライアントオブジェクトの配列が含まれており、それぞれが異なるチャネル接続を表しています。WhatsAppユーザーの場合、次のようなものが表示されます。

WhatsAppの電話番号を抽出する

このJSONataクエリを使用して電話番号を取得します：data.clients[type="whatsapp"].raw.from

このパターンを他のチャネルに適用できます。SMSユーザーの場合は、タイプフィルターを変更します：data.clients[type="sms"].raw.from

1つの実用的なアプリケーション：この電話番号をセッションパラメータとして保存し、後続のAPI呼び出しでCRMを呼び出して、顧客の注文履歴を検索します。AIエージェントが名前であいさつし、「先週の注文があるようですね」と言うと、その体験は本当に個人的なものに感じられます。

会話メタデータを介してカスタムデータを渡す

Webサイトまたはアプリケーションから会話に情報を渡す必要がある場合があります。顧客がヘルプをクリックしたページのURL、チェックアウトフローからの注文ID、またはサブスクリプションティアなどです。Sunshine Conversationsは、メタデータを介してこれを処理します。

Webウィジェットからデータを渡す

ZendeskのWebウィジェットを使用している場合は、会話の開始時にカスタムデータを添付できます。

このデータは、zen:ticket_field:7662882404114としてフォーマットされたキーを持つ会話メタデータに表示されます。ここで、数値はカスタムフィールドIDです。キー要件：カスタムフィールドはZendeskでエンドユーザーが編集可能である必要があります。

AIエージェントでメタデータを取得する

Integration Builderで、次のCRMアクションを使用したアクションを作成します。

• ターゲット：Sunshine Conversations
• タスク：会話メタデータを取得する
• メタデータオブジェクトを取得し、特定のキーを抽出する

パラメータマッピングを設定するときに、zen:ticket_field:プレフィックスを含む完全なキー名を指定します。ウィジェットから渡された値は、ダイアログのセッションパラメータとして利用できるようになりました。

AIエージェントからメタデータを設定する

会話中にメタデータを更新することもできます。これは、AIエージェントが人間のエージェントにエスカレートされたときにZendeskチケットに表示される情報を収集する場合に役立ちます。

タスクが「会話メタデータを更新」に設定されたアクションを作成します。同じキー形式（zen:ticket_field:FIELD_ID）を使用し、パラメータを値として渡します。会話がエージェントワークスペースにエスカレートされると、そのカスタムフィールドが事前に入力されます。

注意すべき点がいくつかあります。ドロップダウンフィールドの場合は、表示名ではなくタグ値を渡します。ルックアップフィールドの場合は、関連レコードのIDを渡します。件名やステータスなどのシステムフィールドは、この方法では更新できません。カスタムフィールドのみを更新できます。

実用的な実装例

これをいくつかの実際のシナリオで実践してみましょう。

フォールバック付きのパーソナライズされたあいさつ

ユーザーの最初の名前を取得するAPI連携をトリガーするように「チャット開始」イベントを設定します。それを{{givenName}}として保存します。ウェルカムメッセージに、「こんにちは{{givenName}}、今日はどのようなご用件ですか？」と書きます。

しかし、名前がない場合はどうでしょうか？条件付きチェックを追加します。{{givenName}}が空の場合、「こんにちは、今日はどのようなご用件ですか？」というメッセージに分岐します。これにより、あいさつでぎこちない空白が防止されます。

注文履歴のCRMルックアップ

Clients APIを独自のCRM APIと組み合わせます。まず、data.clients[type="whatsapp"].raw.fromを使用してWhatsApp番号を取得します。次に、CRMのルックアップエンドポイントを呼び出す2番目のAPI連携を作成し、その電話番号をパラメータとして渡します。

CRMが注文データを返すと、最近の注文番号やステータスなどの主要な詳細を抽出します。これで、AIエージェントは「昨日からの注文番号＃12345があるようですね。それについてお電話ですか？」と言うことができます。

認証済みユーザーフロー

User APIのauthenticatedフィールドを使用して、さまざまなエクスペリエンスを表示します。認証済みユーザーは、「注文状況を確認する」または「サブスクリプションを更新する」などのアカウント固有のアクションにアクセスできる場合があります。ゲストユーザーには、一般的なヘルプトピックに焦点を当てた、より限定的なメニューが表示されます。

認証ステータスは、セキュリティに敏感なアクションに特に役立ちます。払い戻しまたはアカウントの変更を処理する前に、{{authenticated}}がtrueであり、メールID検証レベルが要件を満たしていることを確認してください。

一般的な問題のトラブルシューティング

適切な設定でも、すべてが完全に機能するとは限りません。最も一般的な問題とその解決方法を次に示します。

ユーザーIDが見つかりません：参加者の一覧表示の呼び出しが空を返す場合は、platformConversationIdが実際に渡されていることを確認してください。Integration Builderテストパネルをチェックして、実行時にどのような値が利用可能かを確認してください。会話が存在しないと、参加者を一覧表示できません。

API認証の失敗：基本認証ヘッダーの形式を再確認してください。Base64エンコードされたKeyID:Secretである必要があります。よくある間違いは、Key IDとApp IDを交換したり、URLパスにApp IDを含めるのを忘れたりすることです。

クライアントデータが見つかりません：すべてのチャネルが同じフィールドでクライアント配列を設定するわけではありません。WhatsAppには通常電話番号が含まれていますが、Webチャットクライアントには含まれていない場合があります。チャネル固有のドキュメントをチェックして、何が利用可能かを確認してください。

メタデータがエージェントワークスペースに表示されない：カスタムフィールドがエンドユーザーが編集可能であることを確認してください。また、正確なキー名形式を確認してください。余分なスペースやバリエーションがないzen:ticket_field:12345である必要があります。フィールドIDは完全に一致する必要があります。

セッションパラメータが空：ダイアログでの操作の順序を確認してください。API連携は、出力パラメータを使用する前に実行する必要があります。後続の呼び出しで1つのAPI呼び出しからのパラメータを使用している場合は、最初の呼び出しが正常に完了していることを確認してください。

レート制限：Sunshine Conversationsには、アカウントごとのレート制限があります。429エラーが発生している場合は、再試行ロジックで指数バックオフを実装するか、ユーザーデータをキャッシュして、同じ会話の繰り返しルックアップを減らしてください。

eesel AIでユーザーデータへのアクセスを簡素化する

これまで説明したことはすべて、開発者のリソースがあり、カスタム連携を構築する時間がある場合にうまく機能します。しかし、すべてのチームがそうではありません。エンジニアリングのオーバーヘッドなしでAIを活用したサポートが必要な場合は、より簡単な方法があります。

当社は、カスタムAPI連携を構築せずに高度なAIエージェント機能を必要とするチームのために、eesel AIを特別に構築しました。Integration Builderワークフローを作成してAPI認証情報を管理する代わりに、シンプルなOAuthフローを通じてeeselをZendeskアカウントに直接接続します。

アプローチの違いは次のとおりです。Sunshine Conversations APIメソッドを使用すると、インフラストラクチャを構築しています。APIキーの作成、JSONataクエリの記述、エラーシナリオの処理、および時間の経過に伴う連携の維持です。当社のアプローチでは、そのインフラストラクチャはすでに構築されています。データ配管を処理しながら、AIの動作の構成に焦点を当てます。

eeselをZendeskに接続すると、個別のAPI呼び出しを構築することなく、ユーザープロファイル、チケット履歴、およびカスタムフィールドに自動的にアクセスします。Integration Builderで複雑な条件付きロジックを構築する代わりに、「顧客が請求の問題について言及した場合は、財務チームに渡す」のように、プレーンな英語でエスカレーションルールを定義します。

独自のチャネル要件または複雑なマルチシステムオーケストレーションを備えた高度にカスタム化されたソリューションを構築している場合は、Sunshine Conversations APIアプローチを使用すると、必要な柔軟性が得られます。ただし、エンジニアリングリソースなしでAIを活用した顧客サポートを迅速に展開することが目標である場合は、当社のZendesk連携が複雑さを処理します。

パーソナライズされたAIエージェントエクスペリエンスの構築を開始する

Zendesk Sunshine Conversationsでユーザーデータにアクセスするための全体像を把握できました。アーキテクチャには、プロファイル情報のUser API、電話番号などのチャネル固有の詳細のClients API、およびアプリケーションからのカスタムコンテキストの会話メタデータの3つの主要なデータソースが含まれています。

実装パターンはユースケース全体で一貫しています。Integration BuilderでAPI連携を作成し、JSONataを使用して必要なフィールドを抽出し、それらをセッションパラメータとして保存し、ダイアログフローでそれらのパラメータを参照します。最初に参加者を取得し、次にユーザーの詳細を取得する2段階のプロセスにより、基本的な名前からWhatsApp電話番号まで、すべてにアクセスできます。

構築を開始する前に、実際に必要なユーザーデータを監査します。利用可能なすべてのフィールドを収集することに夢中になりがちですが、顧客体験を真に向上させるデータに焦点を当ててください。顧客の内部ユーザーIDを表示するよりも、顧客の最初の名前を使用したパーソナライズされたあいさつの方が影響があります。

実装する準備ができていても、開発作業が心配な場合は、Zendeskの設定とともに当社のプラットフォームをお試しください。アプローチを比較して、チームの能力とタイムラインに最適なものを選択できます。