ZendeskカスタムオブジェクトAPI：2026年版完全開発者ガイド

ほとんどのサポートチームはいずれ壁にぶつかります。チケット、ユーザー、組織はカバーしていますが、顧客が使用する機器はどうでしょうか？購入したサブスクリプションプランは？問い合わせている注文は？

Zendeskカスタムオブジェクトは、この問題を解決します。Zendeskのデータモデルを拡張して、ビジネスにとって重要なものを何でも保存し、そのデータをサポートチケットに直接接続できます。

このガイドでは、ZendeskカスタムオブジェクトAPIについて知っておくべきことをすべて説明します。統合を構築する開発者、Zendeskインスタンスを拡張するZendesk管理者、またはソリューションを実装するテクニカルコンサルタントのいずれであっても、すぐに使用できる実践的な例と実際のパターンが見つかります。Zendeskの設定をさらに強化したいチームにとって、eesel AIのZendesk統合は、カスタムデータを使用してサポートワークフローを自動化するのに役立ちます。

Zendeskカスタムオブジェクトとは？

Zendeskには、チケット、ユーザー、組織、記事などの標準オブジェクトがすぐに使用できます。これらは、基本的なサポートシナリオに最適です。しかし、ビジネスはそれよりも複雑です。

カスタムオブジェクトを使用すると、Zendesk内に独自のデータ構造を作成できます。これらを自分で定義するデータベーステーブルと考えてください。オブジェクト（テーブル）を作成し、そのフィールド（列）を定義してから、レコード（行）を追加します。

カスタムオブジェクトを効果的に使用するには、次の4つのコアコンセプトを理解する必要があります。

• カスタムオブジェクト - データのコンテナまたはテンプレート。これは、追跡するもののタイプを定義します。
• カスタムオブジェクトフィールド - 各オブジェクトが持つプロパティを定義するスキーマ。フィールドがない場合、オブジェクトは単なる空のシェルです。
• ルックアップリレーションシップフィールド - カスタムオブジェクトと標準のZendeskオブジェクト（またはその他のカスタムオブジェクト）間の接続を作成する特別なフィールド。
• カスタムオブジェクトレコード - カスタムデータの個々のインスタンス。オブジェクトが「ソフトウェア」の場合、各レコードは特定のソフトウェアです。

一般的なユースケースには、ハードウェア資産（ラップトップ、プリンター）の追跡、ソフトウェアライセンスの管理、eコマースの注文とサポートチケットのリンク、またはサブスクリプションデータの保存が含まれます。サポートのやり取り中にビジネス固有のデータを参照する必要があるシナリオはすべて、カスタムオブジェクトの候補です。Zendesk開発者ドキュメントには、これらのユースケースの実装に関する詳細なチュートリアルが用意されています。

新しいAPIとレガシーAPI：知っておくべきこと

ここで、多くの開発者をつまずかせる重要なことがあります。Zendeskには完全に分離された2つのカスタムオブジェクトAPIがあります。これらは互換性がありません。一方のAPIで作成されたデータは、もう一方のAPIではアクセスできません。

新しいカスタムオブジェクトAPI

最新のAPIは、エンドポイント/api/v2/custom_objectsを使用し、Zendeskエージェントワークスペースと深く統合されています。レコードはインターフェイスにネイティブに表示され、ルックアップフィールドはチケットフォームで機能し、全体的なエクスペリエンスはネイティブのZendesk機能のように感じられます。カスタムオブジェクトの開始方法の詳細については、公式ドキュメントをご覧ください。

これは、すべての新しいプロジェクトで使用する必要があるAPIです。

レガシーカスタムオブジェクトAPI

古いAPIは/api/sunshine/を使用しており、Zendeskが最初にカスタムデータを試みたものです。動作はしますが、統合されているというよりは、後付けのように感じられます。レガシーカスタムオブジェクトAPIドキュメントは、これを「レガシーカスタムオブジェクトAPI」と呼び、主に既存の実装のために維持されています。

古い統合を維持している場合は、このAPIが必要になる場合があります。それ以外の場合は、新しいAPIを使用してください。

どちらを使用する必要がありますか？

レガシーAPIを使用する特定の理由（既存のコードの維持など）がない限り、常に新しいカスタムオブジェクトAPIを選択してください。ドキュメントが充実しており、統合が優れており、Zendeskが将来の開発に力を入れている場所です。

はじめに：前提条件と設定

API呼び出しを開始する前に、いくつかの準備が必要です。

必要なZendeskプラン

カスタムオブジェクトは、すべてのプランで利用できるわけではありません。Zendeskのプランに関するドキュメントによると、次のいずれかが必要です。

• Support Enterprise
• すべてのZendesk Suiteプラン（Team、Growth、Professional、Enterprise、またはEnterprise Plus）

プランのティアは、作成できるカスタムオブジェクトの数に影響するため、このガイドの後半の制限事項のセクションを確認してください。

