2026年にZendesk APIを使用してチケットを更新する方法

ワークフローを自動化したり、他のシステムと統合したり、カスタムツールを構築したりすることを検討しているチームにとって、プログラムによるサポートチケットの管理は不可欠です。Zendesk Ticketing APIを使用すると、単純なステータスの変更から、カスタムフィールドを含む複雑な一括操作まで、チケットの更新を完全に制御できます。

このガイドでは、API経由でチケットの更新を開始するために必要なすべての手順を、独自のプロジェクトに適用できる動作するコード例とともに説明します。

開始するために必要なもの

最初のAPI呼び出しを行う前に、次のものが揃っていることを確認してください。

• 管理者またはエージェントアクセス権を持つZendesk Supportアカウント。APIトークンを生成し、チケットデータを表示するためのアクセス許可が必要です。
• APIトークン認証が有効になっていること。トークンアクセスは、管理センターのアプリと連携機能 > API > APIトークンで有効にする必要があります。
• REST APIの基本的な知識。HTTPメソッド（GET、PUT、POST）およびJSONデータ形式を理解している必要があります。
• お好みのツール。このガイドには、Requestsライブラリを使用したcURLおよびPythonの例が含まれていますが、Postman、JavaScript、または任意のHTTPクライアントを使用できます。

Zendesk APIを使い始めたばかりの場合は、最初にAPIクイックスタートガイドを確認することをお勧めします。リクエストの作成とレスポンスの処理の基本について説明しています。

API認証の設定

Zendeskは、APIアクセスにトークンベースの認証を使用します。設定方法は次のとおりです。

APIトークンの生成

1. 管理者としてZendeskアカウントにサインインします。
2. 管理センター > アプリと連携機能 > API > APIトークンに移動します。
3. プラスアイコンをクリックして、新しいトークンを追加します。
4. 「チケット更新スクリプト」のようなわかりやすい名前を付けます。
5. トークンをすぐにコピーします。Zendeskは一度しか表示しません。

認証形式

Zendeskは、次の形式で資格情報を想定しています。

{email_address}/token:{api_token}

たとえば、メールアドレスがadmin@company.comで、トークンがabc123xyzの場合、認証文字列は次のようになります。

admin@company.com/token:abc123xyz

資格情報の安全な保存

スクリプトにAPIトークンをハードコードしないでください。代わりに、環境変数を使用します。

export ZENDESK_SUBDOMAIN="yourcompany"
export ZENDESK_EMAIL="admin@company.com"
export ZENDESK_TOKEN="your_api_token_here"

次に、Pythonでアクセスします。

import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

auth = (f"{email}/token", token)

認証のテスト

すべてが機能することを確認するために、簡単なGETリクエストを作成します。

curl "https://yourcompany.zendesk.com/api/v2/tickets.json?per_page=1" \
  -u "admin@company.com/token:your_api_token"

チケットデータを含むJSONレスポンスを受信した場合、認証されており、続行する準備ができています。401エラーが発生した場合は、トークンとメールアドレスを再確認してください。

単一のチケットの更新

チケットを更新するためのエンドポイントは簡単です。

PUT /api/v2/tickets/{ticket_id}.json

cURLを使用した基本的な更新

チケットのステータスを更新し、コメントを追加する方法を次に示します。

curl "https://yourcompany.zendesk.com/api/v2/tickets/12345.json" \
  -X PUT \
  -u "admin@company.com/token:your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": {
      "status": "solved",
      "comment": {
        "body": "この問題は解決されました。修正は現在公開されています。",
        "public": true
      }
    }
  }'

Pythonの実装

Requestsライブラリを使用すると、同じ操作は次のようになります。

import requests
import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

url = f"https://{subdomain}.zendesk.com/api/v2/tickets/12345.json"
auth = (f"{email}/token", token)

data = {
    "ticket": {
        "status": "solved",
        "priority": "normal",
        "assignee_id": 987654321,
        "comment": {
            "body": "この問題は解決されました。修正は現在公開されています。",
            "public": True
        }
    }
}

response = requests.put(url, json=data, auth=auth)

if response.status_code == 200:
    print("チケットは正常に更新されました")
    updated_ticket = response.json()['ticket']
    print(f"新しいステータス: {updated_ticket['status']}")
else:
    print(f"エラー: {response.status_code}")
    print(response.text)

更新できる一般的なフィールド

commentフィールドを更新するときに、"public": trueを設定すると、リクエスタに表示される公開返信になります。これを省略するか、falseに設定すると、内部メモが作成されます。

