Zendesk Requests API：エンドユーザー向け完全ガイド（2026年）

カスタマーポータルやセルフサービス連携を構築する場合、エンドユーザーに完全な管理者アクセス権を与えることなく、チケットを作成および表示する方法が必要です。Zendesk Requests APIは、まさにこの目的のために設計されています。

Requests APIは、チケットに対するエンドユーザーの視点を提供します。ユーザーは、リクエストの作成、チケット履歴の表示、コメントの追加を、すべて公開情報のみを見ながら行うことができます。これは、完全なTickets APIに対する安全でアクセス制限された代替手段です。

カスタムAPI統合を構築せずにサポートを自動化したい場合は、eesel AIなどのツールが、チケットルーティングからAIを活用した応答まで、サポート自動化の全範囲を処理できます。eeselはZendeskと直接統合し、既存のチケットとドキュメントから学習します。ただし、カスタム統合のために直接APIアクセスが必要な場合は、このガイドですべて必要なことを説明します。

必要なもの

API呼び出しを開始する前に、次のものが揃っていることを確認してください。

• 適切な権限を持つZendeskアカウント（APIトークンを設定するための管理者アクセス権）
• APIトークンまたはOAuth認証情報（これらを生成する方法について説明します）
• REST APIに関する基本的な知識（GET、POST、およびPUTリクエストを理解している必要があります）
• 開発環境（cURL、Python、またはNode.jsで問題ありません）

Requests APIについて

リクエストとは？

Zendeskでは、リクエストはチケットに対するエンドユーザーの視点です。エージェントは内部メモ、カスタムフィールド、および非公開コメントを含む完全なチケットを表示しますが、エンドユーザーは公開コメントと限られた一連のフィールドのみを表示します。

リクエストのJSON形式は次のようになります。

{
  "id": 35436,
  "subject": "助けてください、プリンターが燃えています！",
  "description": "火は非常にカラフルです。",
  "status": "open",
  "priority": "normal",
  "type": "problem",
  "requester_id": 1462,
  "created_at": "2009-07-20T22:55:29Z",
  "updated_at": "2011-05-05T10:38:52Z"
}

主なプロパティは次のとおりです。

• subject（必須） - エンドユーザーに表示される件名
• description - リクエストの読み取り専用の最初のコメント
• status - new、open、pending、hold、solved、またはclosed
• priority - low、normal、high、またはurgent
• type - question、incident、problem、またはtask

出典：Zendesk Requests APIリファレンス

Requests APIとTickets API：どちらを使用する必要がありますか？

これは、統合の動作に影響を与える重要な決定です。内訳は次のとおりです。

**Agent Copilotの問題は重要です。**エンドユーザーの代わりにTickets APIを介してチケットを作成すると、Zendeskはそれをエージェントによって作成されたものとして解釈します。これは、Agent Copilotがトリガーされないことを意味します。Requests APIを使用すると、チケットはメールまたはメッセージングを介して作成されたチケットとまったく同じように動作します。

出典：内部メモ - APIリクエストとAgent Copilot

認証方法

エンドユーザー認証

エンドユーザーは、自分の認証情報を使用して認証できます。Requestsエンドポイントを使用する場合、管理者とエージェントはエンドユーザーとして扱われるため、同じ限定的なビューが表示されます。

APIトークン認証：

curl https://your-subdomain.zendesk.com/api/v2/requests.json \
  -u user@example.com/token:your_api_token_here

**重要な注意：**エンドユーザーが2017年9月17日以降にメールIDを追加し、メールアドレスを確認しなかった場合、リクエストを表示できません。この場合、APIは403応答を返します。

出典：Zendesk Requests APIリファレンス

エンドユーザーの代わりにリクエストを行う（管理者によるなりすまし）

エンドユーザーのチケットを管理者が作成する必要がある場合があります。これには、なりすましスコープを持つOAuthが必要です。

**ステップ1：**管理センターでOAuthクライアントを作成します（アプリと連携 > API > OAuthクライアント）

ステップ2：「impersonate」スコープでアクセストークンをリクエストします。

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
  -H "Content-Type: application/json" \
  -d '{
    "token": {
      "client_id": "your_client_id",
      "scopes": ["impersonate", "write"]
    }
  }' \
  -X POST -v -u {email_address}/token:{api_token}

**ステップ3：**リクエストにX-On-Behalf-Ofヘッダーを含めます。

curl https://z3napi.zendesk.com/api/v2/requests.json \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: customer@example.com" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "request": {
      "subject": "ヘルプリクエスト",
      "comment": {"body": "注文に関する支援が必要です"}
    }
  }'

**重要：**なりすまされたエンドユーザーは、既存のユーザープロファイルを持っている必要があります。そうでない場合、リクエストはinvalid_tokenエラーで失敗します。

