Zendeskチケットのサイドバーアプリを構築する方法：開発者向け完全ガイド

サポートエージェントが複雑なチケットに対応している場面を想像してみてください。顧客の注文履歴を確認し、CRM（顧客関係管理）レコードを調べ、ナレッジベースを検索する必要があります。Zendeskを離れることなく。まさにそれがチケットサイドバーアプリの役割です。外部データとツールをエージェントのワークスペースに直接取り込み、時間を節約し、コンテキストの切り替えを減らします。

チケットサイドバーは、Zendeskアプリにとって最も強力なロケーションの1つです。すべてのチケットの右側にあるアプリトレーに配置され、エージェントはコンテキスト情報に即座にアクセスできます。チーム向けの統合を構築する場合でも、Zendesk Marketplaceで公開する予定の場合でも、このガイドでは、チケットサイドバーアプリを最初から作成する方法を説明します。

必要なもの

構築を開始する前に、次の前提条件が整っていることを確認してください。

• Suite Growthプラン以上、またはSupport Professionalプラン以上のZendeskアカウント。必要に応じて、開発用の無料トライアルアカウントを取得できます。
• Node.js 14.17.3以降がマシンにインストールされていること
• アプリをローカルで構築およびテストするためのZendesk Command Line Interface（ZCLI）
• ChromeやFirefoxなど、HTTPとHTTPSの混合コンテンツを許可するWebブラウザ。Safariは混合コンテンツをサポートしていないため、ローカル開発では機能しません。
• HTML、CSS、およびJavaScriptの基本的な知識

ステップ1：開発環境をセットアップする

まず、ZCLIをインストールし、アプリの構造を作成する必要があります。ZCLIは、新しいアプリのスカフォールディングから、デプロイメント用にパッケージ化するまですべてを処理するZendeskの公式コマンドラインツールです。

ZCLIをグローバルにインストールするには、次を実行します。

npm install -g @zendesk/zcli

インストールしたら、次を実行して新しいアプリを作成します。

zcli apps:new

いくつかの詳細を入力するように求められます。

• ディレクトリ名: アプリファイルのフォルダを作成します
• 作成者の名前とメールアドレス: アプリマニフェスト用
• アプリ名: アプリの表示名

ZCLIは、必要なファイルを含むスターターテンプレートを生成します。

• manifest.json: ロケーションを含むアプリの構成を定義します
• assets/iframe.html: サイドバーに表示されるHTMLコンテンツ
• assets/logo.png: アプリのアイコン
• translations/en.json: 国際化用

ステップ2：チケットサイドバーのロケーションを構成する

アプリ構成の中心はmanifest.jsonにあります。このファイルは、アプリを表示する場所とロードするコンテンツをZendeskに指示します。

チケットサイドバーアプリの場合、マニフェストにはticket_sidebarキーを指定するlocationプロパティが必要です。

{
  "name": "My Sidebar App",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "defaultLocale": "en",
  "private": true,
  "location": {
    "support": {
      "ticket_sidebar": {
        "url": "assets/iframe.html",
        "flexible": true
      }
    }
  },
  "version": "1.0.0"
}

主要なプロパティを見てみましょう。

• url: サイドバーのiframeにロードされるHTMLファイルを指します。これは、アプリのUIが存在する場所です。
• flexible: iframeがアプリトレーのサイズに合わせてサイズ変更されるかどうかを制御します。レスポンシブな動作の場合はtrueに設定し、幅を320pxでロックする場合はfalseに設定します。

エージェントが新しいチケットを作成しているときに表示されるアプリ用のnew_ticket_sidebarロケーションもあります。チケットが作成されると、標準のticket_sidebarロケーションに移動します。

ステップ3：ZAF APIでチケットデータにアクセスする

ここからが面白い部分です。アプリを実際に機能させます。Zendesk Apps Framework（ZAF）は、アプリがチケットデータ、ユーザー情報、およびZendeskインターフェイスと対話できるようにするJavaScript SDKを提供します。

まず、ZAF SDKをiframe.htmlに含めます。

<script src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js"></script>

次に、クライアントを初期化し、データのフェッチを開始します。

var client = ZAFClient.init();

// Get the current ticket's subject and status
client.get('ticket.subject').then(function(data) {
  console.log('Ticket subject:', data['ticket.subject']);
});

// Fetch multiple properties at once
client.get(['ticket.subject', 'ticket.status', 'ticket.priority']).then(function(data) {
  console.log('Ticket info:', data);
});

チケットサイドバーのロケーションを使用すると、豊富なデータオブジェクトにアクセスできます。

• チケットオブジェクト: ステータス、優先度、件名、説明、カスタムフィールド、タグ
• ユーザーオブジェクト: リクエスターの詳細、現在のユーザー、コラボレーター
• コメントオブジェクト: チケットのコメントと添付ファイル
• ブランドおよび組織データ: アカウントに関するコンテキスト

リアルタイムの変更をリッスンすることもできます。エージェントがチケットのステータスまたは担当者を更新すると、アプリはすぐに応答できます。

client.on('ticket.status.changed', function() {
  console.log('Ticket status was updated');
  // Refresh your app's data or UI
});

ステップ4：レスポンシブなレイアウトを設計する