管理センターでカスタムオブジェクトを有効にする

管理者として、機能を使用する前にアクティブ化する必要があります。

1. 管理センターに移動します。
2. サイドバーのオブジェクトとルールをクリックします。
3. カスタムオブジェクト > オブジェクトを選択します。
4. 開始するをクリックします。

アカウントで以前にレガシーカスタムオブジェクトを使用していた場合は、新しいエクスペリエンスを試すことができるバナーが表示されます。試してみるをクリックして、最新のAPIを有効にします。

APIトークンを作成する

すべてのAPIリクエストは、APIトークンを使用したベーシック認証を使用します。Zendesk APIドキュメントでは、次の方法で作成する方法について説明しています。

1. 管理センターで、アプリと統合 > API > Zendesk APIに移動します。
2. 設定タブをクリックします。
3. トークンアクセスがまだオンになっていない場合は、有効にします。
4. **+**ボタンをクリックして、新しいトークンを追加します。
5. 「カスタムオブジェクト統合」などのわかりやすい名前を付けます。
6. トークンをすぐにコピーします（Zendeskは再度表示しません）。

認証形式

すべてのAPIリクエストには、メールとトークンを含むAuthorizationヘッダーが必要です。

Authorization: Basic {base64({email_address}/token:{api_token})}

たとえば、メールがadmin@company.comで、トークンがabc123xyzの場合、admin@company.com/token:abc123xyzをBase64でエンコードし、それをヘッダーに含めます。

カスタムオブジェクトAPIの操作

次に、最も頻繁に使用するコア操作について説明します。

カスタムオブジェクトの作成

カスタムオブジェクトを作成するには、次の3つの必須フィールドを含むPOSTリクエストを/api/v2/custom_objectsに送信します。

• key - オブジェクトの一意の識別子（後で変更することはできません）
• title - 単数形の表示名（例：「ソフトウェア」）
• title_pluralized - 複数形の表示名（例：「ソフトウェア」）

cURLの例を次に示します。

curl --request POST https://{subdomain}.zendesk.com/api/v2/custom_objects \
  --header "Content-Type: application/json" \
  -u {email_address}/token:{api_token} \
  --data-raw '{
    "custom_object": {
      "key": "software",
      "title": "Software",
      "title_pluralized": "Software"
    }
  }'

オプションのフィールドは次のとおりです。

• description - このオブジェクトが表すもの
• allows_attachments - レコードにファイル添付ファイルを含めることができるかどうか
• include_in_list_view - エージェントがカスタムオブジェクトレコードページでこのオブジェクトを表示するかどうか

カスタムオブジェクトフィールドの定義

フィールドのないオブジェクトは、単なる空のコンテナです。カスタムオブジェクトフィールドAPIを使用してスキーマを定義します。カスタムオブジェクトの作成に関する公式ドキュメントには、フィールド構成に関する追加のガイダンスが記載されています。

curl --request POST https://{subdomain}.zendesk.com/api/v2/custom_objects/software/fields \
  --header "Content-Type: application/json" \
  -u {email_address}/token:{api_token} \
  --data-raw '{
    "custom_object_field": {
      "key": "version",
      "title": "Version",
      "type": "text"
    }
  }'

使用可能なフィールドタイプには、テキスト、テキストエリア、チェックボックス、日付、整数、10進数、正規表現、ドロップダウン、複数選択、およびルックアップがあります。各フィールドタイプの詳細については、カスタムオブジェクトフィールドAPIリファレンスを参照してください。

ルックアップフィールドは特に強力です。オブジェクト間の関係を作成します。ソフトウェアオブジェクトをチケットにリンクするには、チケットにソフトウェアを指すルックアップフィールドを作成します。

curl https://{subdomain}.zendesk.com/api/v2/ticket_fields.json \
  -H "Content-Type: application/json" -X POST \
  -u {email_address}/token:{api_token} \
  --data-raw '{
    "ticket_field": {
      "type": "lookup",
      "title": "Affected Software",
      "relationship_target_type": "zen:custom_object:software"
    }
  }'

カスタムオブジェクトレコードの管理

オブジェクトとフィールドを設定したら、レコードを作成できます。

import requests
from requests.auth import HTTPBasicAuth

url = "https://{subdomain}.zendesk.com/api/v2/custom_objects/software/records"
payload = {
    "custom_object_record": {
        "name": "Zendesk Support",
        "custom_object_fields": {
            "version": "2024.1",
            "license_type": "Enterprise"
        }
    }
}
headers = {"Content-Type": "application/json"}
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request("POST", url, auth=auth, headers=headers, json=payload)

APIは、レコードを一覧表示するためのカーソルベースのページネーションをサポートしています。これは、大規模なデータセットの場合、オフセットページネーションよりも効率的です。page[after]およびpage[size]パラメーターを使用して、結果をナビゲートします。ページネーションの詳細については、カスタムオブジェクトレコードAPIリファレンスを参照してください。

