APIを使用してZendeskトリガーを作成および更新する方法

ZendeskのUI（ユーザーインターフェース）を通じてトリガーを管理することは、一度限りの変更には適しています。しかし、複数の環境に同じトリガーをデプロイしたり、サンドボックスと本番環境間で構成を同期したり、トリガー管理を大規模に自動化する必要がある場合は、APIが不可欠になります。このガイドでは、認証から本番環境で使用できるコード例まで、Zendeskトリガーをプログラムで作成および更新する方法を説明します。

理解と判断を必要とするシナリオを処理するために、ますます複雑なトリガーチェーンを構築している場合は、AI（人工知能）を活用した代替手段を検討することをお勧めします。当社のZendesk連携は、ルールベースのトリガーでは対応が難しい、ニュアンスのある自動化を処理します。しかし、まずはAPIを使い始めましょう。

必要なもの

最初のAPIコールを行う前に、以下の基本事項を確認してください。

• 管理者アクセス権を持つZendeskアカウント。 APIトークンを作成してトリガーを管理するには、管理者権限が必要です。
• APIトークン。 管理センターから生成されます（ステップ1で説明します）。
• HTTPリクエストを行うためのツール。 テストにはcurlが最適です。Postmanは探索に役立ちます。HTTP機能を持つ任意のプログラミング言語（Python、Node.js、Ruby）は、自動化に適しています。
• JSONの基本的な理解。 APIはJSONペイロードを受け入れ、返します。

Zendeskトリガーの構造を理解する

Zendeskのトリガーは、単純なパターンに従います。**条件（conditions）**はトリガーがいつ実行されるかを定義し、**アクション（actions）**はトリガーが実行されたときに何が起こるかを定義します。「もしこうなら、そうする」というルールと考えてください。

基本的なJSON構造は次のとおりです。

{
  "trigger": {
    "title": "再オープン時に担当者に通知",
    "conditions": {
      "all": [
        {"field": "status", "operator": "changed", "value": "open"}
      ]
    },
    "actions": [
      {"field": "notification_user", "value": ["assignee_id", "チケットが再オープンされました", "お客様がこのチケットを再オープンしました。"]}
    ]
  }
}

conditionsオブジェクトには、all（論理AND）とany（論理OR）の2つの配列が含まれています。トリガーが発動するには、all配列内のすべての条件がtrueである必要があります。any配列内の条件は、1つだけtrueであれば十分です。

知っておくべき重要なフィールド：

• title: トリガー名（必須）
• conditions: トリガーがいつ実行されるかを定義します（必須）
• actions: トリガーが何をするか（必須）
• active: 有効/無効を切り替えるブール値（デフォルトはtrue）
• category_id: トリガーをカテゴリに整理します（オプション）
• position: 実行順序を制御します（数値が小さいほど最初に実行されます）

重要な区別：POSTでトリガーを作成するときは、完全なトリガーオブジェクトを送信します。PUTでトリガーを更新するときは、変更するフィールドだけでなく、すべての条件とアクションを含める必要があります。更新はトリガー構成全体を置き換えます。

ステップ1：API認証を設定する

Zendeskは認証にAPIトークンを使用します。トークンを生成する方法は次のとおりです。

1. 管理センター > アプリとインテグレーション > API > Zendesk APIに移動します。
2. 設定タブをクリックし、「トークンアクセス」が有効になっていることを確認します。
3. (+) APIトークンを追加ボタンをクリックします。
4. トークンに「トリガー管理」のようなわかりやすい名前を付けます。
5. トークンをすぐにコピーします（再度表示されることはありません）。

**トークンの制限：**アカウントごとに最大256個のアクティブなトークンを持つことができます。その制限に達した場合は、新しいトークンを作成する前に、既存のトークンを削除する必要があります。

**認証形式：**メールアドレスとトークンを/token:を区切り文字として組み合わせて使用​​します。

jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

簡単なリクエストで認証をテストします。

curl https://your-subdomain.zendesk.com/api/v2/triggers.json \
  -u jdoe@example.com/token:YOUR_API_TOKEN