ここで、多くの開発者が見落としていることがあります。チケットサイドバーの幅は固定されなくなりました。Agent Workspaceを使用すると、エージェントはアプリトレーのサイズを200pxから事実上無制限の幅まで変更できます。アプリはこれを適切に処理する必要があります。

マニフェストでflexible: trueを設定すると、iframeは自動的にサイズ変更されます。ただし、CSSも応答する必要があります。Tailwind CSSのようなレスポンシブフレームワークを使用するか、レイアウトを調整するメディアクエリを作成することを検討してください。

/* Default styles for narrow sidebar */
.app-container {
  padding: 12px;
  font-size: 14px;
}

/* Wider sidebar - show more details */
@media (min-width: 400px) {
  .app-container {
    padding: 16px;
  }
  .detail-view {
    display: block;
  }
}

エージェントの焦点について考えてください。サイドバーが狭い場合、会話に集中している可能性があります。必要な情報のみを表示します。トレーを展開すると、アプリでタスクを完了しようとしている可能性があります。そのときに、より多くの機能を明らかにすることができます。

ステップ5：アプリをテストしてデプロイする

アプリが構築されたので、デプロイする前にローカルでテストする時が来ました。ZCLIには、実際のZendesk環境でアプリを実行できるローカルサーバーが含まれています。

開発サーバーを起動します。

zcli apps:server

これにより、アプリのローカルWebサーバーが起動します。実際に動作しているのを確認するには：

1. シークレットまたはプライベートブラウザウィンドウを開きます（これにより、キャッシュの問題を防ぎます）
2. Zendeskにサインインして、任意のチケットを開きます
3. URLに?zcli_apps=trueを追加します
4. アプリがアプリトレーに表示されます

コードを変更し、保存して、ページを更新すると、更新がすぐに表示されます。

デプロイする準備ができたら、アプリをパッケージ化します。

zcli apps:package

これにより、プライベートで使用するためにZendeskインスタンスに直接アップロードできるZIPファイルが作成されるか、他の組織と共有する場合はZendesk Marketplaceに送信できます。

チケットサイドバーアプリの一般的なユースケース

メカニズムを理解したので、何を構築する必要がありますか？チケットサイドバーでうまく機能するパターンを次に示します。

• 顧客データルックアップ: Shopifyから注文履歴、Salesforceからアカウントの詳細、または請求システムからサブスクリプションステータスを取得します。エージェントはタブを切り替えることなくすべてを確認できます。
• クロスプラットフォームワークフロー: Jiraの課題を作成したり、Trelloカードを追加したり、GitHubでチケットから直接バグを記録したりします。アプリはZendeskチケットからデータを事前に入力して、時間を節約します。
• 知識支援: ヘルプセンター、内部wiki、または過去のチケットを検索して、関連する解決策を見つけます。一部のアプリはAIを使用して、チケットコンテンツに基づいて応答を提案します。
• AI搭載サポート: eesel AIのようなツールはサイドバーで動作し、応答を起草し、複数のソースから関連する知識を表面化し、エージェントがチケットをより迅速に解決するのに役立ちます。

重要なのはコンテキストです。最適なサイドバーアプリは、エージェントが表示している特定のチケットと顧客に関連する情報を自動的に表示します。

ヒントとベストプラクティス

アプリを完成させる前に、次のガイドラインに留意してください。

• 軽量に保つ: サイドバーアプリはすべてのチケットでロードされます。重いJavaScriptライブラリまたは大きなアセットは、エージェントのエクスペリエンスを低下させます。
• エラーを適切に処理する: 外部APIは失敗します。ネットワーク接続が切断されます。アプリがエージェントのワークフローを中断するのではなく、サイレントに失敗するようにエラー処理を組み込みます。
• Zendesk Gardenを使用する: Zendeskのデザインシステムは、ネイティブインターフェイスに一致するコンポーネントを提供します。これにより、アプリは外部要素ではなく、Zendeskの一部のように感じられます。
• APIキーを保護する: アプリに資格情報をハードコードしないでください。認証には、Zendeskの安全な設定またはOAuthを使用します。
• 実際のデータでテストする: テストチケットで完全に機能するアプリは、異常な文字、長い件名、または欠落しているカスタムフィールドで苦労する可能性があります。

今すぐZendeskサイドバーアプリの構築を開始する

チケットサイドバーアプリを構築するために必要なものがすべて揃いました。ZCLIを使用した開発環境のセットアップから、マニフェストの構成、ZAFを介したチケットデータへのアクセス、レスポンシブレイアウトの設計まで、基盤が整っています。

チケットサイドバーは、Zendeskの機能を拡張する強力な方法です。チームの特定のワークフローを解決する場合でも、より広範なZendeskコミュニティのために何かを構築する場合でも、このロケーションのアプリは、エージェントが必要とする場所に情報とアクションを正確に配置します。

Zendeskの設定にAI機能を追加したい場合は、eesel AIがサイドバーアプリとして機能し、ヘルプセンター、過去のチケット、および内部ドキュメントからの知識をエージェントワークスペースに直接取り込みます。Zendesk Apps Frameworkと最新のAI機能を組み合わせると何が可能かの良い例です。

始める準備はできましたか？Zendeskの資格情報を取得し、ZCLIをインストールして、サポートチームの1日を少し楽にするものを構築してください。