freshdesk-api

Freshdesk API

概要

Freshdesk のヘルプデスクプラットフォームと REST API v2 を使用して連携機能を構築できます。サポートチケット、連絡先、会社、エージェントを管理し、ワークフローを自動化できます。この API は、フィルタリング、ページネーション、埋め込みデータに対応し、主要なすべてのリソースで CRUD 操作を実行できます。

利用する場面

• ヘルプデスク連携機能やサポートダッシュボードを構築する
• サポートチケットのデータを抽出して分析する
• チケットの振り分け、割り当て、更新を自動化する
• 連絡先や会社を CRM システムと同期する
• サポート指標に関するカスタムレポートを作成する
• チャットボットや AI を活用したサポートツールを実装する
• Freshdesk との間でデータを移行する

前提条件

API キーの設定

1. 管理者として Freshdesk にログインします
2. プロフィール画像をクリックし、プロフィール設定を選択します
3. 右側のサイドバーでAPI キーを確認します
4. 安全に保管します（バージョン管理に絶対にコミットしないでください）

# Set environment variable
export FRESHDESK_API_KEY="your-api-key-here"
export FRESHDESK_DOMAIN="yourcompany"  # From yourcompany.freshdesk.com

必要なツール

• HTTP リクエスト用の curl
• JSON 解析用の jq（macOS では brew install jq）
• SDK を使用する場合：Python 3.6 以降、Node.js 14 以降、または Ruby 2.7 以降

API ベース URL

https://{domain}.freshdesk.com/api/v2/

{domain} を Freshdesk のサブドメイン（例：acme.freshdesk.com の場合は acme）に置き換えます。

認証

Freshdesk は HTTP Basic 認証を使用します。API キーをユーザー名、X をパスワードとして指定します。

curl の例

# Using -u flag (username:password)
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets"

# Using Authorization header
curl -H "Authorization: Basic $(echo -n "$FRESHDESK_API_KEY:X" | base64)" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets"

ヘッダー

常に次のヘッダーを含めます。

Content-Type: application/json

クイックスタート

すべてのチケットを取得する

curl -u "$FRESHDESK_API_KEY:X" \
  -H "Content-Type: application/json" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets"

チケットを作成する

curl -u "$FRESHDESK_API_KEY:X" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "subject": "Support needed",
    "description": "Details of the issue...",
    "email": "[email protected]",
    "priority": 2,
    "status": 2
  }' \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets"

連絡先を取得する

curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/contacts/12345"

チケットを検索する

# Search by status and priority
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/search/tickets?query=\"status:2 AND priority:3\""

主要なエンドポイント

エンドポイント	説明
/tickets	チケットの作成、一覧表示、更新、削除
/contacts	顧客の連絡先を管理
/companies	会社／組織のレコードを管理
/agents	サポートエージェントの表示と管理
/groups	エージェントグループを管理
/conversations	チケットへの返信、メモ、転送
/time_entries	チケットの時間追跡
/surveys/satisfaction_ratings	顧客満足度データ
/products	製品カタログの管理
/business_hours	営業時間の設定
/email_configs	メール設定
/sla_policies	SLA ポリシーの管理
/canned_responses	定型返信テンプレート
/ticket_fields	カスタムチケットフィールド

チケット操作の詳細については、references/tickets-api.md を参照してください。 連絡先や会社の管理については、references/contacts-companies.md を参照してください。

レート制限

API バージョンごとの制限

バージョン	制限
API v1	1 時間あたり 1000 回
API v2	1 分あたり、プランに基づく
トライアルプラン	1 分あたり 50 回

レート制限ヘッダー

各レスポンスには次のヘッダーが含まれます。

ヘッダー	説明
X-Ratelimit-Total	1 分あたりに許可される呼び出しの合計数
X-Ratelimit-Remaining	今分に残っている呼び出し数
X-Ratelimit-Used-CurrentRequest	このリクエストで使用したクレジット数

レート制限への対処

#!/usr/bin/env bash
# Retry with exponential backoff for 429 errors

max_retries=3
retry_count=0

while [ "$retry_count" -lt "$max_retries" ]; do
  response=$(curl -s -w "\n%{http_code}" -u "$FRESHDESK_API_KEY:X" \
    "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets")

  http_code=$(echo "$response" | tail -1)
  body=$(echo "$response" | sed '$d')

  if [ "$http_code" = "200" ]; then
    echo "$body"
    exit 0
  elif [ "$http_code" = "429" ]; then
    delay=$((2 ** retry_count))
    echo "Rate limited. Retrying in ${delay}s..." >&2
    sleep "$delay"
    retry_count=$((retry_count + 1))
  else
    echo "Error: HTTP $http_code" >&2
    echo "$body" >&2
    exit 1
  fi