トリガーを含むJSONレスポンス（またはトリガーがない場合は空の配列）が表示された場合は、認証されており、続行する準備ができています。

セキュリティのベストプラクティス：

• トークンはコードではなく、環境変数に保存します。
• 使用していないトークンは削除します。
• トークンを定期的にローテーションします。
• 異なる環境（開発、ステージング、本番）には、個別のトークンを使用します。

ステップ2：最初のトリガーを作成する

次に、API経由でトリガーを作成しましょう。「緊急」という単語を含むチケットを特定のグループに割り当てる簡単なトリガーを作成します。

エンドポイントはPOST /api/v2/triggersです。

curl https://your-subdomain.zendesk.com/api/v2/triggers.json \
  -u jdoe@example.com/token:YOUR_API_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "trigger": {
      "title": "緊急チケットをTier 2にルーティング",
      "conditions": {
        "all": [
          {"field": "comment_includes_word", "operator": "includes", "value": "urgent"},
          {"field": "status", "operator": "is", "value": "new"}
        ]
      },
      "actions": [
        {"field": "group_id", "value": "20455932"},
        {"field": "priority", "value": "high"}
      ]
    }
  }'

何が起こっているかを詳しく見てみましょう。

**条件：**トリガーは、チケットが新規（status is new）であり、コメントに「緊急」（comment_includes_word includes urgent）という単語が含まれている場合にのみ発動します。両方の条件はall配列にあるため、trueである必要があります。

**アクション：**条件が満たされると、トリガーはチケットをグループID 20455932に割り当て、優先度を「高」に設定します。

APIレスポンスには、割り当てられたIDを持つ作成されたトリガーが含まれています。

{
  "trigger": {
    "id": 360012345678,
    "title": "緊急チケットをTier 2にルーティング",
    "active": true,
    "conditions": {...},
    "actions": {...},
    "position": 15,
    "created_at": "2026-02-24T10:30:00Z"
  }
}

そのIDを保存します。更新に必要になります。

**トリガーのテスト：**説明に「緊急」という単語を含むテストチケットを作成します。正しいグループに割り当てられ、優先度が「高」に設定されていることを確認します。動作しない場合は、トリガーの位置を確認してください（トリガーは順番に実行され、別のトリガーが干渉している可能性があります）。

ステップ3：既存のトリガーを更新する

トリガーの更新には、特に注意が必要です。PUT /api/v2/triggers/{id}エンドポイントは、トリガー構成全体を置き換えます。変更するフィールドのみを送信すると、他のすべての条件とアクションが失われます。

トリガーを安全に更新する方法は次のとおりです。

1. 既存のトリガーを取得して、現在の状態を取得します。
2. 変更するフィールドを修正します。
3. 完全なオブジェクトをPUTで返送します。

curl https://your-subdomain.zendesk.com/api/v2/triggers/360012345678.json \
  -u jdoe@example.com/token:YOUR_API_TOKEN

curl https://your-subdomain.zendesk.com/api/v2/triggers/360012345678.json \
  -u jdoe@example.com/token:YOUR_API_TOKEN \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "trigger": {
      "title": "緊急および重大なチケットをTier 2にルーティング",
      "conditions": {
        "all": [
          {"field": "comment_includes_word", "operator": "includes", "value": "urgent critical"},
          {"field": "status", "operator": "is", "value": "new"}
        ]
      },
      "actions": [
        {"field": "group_id", "value": "20455932"},
        {"field": "priority", "value": "high"},
        {"field": "set_tags", "value": "urgent-routing"}
      ]
    }
  }'

キーワードに「重大」を追加し、タグアクションを追加したことに注意してください。変更だけでなく、条件とアクションの配列全体が含まれています。

**更新の競合の処理：**2つのプロセスが同じトリガーを同時に更新しようとすると、409 Conflictエラーが発生する可能性があります。トリガーはチケットが使用するsafe_updateパラメーターをサポートしていませんが、変更を行う前にupdated_atタイムスタンプを確認することで、独自の競合検出を実装できます。

ステップ4：一括操作