プランの制限とベストプラクティス

制限事項を理解することで、最初から制約内で設計できます。

プランごとのカスタムオブジェクトの制限

その他の重要な制限

• カスタムオブジェクトあたり最大100フィールド（標準フィールドはカウントされません）
• レコードあたり最大32KB
• アカウントあたり最大5000万レコード
• API経由で一覧表示する場合1ページあたり100レコード

データモデリングのベストプラクティス

構築を開始する前に、オブジェクトの関係を計画してください。後でキーまたは基本的な構造を変更するには、オブジェクトを再作成してデータを移行する必要があります。

外部システムと同期する場合は、レコードにexternal_idフィールドを使用します。これにより、Zendeskの内部IDではなく、独自の識別子でレコードを参照できます。

パフォーマンスを向上させるには、大規模なレコードセットを反復処理するときに、カーソルベースのページネーションを使用します。オフセットページネーションは、結果の奥深くまでページングするにつれて遅くなります。最適化のヒントについては、Zendesk APIページネーションドキュメントを確認してください。

カスタムオブジェクトをワークフローに統合する

カスタムオブジェクトの真の力は、Zendeskの他の部分とどのように統合されるかから生まれます。

チケットフォームとエージェントワークスペース

チケットフォームにルックアップフィールドを追加すると、エージェントはチケットを表示しながらカスタムオブジェクトレコードを直接検索して選択できます。選択したレコードのデータがチケットのサイドバーに表示され、エージェントはコンテキストを切り替えることなく完全なコンテキストを得ることができます。設定手順については、Zendeskのカスタムオブジェクトの開始に関するガイドをご覧ください。

Zendesk Apps Framework

エージェントワークスペースにカスタムオブジェクトデータを表示するサイドバーアプリを構築できます。これは、計算されたデータ、外部システムからの関連レコード、またはルックアップフィールドが提供する以上のカスタム視覚化を表示する必要がある場合に役立ちます。

トリガーと自動化

カスタムオブジェクトはZendeskトリガーと連携し、カスタムデータに基づいて自動化できます。たとえば、期限切れのライセンスに関するチケットを自動的に更新チームにルーティングしたり、カスタムオブジェクトのデータに基づいてVIP顧客に影響を与える問題をエスカレートしたりできます。

外部システム統合

APIを使用すると、外部システムとの双方向同期が可能になります。eコマースプラットフォームから製品カタログデータを同期したり、IT資産管理システムから資産情報を取得したり、サポートインサイトをCRMにプッシュバックしたりできます。

Zendeskカスタムデータでeesel AIを使用する

カスタムオブジェクトにビジネスデータを保存したら、その情報をサポート業務に活用できます。eesel AIでは、カスタムオブジェクトを含むZendeskデータとシームレスに連携するようにプラットフォームを構築しました。

当社のAIエージェントは、チケットに応答するときにカスタムオブジェクトレコードを参照できます。顧客がソフトウェアライセンスについて質問した場合、AIはライセンスレコードを検索し、有効期限を確認し、人的介入なしに正確な情報を提供できます。

また、カスタムオブジェクトのリレーションシップを使用して、インタラクションをパーソナライズします。AIが顧客が使用する製品を（カスタムオブジェクトから）認識している場合、関連するコンテキストで応答を調整し、適切なソリューションを提案できます。

ビジネスデータをモデル化するためにカスタムオブジェクトに投資する場合は、AIがその投資をどのように活用できるかを検討してください。構造化されたカスタムデータとインテリジェントな自動化の組み合わせにより、一般的なものではなく、本当に役立つと感じられるサポートエクスペリエンスが生まれます。eesel AIを無料で試して、Zendeskの設定でどのように機能するかを確認できます。

今すぐZendeskカスタムオブジェクトで構築を開始する

ZendeskカスタムオブジェクトAPIを使用すると、独自のビジネスデータをモデル化し、それをサポートワークフローに直接統合するためのツールが提供されます。コアコンセプト、APIバージョンの違い、認証方法、オブジェクトの作成、フィールドの定義、レコードの管理に関する主要な操作について学びました。

次のステップは、目標によって異なります。統合を構築する場合は、小さな概念実証から始めます。おそらく、いくつかのフィールドを持つ1つのカスタムオブジェクトです。CRUD操作をテストしてから、リレーションシップと外部システム接続に拡張します。

Zendesk管理者の方は、チームと協力して、どのビジネスデータがサポートのやり取りを最も改善するかを特定します。最適なカスタムオブジェクトの実装は、エージェントが日常的に直面する実際の問題を解決します。

また、Zendeskへの投資からより多くの価値を得たい場合は、AIがカスタムデータを活用して、よりスマートでパーソナライズされたサポートを実現する方法を検討してください。構造化されたデータとインテリジェントな自動化の組み合わせは、最新のサポートが進む方向です。デモを予約して、eesel AIがZendeskカスタムオブジェクトとどのように連携するかをご覧ください。