ZendeskのWeb API経由でトリガの設定を確認・更新する方法

こんにちは、ゲームソリューショングループの入井です。

Zendeskでは、トリガを設定することによって、一定の条件を満たした際に様々な処理をオートメーションで実行することが可能です。

トリガは非常に便利な機能である反面、その設定内容は複雑になりがちで、現在どのような設定がされているのかの把握が難しく、設定確認のためにいちいちGUIの管理画面を開くのも手間がかかります。また、他の管理者によって設定が変えられていても、それに気づくことは難しいです。

トリガは、Zendeskが用意しているWeb APIから設定内容の確認・更新が可能です。細かな条件や処理の内容まですべてJSONによってテキストで表現されているので、上手くAPIを活用すれば設定内容を自動的にドキュメント化する仕組みが作成できます。例えば、設定内容をGitで管理するような仕組みを作れば、変更の差分を後からでも把握できるようになります。

なお、Zendesk APIを使用するための認証の方法については、以下の記事を参考にしてください。

APIリクエストを認証するにはどうすればよいですか？ – Zendeskヘルプ

トリガへのWeb APIでのアクセス

取得

トリガの設定内容を取得するには、以下のエンドポイントにアクセスします。

• GET https://[subdomain].zendesk.com/api/v2/triggers
  • トリガをリスト形式で取得
• GET https://[subdomain].zendesk.com/api/v2/triggers[trigger_id]
  • 指定したIDのトリガを単体取得

トリガのレスポンス形式は、以下のような形です。

{
      "url": "https://[subdomain].zendesk.com/api/v2/triggers/111111.json",
      "id": 111111,
      "title": "担当者への通知 - 割り当て",
      "active": false,
      "updated_at": "2023-01-10T09:11:01Z",
      "created_at": "2020-04-15T09:26:21Z",
      "default": false,
      "actions": [
          {
              "field": "notification_user",
              "value": [
                  "assignee_id",
                  "[{{ticket.account}}] 割り当て: {{ticket.title}}",
                  "あなたはこのチケット（No.#{{ticket.id}}）の担当者になりました。\n\n{{ticket.comments_formatted}}"
              ]
          }
      ],
      "conditions": {
          "all": [
              {
                  "field": "assignee_id",
                  "operator": "changed",
                  "value": null
              },
              {
                  "field": "assignee_id",
                  "operator": "is_not",
                  "value": "current_user"
              }
          ],
          "any": []
      },
      "description": null,
      "position": 8,
      "raw_title": "担当者への通知 - 割り当て",
      "category_id": "999999"
  }

こちらは、実際に弊社のZendesk検証環境内に設定されているトリガから取得した情報です。チケットの担当者として割り当てられたエージェントに対し、メールで通知を送るトリガです。

“conditions”内にトリガの実行条件が書かれています。”all”内の条件を全て満たし”any”内の条件のいずれかを満たした際にアクションが実行される形です。

  {
      "field": "assignee_id",
      "operator": "changed",
      "value": null
  },

こちらは、「担当者が変更された」を意味する条件です。値の設定は必要ないので"value"がnullとなっています。

 {
      "field": "assignee_id",
      "operator": "is_not",
      "value": "current_user"
  }

こちらは、「担当者がチケット更新を行ったユーザーではない」を意味する条件です。自分でチケット担当者を自分に割り当てた際は通知の必要がないため、この条件が入っています。

実行されるアクションについては、”actions”に入っています。

  {
      "field": "notification_user",
      "value": [
          "assignee_id",
          "[{{ticket.account}}] 割り当て: {{ticket.title}}",
          "あなたはこのチケット（No.#{{ticket.id}}）の担当者になりました。\n\n{{ticket.comments_formatted}}"
      ]
  }

“notification_user”はメール通知の実行を表し、具体的な内容は”value”配列内で通知対象、メール件名、メール本文という順番で設定されています。{{ticket.account}}などはプレースホルダーです。実際のアクション実行時は、対応したテキストが動的に割り当てられます。

なお、こちらのトリガ設定を管理画面上で見ると以下の画像のような形となっています。

作成・更新

トリガの設定内容を更新するには、以下のエンドポイントにアクセスします。

• POST https://[subdomain].zendesk.com/api/v2/triggers
  • トリガを新しく作成
• PUT https://[subdomain].zendesk.com/api/v2/triggers/[trigger_id]
  • 既存のトリガの設定内容更新

具体的な作成・更新内容はリクエストボディに付けて送ります。

オブジェクトの構造は取得時と同様で、設定したい内容を各プロパティに入れます。

具体的な設定値については以下のドキュメントを参考にしてください。

Conditions reference | Zendesk Developer Docs

Actions reference | Zendesk Developer Docs

まとめ

トリガの設定内容にWeb API経由でアクセスする方法について書きました。

なお、トリガと自動化は実行タイミングが異なるだけで、基本的な設定内容はほとんど同様なので、自動化についてもトリガとほとんど同じ方法でアクセスできます。

管理画面から簡単に設定変更できるのはZendeskの強いですが、管理上辛い部分が出てきた場合はWeb APIを活用した運用方法についても検討をしてみてください。