トリガーを大規模に管理する場合、個別のAPIコールは非効率になります。Zendeskは、一般的な操作のための一括エンドポイントを提供します。

トリガーの並べ替え

トリガーの位置によって実行順序が決まります。複数のトリガーを移動するには：

curl https://your-subdomain.zendesk.com/api/v2/triggers/update_many.json \
  -u jdoe@example.com/token:YOUR_API_TOKEN \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "triggers": [
      {"id": 360012345678, "position": 1},
      {"id": 360012345679, "position": 2},
      {"id": 360012345680, "position": 3}
    ]
  }'

一括でのアクティブ化と非アクティブ化

curl https://your-subdomain.zendesk.com/api/v2/triggers/update_many.json \
  -u jdoe@example.com/token:YOUR_API_TOKEN \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "triggers": [
      {"id": 360012345678, "active": false},
      {"id": 360012345679, "active": false}
    ]
  }'

一括操作のユースケース：

• 環境全体へのトリガー構成のデプロイ
• メンテナンス中のトリガーの一時的な無効化
• 新しいトリガーを追加した後のトリガーの並べ替え
• Zendeskインスタンス間のトリガーの移行

**パフォーマンスに関する考慮事項：**一括更新は非同期で処理されます。APIは、完了を確認するためにポーリングできるジョブステータスを返します。大規模な操作（100個以上のトリガー）の場合は、より小さなバッチに分割することを検討してください。

一般的なパターンと例

ニーズに合わせて調整できる4つの実用的なトリガーパターンを次に示します。

パターン1：チケットタイプに基づく自動割り当て

{
  "trigger": {
    "title": "インシデントをL3チームに割り当てる",
    "conditions": {
      "all": [
        {"field": "type", "operator": "is", "value": "incident"},
        {"field": "status", "operator": "is", "value": "new"}
      ]
    },
    "actions": [
      {"field": "group_id", "value": "20456000"},
      {"field": "assignee_id", "value": "296220096"}
    ]
  }
}

パターン2：優先度の変更を伴うエスカレーショントリガー

{
  "trigger": {
    "title": "優先度の高いチケットをエスカレートする",
    "conditions": {
      "all": [
        {"field": "priority", "operator": "is", "value": "high"},
        {"field": "status", "operator": "is", "value": "open"},
        {"field": "hours_since_open", "operator": "greater_than", "value": "4"}
      ]
    },
    "actions": [
      {"field": "priority", "value": "urgent"},
      {"field": "notification_group", "value": ["20456001", "エスカレーション：優先度の高いチケット", "優先度の高いチケットが4時間以上オープンになっています。"]}
    ]
  }
}

パターン3：カスタムメッセージを使用した通知トリガー

{
  "trigger": {
    "title": "VIPチケットに関するマネージャーへの通知",
    "conditions": {
      "all": [
        {"field": "current_tags", "operator": "includes", "value": "vip"},
        {"field": "update_type", "value": "Create"}
      ]
    },
    "actions": [
      {"field": "notification_user", "value": ["296220100", "新しいVIPチケット：{{ticket.title}}", "VIPのお客様から新しいチケットが送信されました。\n\nチケットID：{{ticket.id}}\nリクエスター：{{ticket.requester.name}}\n優先度：{{ticket.priority}}"]}
    ]
  }
}

パターン4：外部連携のためのWebhookトリガー

{
  "trigger": {
    "title": "チケットをCRMに送信",
    "conditions": {
      "all": [
        {"field": "status", "operator": "changed", "value": "solved"}
      ]
    },
    "actions": [
      {"field": "notification_webhook", "value": ["01G8Z5K1234567890ABCDEF", "{\"ticket_id\": \"{{ticket.id}}\", \"status\": \"{{ticket.status}}\", \"solved_at\": \"{{ticket.solved_at}}\"}"]}
    ]
  }
}

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

Triggers APIを使用する場合、次のHTTPステータスコードが発生します。

一般的な問題と修正：

**無効なJSONエラー：**APIはJSON形式に厳密です。一般的な間違いには、末尾のコンマ、引用符で囲まれていないキー、文字列内の特殊文字の不適切なエスケープなどがあります。