カスタムフィールドの操作

カスタムフィールドは、製品カテゴリ、顧客層、または問題の種類などの特定のデータを追跡するために、Zendeskの設定で一般的です。API経由で更新するには、フィールドIDを知っている必要があります。

カスタムフィールドIDの検索

カスタムフィールドIDは、次の2つの方法で見つけることができます。

1. 管理センター: オブジェクトとルール > チケット > カスタムフィールドに移動します。フィールドを編集すると、URLにIDが表示されます。
2. API: GET /api/v2/ticket_fields.jsonを使用して、すべてのカスタムフィールドを一覧表示します。

カスタムフィールドの更新

カスタムフィールドは、APIで特定の形式を使用します。idおよびvalueプロパティを持つオブジェクトの配列を提供します。

{
  "ticket": {
    "custom_fields": [
      {"id": 25356371, "value": "enterprise"},
      {"id": 25356372, "value": 42},
      {"id": 25356373, "value": "billing_issue"}
    ]
  }
}

完全なPythonの例を次に示します。

import requests
import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

url = f"https://{subdomain}.zendesk.com/api/v2/tickets/12345.json"
auth = (f"{email}/token", token)

data = {
    "ticket": {
        "custom_fields": [
            {"id": 360012345678, "value": "premium"},      # ドロップダウン
            {"id": 360012345679, "value": "2026-03-15"},  # 日付
            {"id": 360012345680, "value": 1500.00},        # 10進数
            {"id": 360012345681, "value": True}            # チェックボックス
        ],
        "comment": {
            "body": "顧客層と更新日を更新しました。",
            "public": False
        }
    }
}

response = requests.put(url, json=data, auth=auth)

if response.status_code == 200:
    print("カスタムフィールドは正常に更新されました")
else:
    print(f"エラー {response.status_code}: {response.text}")

カスタムフィールドに関する一般的な落とし穴

• 間違ったデータ型: フィールドが数値を想定している場合に文字列を送信すると、422エラーが返されます。
• 無効なオプション値: ドロップダウンフィールドは、事前定義された値のみを受け入れます。更新が失敗する場合は、フィールド構成を確認してください。
• フィールドのアクセス許可: 一部のカスタムフィールドは読み取り専用であるか、特定のロールのみが編集できます。

複数のチケットの一括更新

数十または数百のチケットを更新する必要がある場合、個々のAPI呼び出しは非効率的です。Zendeskは、このシナリオに対応するための一括更新エンドポイントを提供します。

一括更新エンドポイント

PUT /api/v2/tickets/update_many.json?ids=1,2,3,4,5

IDでチケットを指定するか、検索クエリを使用できます。

PUT /api/v2/tickets/update_many.json?query=status:open+priority:high

一括更新を使用する場合

一括更新は、次のような場合に役立ちます。

• 退職するエージェントからのすべてのチケットを再割り当てする
• 30日以上前の解決済みのチケットをクローズする
• チケットのカテゴリ全体でカスタムフィールド値を更新する
• 特定の条件に一致するチケットにタグを追加する

レート制限に関する考慮事項

Zendeskは、プランによって異なるレート制限を適用します。Teamプランは1分あたり200リクエスト、GrowthおよびProfessionalプランは400、Enterpriseプランは700です。一括更新は、影響を与えるチケットの数に関係なく、単一のリクエストとしてカウントされるため、個々の呼び出しよりもはるかに効率的です。

大規模な更新のベストプラクティス

1. 最初に小さなバッチでテストする。数百件を処理する前に、5〜10件のチケットで更新を実行して、ロジックを確認します。
2. 検索クエリを慎重に使用する。不適切に作成されたクエリは、意図せずに数千件のチケットに一致する可能性があります。
3. ページネーションを処理する。検索で多数の結果が返される場合は、バッチで処理します。
4. 変更をログに記録する。どのチケットがいつ更新されたかの記録を保持します。

特定の担当者に割り当てられたすべてのオープンチケットを更新する例を次に示します。

import requests
import os
import time

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

auth = (f"{email}/token", token)
base_url = f"https://{subdomain}.zendesk.com/api/v2"

search_url = f"{base_url}/search.json?query=assignee:987654321+status:open"
response = requests.get(search_url, auth=auth)
results = response.json()

ticket_ids = [str(ticket['id']) for ticket in results['results']]