done

echo "Max retries exceeded" >&2
exit 1

クレジットシステム

一部の操作では、複数の API クレジットを消費します。

• 基本リクエスト：1 クレジット
• 埋め込みデータを含める場合（include= パラメーター）：指定した項目ごとに +1 クレジット
• 例：?include=requester,company は合計 3 クレジットを消費します

ページネーション

クエリパラメーター

パラメーター	デフォルト	最大値	説明
page	1	-	ページ番号（1 始まり）
per_page	30	100	1 ページあたりの結果数

例：すべてのチケットをページごとに取得する

page=1
while true; do
  response=$(curl -s -u "$FRESHDESK_API_KEY:X" \
    "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?page=$page&per_page=100")

  count=$(echo "$response" | jq length)

  if [ "$count" -eq 0 ]; then
    break
  fi

  echo "$response" | jq '.[] | {id, subject, status}'
  page=$((page + 1))
done

Link ヘッダー

レスポンスには、ページ間を移動するための Link ヘッダーが含まれます。

Link: <https://domain.freshdesk.com/api/v2/tickets?page=2>; rel="next"

フィルタリングと埋め込み

フィルターパラメーター

一覧エンドポイントで利用できる一般的なフィルター：

パラメーター	例	説明
filter	new_and_my_open	定義済みフィルター
requester_id	12345	リクエスターでフィルタリング
company_id	67890	会社でフィルタリング
updated_since	2024-01-01T00:00:00Z	指定日以降に更新された項目

定義済みのチケットフィルター

# New and open tickets assigned to me
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?filter=new_and_my_open"

# All unresolved tickets
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?filter=all_unresolved"

# Tickets updated in last 30 days
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?updated_since=2024-11-01T00:00:00Z"

Include（関連データの埋め込み）

関連オブジェクトを埋め込んで、API 呼び出しを減らします。

# Include requester and company with ticket
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets/123?include=requester,company"

# Include stats with ticket list
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?include=stats"

チケットで利用可能な include：requester、company、stats、conversations、description

Search API

Search API を使用すると、チケット、連絡先、会社を対象に複雑なクエリを実行できます。

構文

curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/search/tickets?query=\"<query>\""

クエリの例

# Tickets with specific status and priority
"status:2 AND priority:3"

# Tickets from a specific requester
"requester_email:'[email protected]'"

# Tickets created in date range
"created_at:>'2024-01-01' AND created_at:<'2024-02-01'"

# Tickets with specific tag
"tag:'urgent'"

# Tickets assigned to specific agent
"agent_id:12345"

# Full-text search in subject and description
"~'password reset'"

検索演算子

演算子	説明
AND	両方の条件に一致する
OR	いずれかの条件に一致する
:	等しい
:>	より大きい
:<	より小さい
~	全文検索

チケットのステータスと優先度の値

ステータス

値	ステータス
2	オープン
3	保留中
4	解決済み
5	クローズ

優先度

値	優先度
1	低
2	中
3	高
4	緊急

送信元

値	送信元
1	メール
2	ポータル
3	電話
7	チャット
8	Mobihelp
9	フィードバックウィジェット
10	送信メール

エラー処理

HTTP ステータスコード

コード	意味	対処
200	成功	レスポンスを処理する
201	作成済み	リソースが正常に作成されました
204	コンテンツなし	削除に成功しました
400	不正なリクエスト	リクエスト本文／パラメーターを確認する
401	認証されていない	API キーを確認する
403	禁止	権限を確認する
404	見つからない	リソース ID を確認する
409	競合	リソースはすでに存在します
429	レート制限	待機して再試行する
500	サーバーエラー	間隔を空けて再試行する

エラーレスポンスの形式

{
  "description": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "It should be a valid email address.",
      "code": "invalid_value"
    }
  ]
}

Webhook

Freshdesk は、チケットのイベント発生時に Webhook 通知を送信できます。管理者 → 自動化 → Webhook で Webhook を設定してください。

イベントの種類

• チケット作成
• チケット更新
• エージェントの返信
• 顧客の返信
• メモ追加
• チケット解決／クローズ

Webhook ペイロードの例