出典：エンドユーザーの代わりにAPIリクエストを行う

匿名リクエスト

Zendesk管理者が有効にしている場合、認証なしでリクエストを作成できます。これは、公開連絡先フォームに役立ちます。

要件：

• 匿名リクエストは管理センターで有効にする必要があります
• 少なくとも名前を含むrequesterオブジェクトを含めます

{
  "request": {
    "requester": {"name": "匿名の顧客"},
    "subject": "助けて！",
    "comment": {"body": "プリンターが燃えています！"}
  }
}

**レート制限：**匿名リクエストは、トライアルアカウントの場合、1時間あたり5件に制限されています。

出典：リクエストの作成と管理

主要なAPIエンドポイント

リクエストのリスト

認証されたユーザーのすべてのリクエストを取得します。

GET /api/v2/requests

パラメーター：

• page - ページネーション（オフセットまたはカーソルベースをサポート）
• per_page - 1ページあたりのレコード数
• sort_by - "updated_at"または"created_at"
• sort_order - "asc"または"desc"

リクエストの作成

エンドユーザーの視点から新しいチケットを作成します。

POST /api/v2/requests

必須フィールド：

• subject - チケットの件名
• comment - 説明を含むbodyを持つオブジェクト

オプションフィールド：

• requester - 匿名リクエストの場合（名前、メールを含むオブジェクト）
• collaborators - CCするユーザーIDまたはメールのアレイ
• custom_fields - カスタムフィールド値のアレイ
• tags - 適用するタグのアレイ

リクエストの更新

コメントを追加するか、リクエストを解決済みとしてマークします。

PUT /api/v2/requests/{id}

書き込み可能なプロパティ：

• comment - 新しいコメントを追加する
• solved - 解決済みとしてマークするにはtrueに設定します（can_be_solved_by_meがtrueの場合のみ）
• additional_collaborators - リクエストにCCを追加する

コメントのリスト

会話履歴を表示します。

GET /api/v2/requests/{request_id}/comments

デフォルトでは、コメントは作成日で昇順にソートされます。

出典：Zendesk Requests APIリファレンス

コード例

cURLでリクエストを作成する

#!/bin/bash

SUBDOMAIN="your-subdomain"
EMAIL="admin@example.com"
TOKEN="your_api_token"

curl "https://${SUBDOMAIN}.zendesk.com/api/v2/requests.json" \
  -u "${EMAIL}/token:${TOKEN}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "request": {
      "subject": "注文状況の問い合わせ",
      "comment": {
        "body": "先週注文しましたが、状況を確認したいと思います。注文番号は#12345です。"
      },
      "collaborators": ["spouse@example.com"]
    }
  }'

Pythonでリクエストを作成する

import requests
import json

subdomain = "your-subdomain"
email = "admin@example.com"
api_token = "your_api_token"

url = f"https://{subdomain}.zendesk.com/api/v2/requests.json"

payload = {
    "request": {
        "subject": "技術サポートが必要です",
        "comment": {
            "body": "アカウントにログインできません。助けてもらえますか？"
        }
    }
}

auth = (f"{email}/token", api_token)
headers = {"Content-Type": "application/json"}

try:
    response = requests.post(url, json=payload, auth=auth, headers=headers)
    response.raise_for_status()

    data = response.json()
    print(f"リクエストが正常に作成されました！")
    print(f"チケットID：{data['request']['id']}")
    print(f"ステータス：{data['request']['status']}")

except requests.exceptions.HTTPError as err:
    print(f"HTTPエラー：{err}")
    print(f"応答：{response.text}")
except Exception as err:
    print(f"エラー：{err}")

Node.jsでリクエストを作成する

const axios = require('axios');

const config = {
  subdomain: 'your-subdomain',
  email: 'admin@example.com',
  apiToken: 'your_api_token'
};

async function createRequest() {
  const url = `https://${config.subdomain}.zendesk.com/api/v2/requests.json`;

  const payload = {
    request: {
      subject: '請求に関する質問',
      comment: {
        body: '今月、サブスクリプションの料金が2回請求されました。解決にご協力ください。'
      }
    }
  };

  try {
    const response = await axios.post(url, payload, {
      auth: {
        username: `${config.email}/token`,
        password: config.apiToken
      },
      headers: {
        'Content-Type': 'application/json'
      }
    });

    console.log('リクエストが正常に作成されました！');
    console.log(`チケットID：${response.data.request.id}`);
    console.log(`ステータス：${response.data.request.status}`);

  } catch (error) {
    console.error('リクエストの作成エラー：', error.response?.data || error.message);
  }
}

createRequest();

一般的なエラーとトラブルシューティング