for i in range(0, len(ticket_ids), 100):
    batch = ticket_ids[i:i+100]
    ids_param = ','.join(batch)

    update_url = f"{base_url}/tickets/update_many.json?ids={ids_param}"
    data = {
        "ticket": {
            "assignee_id": 123456789,  # 新しい担当者
            "comment": {
                "body": "新しいチームメンバーに再割り当てされました。",
                "public": False
            }
        }
    }

    response = requests.put(update_url, json=data, auth=auth)

    if response.status_code == 200:
        print(f"バッチ {i//100 + 1} を更新しました: {len(batch)} 件のチケット")
    else:
        print(f"バッチ {i//100 + 1} でエラーが発生しました: {response.text}")

    # APIに優しくする
    time.sleep(1)

エラー処理とトラブルシューティング

慎重に計画しても、API呼び出しが失敗することがあります。エラーレスポンスの解釈方法を知っておくと、デバッグ時間を節約できます。

一般的なHTTPエラーコード

検証エラーの処理

422エラーは通常、データがZendeskが想定しているものと一致しないことを意味します。レスポンス本文には詳細が含まれています。

{
  "error": "RecordInvalid",
  "description": "レコード検証エラー",
  "details": {
    "custom_fields": [
      {
        "description": "フィールド値を空白にすることはできません",
        "error": "BlankValue"
      }
    ]
  }
}

デバッグのヒント

1. HTTPクライアントで詳細ロギングを有効にするして、完全なリクエストとレスポンスの詳細を表示します。
2. 管理センターでZendesk APIログを確認するして、失敗したリクエストを確認します。
3. 送信する前にJSONを検証する。末尾のカンマまたは引用符の欠落はエラーの原因になります。
4. 構文の問題を分離するために、コードを記述する前にPostmanまたはcURLでテストする。

Zendeskサポートに連絡する場合

ほとんどのAPIの問題は、ドキュメントを確認し、リクエスト形式を確認することで解決できます。Zendeskサポートには、次の問題が発生した場合に連絡してください。

• 一貫した500エラー（サーバー側の問題）
• ドキュメントに記載されている制限を下回っているにもかかわらず、予期しないレート制限が発生する
• 公式APIドキュメントと矛盾する動作

eesel AIによるチケット更新の合理化

API連携を構築および維持するには、時間とエンジニアリングリソースが必要です。コードを記述せずに自動化されたチケット管理を必要とするチームのために、eesel AIは異なるアプローチを提供します。

チームが手動スクリプトよりも自動化を選択する理由

カスタムAPIスクリプトは、特定の1回限りのタスクには適しています。ただし、次のような場合は負担になります。

• 変化する条件に基づいてチケットを継続的に更新する必要がある
• ワークフローの進化に合わせて連携機能を維持する
• チームメンバーにコードの使用方法と変更方法をトレーニングする
• 複数のチケットタイプとチャネルにわたって自動化を拡張する

eesel AIがZendeskに接続する方法

API呼び出しを記述する代わりに、eesel AIをAIエージェントとしてチームに招待します。過去のチケット、ヘルプセンターの記事、およびマクロから学習し、ルーチン更新を自動的に処理します。

実際には次のようになります。

• 自動タグ付け: eeselは受信チケットを読み取り、コンテンツに基づいて関連するタグを適用します。
• インテリジェントルーティング: チケットは手動トリアージなしで、適切なチームまたはエージェントに割り当てられます。
• ステータス更新: eeselは、特定の条件が満たされたときにチケットステータスを変更できます。
• エスカレーション処理: 複雑な問題は、コンテキストとともに人間のエージェントに自動的にエスカレーションされます。

自動化されたチケット管理のユースケース

チームは、eesel AIのZendesk連携機能を、複雑なAPIスクリプトを必要とするシナリオで使用します。

• VIP顧客のチケットをすぐに上級エージェントにルーティングする
• スパムまたは「ありがとう」メッセージを自動的にクローズする
• チケットコンテンツ分析に基づいてカスタムフィールドを更新する
• 同じ顧客からの重複チケットをマージする

eesel AIの開始方法

チームが自動化から得られるメリットよりもAPIスクリプトの維持に多くの時間を費やしている場合、eesel AIの料金はノーコードの代替手段を提供します。プランは年間請求で月額239ドルから始まり、ワークフローへの適合性をテストするための7日間の無料トライアルが付いています。

違いはアプローチにあります。チケットを更新するコードを記述するのではなく、何が必要かをわかりやすい英語で説明します。eeselはビジネスを学習し、ガイダンスから始めて、自らを証明するにつれて自律的に動作するようにレベルアップします。