{
  "freshdesk_webhook": {
    "ticket_id": 12345,
    "ticket_subject": "Support needed",
    "ticket_status": "Open",
    "ticket_priority": "Medium",
    "ticket_requester_email": "[email protected]",
    "triggered_event": "ticket_created"
  }
}

Webhook の設定について詳しくは、references/webhooks-automation.md を参照してください。

ベストプラクティス

パフォーマンス

1. ポーリングではなく Webhook を使用する - イベントにリアルタイムで対応します
2. 操作をバッチ処理する - 利用可能な場合は一括エンドポイントを使用します
3. 静的データをキャッシュする - エージェント一覧やチケットフィールドはほとんど変更されません
4. include パラメーターを使用する - データを埋め込んで API 呼び出しを減らします
5. 効率的にページネーションする - 一括操作では最大 per_page=100 を使用します

セキュリティ

1. API キーを環境変数に保存する - ハードコードしないでください
2. HTTPS のみを使用する - すべての API 呼び出しで HTTPS を使用する必要があります
3. キーを定期的にローテーションする - 90 日ごとに API キーを再生成します
4. API キーのスコープを制限する - 最小限の権限を持つエージェントアカウントを使用します

信頼性

1. 間隔を空けた再試行を実装する - 429 および 5xx エラーに対処します
2. レート制限ヘッダーを確認する - 制限に達する前に一時停止します
3. レスポンスを検証する - エラーオブジェクトがないか確認します
4. API 呼び出しをログに記録する - 使用状況の追跡と問題のデバッグに役立てます

データ処理

1. null フィールドを処理する - API はフィールドを省略せず、null を返します
2. タイムスタンプを UTC として解析する - 形式：YYYY-MM-DDTHH:MM:SSZ
3. カスタムフィールドを検証する - 送信前にフィールドの型を確認します
4. ユーザー入力をサニタイズする - 説明へのインジェクションを防止します

SDK とライブラリ

公式／コミュニティ SDK

言語	パッケージ	インストール
Python	python-freshdesk	pip install python-freshdesk
Node.js	node-freshdesk-api	npm install node-freshdesk-api
Ruby	freshdesk-ruby	gem install freshdesk
PHP	公式サンプル	Freshdesk のドキュメントを参照
Java	公式サンプル	Freshdesk のドキュメントを参照

詳しいコード例については、references/sdk-examples.md を参照してください。

よくあるワークフロー

すべてのチケットを JSON にエクスポートする

#!/usr/bin/env bash
# Export all tickets to tickets.json

page=1
echo "[" > tickets.json
first=true

while true; do
  response=$(curl -s -u "$FRESHDESK_API_KEY:X" \
    "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?page=$page&per_page=100&include=description")

  count=$(echo "$response" | jq length)
  [ "$count" -eq 0 ] && break

  if [ "$first" = true ]; then
    first=false
  else
    echo "," >> tickets.json
  fi

  echo "$response" | jq '.[]' | paste -sd ',' - >> tickets.json
  page=$((page + 1))
  sleep 0.5  # Respect rate limits
done

echo "]" >> tickets.json
echo "Exported $((page - 1)) pages of tickets"

CSV から連絡先を同期する

#!/usr/bin/env bash
# Import contacts from contacts.csv (name,email,company_id)

while IFS=, read -r name email company_id; do
  curl -s -u "$FRESHDESK_API_KEY:X" \
    -H "Content-Type: application/json" \
    -X POST \
    -d "{\"name\":\"$name\",\"email\":\"$email\",\"company_id\":$company_id}" \
    "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/contacts"
  sleep 0.5
done < contacts.csv

チケットの指標を取得する

# Get resolution time stats for closed tickets this month
curl -s -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/search/tickets?query=\"status:5 AND created_at:>'2024-12-01'\"" \
  | jq '[.results[] | .stats.resolved_at as $r | .created_at as $c |
    (($r | fromdateiso8601) - ($c | fromdateiso8601)) / 3600] |
    {count: length, avg_hours: (add / length)}'

リソース

• Freshdesk API ドキュメント
• API v2 リファレンス
• Webhook ガイド
• レート制限に関する FAQ
• Python SDK
• Node.js SDK
• Ruby SDK

リファレンスファイル

エンドポイントの詳細なドキュメントについては、以下を参照してください。

• チケット API リファレンス - チケットの CRUD、会話、時間記録の全項目
• 連絡先と会社 - 連絡先と会社の管理
• Webhook と自動化 - Webhook の設定と自動化ルール
• SDK コード例 - Python、Node.js、Ruby の例