**検証エラー（422）：**これらは通常、条件またはアクションフィールドが存在しないか、無効な値を持っていることを意味します。条件リファレンスおよびアクションリファレンスに対してフィールド名を再確認してください。

**作成後にトリガーが発動しない：**トリガーは位置順に実行されることを忘れないでください。別のトリガーが最初にチケットを変更した場合、新しいトリガーの条件が一致しなくなる可能性があります。トリガーをより早い位置に移動してみてください。

**レート制限：**Zendeskは、ほとんどのエンドポイントに対して1分あたり700件のリクエストを許可しています。制限に達した場合は、指数関数的な遅延でバックオフして再試行してください。

APIトリガー管理のベストプラクティス

複数のプロジェクトでTriggers APIを操作した後、時間を節約し、頭痛の種を防ぐためのプラクティスを次に示します。

**トリガー構成のバージョン管理を行います。**トリガーJSONをGitに保存します。これにより、トリガーの変更に対するコードレビュー、何かが壊れた場合の簡単なロールバック、および特定の条件が存在する理由のドキュメントが可能になります。

**最初にサンドボックスでテストします。**本番環境にデプロイする前に、常にサンドボックス環境でトリガーロジックを検証してください。トリガーの相互作用は複雑になる可能性があり、単独で動作するものが既存のトリガーと競合する可能性があります。

**一貫した命名規則を使用します。**UIでスキャンできるように、関数でトリガーにプレフィックス（「ROUTE-」、「NOTIFY-」、「ESCALATE-」）を付けます。トリガーが特定の問題に関連付けられている場合は、チケット参照をコミットメッセージに含めます。

**トリガーの依存関係を文書化します。**トリガーが相互作用する場合（あるトリガーが別のトリガーがチェックするタグを設定する場合）、これらの関係を文書化します。1つのトリガーへの変更は、他のトリガーを微妙な方法で壊す可能性があります。

**トリガーのパフォーマンスを監視します。**使用状況のサイドロード（?include=usage_24h）を使用して、トリガーが発動する頻度を追跡します。発動しないトリガーには、誤った条件がある可能性があります。常に発動するトリガーは、不必要な負荷を引き起こしている可能性があります。

**UIとAPIをいつ使用するかを知っておいてください。**一度限りの変更や実験にはUIを使用します。環境全体へのデプロイ、一括更新、およびバージョン管理したいものにはAPIを使用します。

自動化にeesel AIを検討する場合

トリガーは、単純なルールベースの自動化に適しています。しかし、それらには限界があります。コンテキスト、感情、または意図を理解できません。顧客が実際に何を必要としているかを理解するのではなく、キーワードの正確な一致が必要です。

eesel AIでは、自動化へのアプローチが異なります。厳格なトリガーロジックを構築する代わりに、ビジネスを学習し、インテリジェントな意思決定を行うAIチームメイトを採用します。

複雑なトリガーの代わりに、またはその横に、当社のZendesk連携を検討する時期は次のとおりです。

**理解を必要とする複雑な自動化。**感情、緊急性、または顧客の意図に基づいてチケットをエスカレートしたいですか？当社のAIは、フィールド値だけでなく、チケットの内容を読み取り、理解します。

自然言語条件。「タグがXと等しい場合」の代わりに、「顧客が請求について不満を持っているように見える場合」のようなことを言うことができます。AIはコンテキストとニュアンスを理解します。

**自動チケット解決。**トリガーは通知とタグ付けを行うことができますが、当社のAIエージェントは実際にチケットを自律的に解決できます。過去のチケットとヘルプセンターから学習し、手動設定なしで正確な回答を提供します。

**段階的な自動化。**エージェントレビューのためにAIが返信を下書きすることから始めます。それが証明されたら、直接応答を送信させます。最終的には、最前線のサポート全体を処理できます。ペースはあなたがコントロールできます。

ますます複雑なトリガーチェーンを構築している場合は、別のアプローチを検討する時期かもしれません。eesel AIがZendeskとどのように連携するかをご覧ください。