403 Forbidden

これは、Requests APIを使用する際によくあるエラーです。一般的な原因：

• **未確認のメール：**エンドユーザーが2017年9月17日以降にメールを追加し、確認していません
• **不十分な権限：**エンドユーザーに許可されていないエンドポイントにアクセスしようとしています
• **なりすましスコープの欠落：**適切なOAuthスコープなしに、ユーザーの代わりにリクエストを作成しようとしています

**解決策：**Zendesk管理でユーザーのメールアドレスを確認するか、ユースケースに適した認証方法を使用していることを確認してください。

401 Unauthorized

• 無効なAPIトークンまたはOAuth認証情報
• トークンの有効期限が切れました（OAuthトークンには有効期間があります）
• ユーザーアカウントが停止または削除されました

**解決策：**認証情報を再確認し、必要に応じてトークンを再生成してください。

429 Rate Limit Exceeded

• 標準API：1分あたり700リクエスト
• 匿名リクエスト：1時間あたり5リクエスト（トライアルアカウント）

**解決策：**コードに指数バックオフを実装します。429を受け取ったら、再試行する前に待機します。

import time

def make_request_with_retry(url, payload, auth, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, auth=auth)
            response.raise_for_status()
            return response
        except requests.exceptions.HTTPError as err:
            if response.status_code == 429:
                wait_time = (2 ** attempt)  # 指数バックオフ
                print(f"レート制限されています。{wait_time}秒待機しています...")
                time.sleep(wait_time)
            else:
                raise
    raise Exception("最大再試行回数を超えました")

Agent Copilotが起動しない

ZendeskのAgent Copilotを使用している場合に、APIを介して作成されたチケットに対する応答が提案されない場合は、Requests APIではなくTickets APIを使用している可能性があります。

**解決策：**Tickets API（POST /api/v2/tickets.json）ではなく、Requests API（POST /api/v2/requests.json）に切り替えてください。

出典：内部メモ - APIリクエストとAgent Copilot

ベストプラクティス

エンドユーザー向けの統合にはRequests APIを使用する

カスタマーポータル、セルフサービスウィジェット、またはエンドユーザーがチケットを作成するインターフェイスを構築する場合は、常にRequests APIを使用してください。これにより、次のことが保証されます。

• 適切なAgent Copilotの動作
• 正しい最初の応答時間の計算
• メールで作成されたチケットとの一貫性のあるチケットライフサイクル

レート制限を適切に処理する

常に指数バックオフで再試行ロジックを実装します。ZendeskのAPIはすべての顧客で共有されており、積極的なポーリングにより、統合がレート制限されたり、ブロックされたりする可能性があります。

メール確認ステータスを検証する

ユーザーがリクエストを表示できるようにする前に、メールが確認されていることを確認してください。これはUsers APIを介して確認でき、必要に応じて確認を促すことができます。

認証情報を安全に保管する

APIトークンをフロントエンドコードにハードコードしたり、バージョン管理にコミットしたりしないでください。環境変数または安全なシークレット管理システムを使用してください。

ノーコードの代替手段を検討する

API統合の構築と維持には、かなりの開発リソースが必要です。カスタムポータルを構築するのではなく、サポート応答を自動化することが目標の場合は、Zendeskと直接統合し、コードを記述せずにAIを活用した自動化を提供するeesel AIなどのツールを検討してください。eesel AIは複雑な構成を必要としません。チームに招待するだけで、数分でビジネスを学習します。

当社は以下を提供します。

• 最前線のサポートを自律的に処理するAIエージェント
• エージェントが確認するための返信を下書きするAI Copilot
• チケットを自動的にタグ付け、ルーティング、優先順位付けするAIトリアージ
• Zendeskとのワンクリック統合（API開発は不要）

出典：eesel AI製品

Zendesk Requests APIで構築を開始する

Zendesk Requests APIを使用すると、エンドユーザーがサポートシステムと安全に対話できるようになります。Requests APIとTickets APIの違いを理解し、適切な認証を実装し、ベストプラクティスに従うことで、堅牢なセルフサービス統合を構築できます。

主なポイント：

• エンドユーザー向けの統合にはRequests APIを使用する
• 管理者がユーザーの代わりに行動する必要がある場合は、なりすましスコープでOAuthを実装する
• レート制限とエラーを適切に処理する
• 本番環境にデプロイする前に十分にテストする

詳細については、公式Zendesk Requests APIドキュメントをご覧ください。

開発オーバーヘッドなしでサポートを自動化したい場合は、eesel AIがどのように役立つかをご覧ください。当社のAIエージェントはZendeskと直接統合し、既存のドキュメントと過去のチケットから学習し、最前線のサポートの最大81％を自律的に処理できます。